claude-dev-env 1.94.0 → 2.0.0

package/agents/code-verifier.md

@@ -33,7 +33,7 @@ On Windows the same file sits at %USERPROFILE%\.claude\hooks\blocking\verificati
 
 The printed hash commits to every changed and untracked file's content in the verified work tree, so it names that surface no matter which directory you or the committer run from. If the CLI prints an empty-surface or wrong-work-tree error and no hash, you are pointed at a work tree with no changes versus origin/main — re-run with the branch mode to locate the correct work tree.
 
-As the last step before the verdict, put your draft verdict through one best-effort strongest-tier validation pass. Spawn a single validation subagent through the Task tool as the `Explore` agent type at the strongest reachable tier: set the Task `subagent_type` to `Explore`, detect the host profile first per `~/.claude/_shared/advisor/advisor-protocol.md` — the source of truth for host detection, the ladder, and its aliases — then on a Claude host pick the strongest reachable tier on the Fable → Opus → Sonnet → Haiku ladder and on a Grok host use the single Grok tier, and set the Task `model:` field to that tier's alias. The `Explore` type carries no Edit or Write tools and cannot spawn further agents, so the harness itself holds the validator to the no-edit, no-spawn contract the next paragraph names. Hand it the draft verdict together with your evidence — every command you ran with its output, and your two-way diff-to-task mapping — and state that its task is adversarial verification of that supplied draft verdict: refute it against the supplied evidence rather than discover code, naming any gate you misread, any task item you mapped wrong, or any finding that does not hold. When the spawn is unavailable — a Task tool error, an unreachable tier at every rung, or this subagent being barred from spawning further agents — skip the validation pass and emit the draft verdict as it stands, noting the skip in your final message; a spawn failure never blocks the verdict fence from being emitted.
+As the last step before the verdict, put your draft verdict through one best-effort strongest-tier validation pass. Spawn a single validation subagent through the Task tool as the `Explore` agent type at the strongest reachable tier: set the Task `subagent_type` to `Explore`, detect the host profile first per `~/.claude/_shared/advisor/advisor-protocol.md` — the source of truth for host detection, the ladder, and its aliases — then on a Claude host pick the strongest reachable tier on the Fable → Opus → Sonnet → Haiku ladder and on a third-party host use the single third-party tier, and set the Task `model:` field to that tier's alias. The `Explore` type carries no Edit or Write tools and cannot spawn further agents, so the harness itself holds the validator to the no-edit, no-spawn contract the next paragraph names. Hand it the draft verdict together with your evidence — every command you ran with its output, and your two-way diff-to-task mapping — and state that its task is adversarial verification of that supplied draft verdict: refute it against the supplied evidence rather than discover code, naming any gate you misread, any task item you mapped wrong, or any finding that does not hold. When the spawn is unavailable — a Task tool error, an unreachable tier at every rung, or this subagent being barred from spawning further agents — skip the validation pass and emit the draft verdict as it stands, noting the skip in your final message; a spawn failure never blocks the verdict fence from being emitted.
 
 This validation pass is terminal: the `Explore` type gives the validation subagent no way to spawn a further agent or edit a file, so it answers with prose only. When it refutes any part, re-check that part yourself against the commands and the diff, and correct the verdict before you emit it. When it refutes nothing, the draft verdict stands. Then emit the fenced verdict block below — it stays the last thing in your message so the verifier_verdict_minter hook reads it.
 

package/bin/CLAUDE.md

@@ -6,7 +6,8 @@ The installer and its companion modules. Running `npx claude-dev-env` (or `node
 
 | File | Purpose |
 |---|---|
-| `install.mjs` | Main installer: discovers install groups, copies content directories (`rules`, `docs`, `commands`, `agents`, `system-prompts`, `scripts`, `_shared`, `audit-rubrics`), merges hooks into `settings.json`, installs skills, runs `git_hooks_installer.mjs` and `install_mypy_ini.mjs` |
+| `install.mjs` | Main installer: discovers install groups, copies content directories (`rules`, `docs`, `commands`, `agents`, `system-prompts`, `scripts`, `_shared`, `audit-rubrics`), merges hooks into `settings.json`, installs skills, prunes retired skills on a full install, runs `git_hooks_installer.mjs` and `install_mypy_ini.mjs` |
+| `ever-shipped-skills.mjs` | Static `EVER_SHIPPED_SKILL_NAMES` set of every top-level skill directory name the package has shipped; the installer subtracts the current skill set from it to prune retired skills left under `~/.claude/skills` |
 | `expand_home_directory_tokens.mjs` | Expands residual `$HOME` / `${HOME}` / `~/` tokens in settings.json hook and statusLine commands to absolute home paths at install time (literal-safe for homes that contain `$`) |
 | `git_hooks_installer.mjs` | Installs or updates the `pre-commit`, `pre-push`, and `post-commit` Git hooks in the user's git config; writes hook scripts that delegate to the installed Python hooks |
 | `install_mypy_ini.mjs` | Writes `~/.mypy.ini` with settings that make mypy find the hooks package and enforce strict type checking |
@@ -14,6 +15,14 @@ The installer and its companion modules. Running `npx claude-dev-env` (or `node
 | `git_hooks_installer.test.mjs` | Tests for `git_hooks_installer.mjs` |
 | `install_mypy_ini.test.mjs` | Tests for `install_mypy_ini.mjs` |
 
+## Retired-skill prune
+
+The full-install prune renames a retired skill directory into a timestamped backup rather than deleting it. Each pruned directory is renamed to `~/.claude/.claude-dev-env-pruned/<timestamp>/<skill-name>/`, a backup root outside `~/.claude/skills` so a backed-up directory is never re-discovered as a skill. Backups accumulate — nothing cleans them — so a user can recover a directory. A rename that fails leaves the directory in place with a logged warning and never falls back to deletion, so a prune failure costs at most a cosmetic leftover.
+
+Matching is by directory name alone, so a user-authored directory whose name collides with a retired skill is backed up as if it were that skill. A directory is pruned when the prior install's manifest recorded it or the ever-shipped set names it, and the current install did not just write it. A name absent from all three of those sets, together with `~/.claude/skills/_shared`, is left in place.
+
+The prune is skipped for the whole run — with a logged notice naming the unresolved group — when any declared dependency group fails to resolve. An unresolved dependency contributes no skills to the installed set, so a live skill that a dependency package supplies would look retired; holding the prune until every dependency resolves keeps such a skill from being backed up.
+
 ## Key exports from install.mjs
 
 | Export | Description |

package/bin/ever-shipped-skills.mjs

@@ -0,0 +1,73 @@
+/**
+ * The top-level skill directory names this package has ever shipped.
+ *
+ * The installer subtracts the skills the current package installs from this set
+ * to learn which shipped skills have retired, so a full reinstall can remove a
+ * retired skill left behind under ~/.claude/skills. Because the current set is
+ * subtracted at runtime, restoring a retired skill to the package protects it
+ * automatically — it re-enters the installed set and drops out of the retired
+ * set on the next install.
+ *
+ * The list is a committed literal rather than a git query, because a user
+ * installs from the npm tarball, which carries no source-repo history. Refresh
+ * it by running, from the repository root:
+ *
+ *   git log --all --pretty=format: --name-only -- 'packages/claude-dev-env/skills/*\/SKILL.md' | sort -u
+ *
+ * and pasting each distinct top-level skill directory name below.
+ */
+export const EVER_SHIPPED_SKILL_NAMES = new Set([
+    'anthropic-plan',
+    'auditing-claude-config',
+    'autoconverge',
+    'bdd-protocol',
+    'bg-agent',
+    'bugteam',
+    'caveman',
+    'closeout',
+    'code',
+    'codex-review',
+    'copilot-finding-triage',
+    'copilot-review',
+    'deep-research',
+    'everything-search',
+    'findbugs',
+    'fixbugs',
+    'fresh-branch',
+    'gh-paginate',
+    'gotcha',
+    'grok-spawn',
+    'grokify',
+    'implement',
+    'log-audit',
+    'logifix',
+    'monitor-open-prs',
+    'orchestrator',
+    'orchestrator-refresh',
+    'post-audit-findings',
+    'pr-consistency-audit',
+    'pr-converge',
+    'pr-fix-protocol',
+    'pr-loop-cloud-transport',
+    'pr-loop-lifecycle',
+    'pr-review-responder',
+    'pr-scope-resolve',
+    'pre-compact',
+    'privacy-hygiene',
+    'qbug',
+    'rebase',
+    'recall',
+    'refine',
+    'remember',
+    'research-mode',
+    'reviewer-gates',
+    'session-log',
+    'session-tidy',
+    'skill-builder',
+    'structure-prompt',
+    'task-build',
+    'team-advisor',
+    'update',
+    'usage-pause',
+    'verified-build',
+]);

package/bin/expand_home_directory_tokens.mjs

@@ -1,7 +1,7 @@
 /**
  * Install-time expansion of $HOME / ${HOME} / ~/ in settings.json commands.
  *
- * Hosts that require referenced env vars at hook load time (for example Grok)
+ * Hosts that require referenced env vars at hook load time (for example a third-party host)
  * skip the hook when HOME is unset — common on Windows — so the installer
  * rewrites residual tokens to absolute home paths.
  */

package/bin/install.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, copyFileSync, unlinkSync, rmSync, realpathSync } from 'node:fs';
-import { join, dirname, resolve, relative } from 'node:path';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, copyFileSync, unlinkSync, rmSync, renameSync, realpathSync } from 'node:fs';
+import { join, dirname, resolve, relative, basename } from 'node:path';
 import { homedir } from 'node:os';
 import { execSync, execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -9,6 +9,7 @@ import { createRequire } from 'node:module';
 import { installAllGitHooks } from './git_hooks_installer.mjs';
 import { installMypyIniForClaudeHooks } from './install_mypy_ini.mjs';
 import { expandHomeDirectoryTokensInSettings } from './expand_home_directory_tokens.mjs';
+import { EVER_SHIPPED_SKILL_NAMES } from './ever-shipped-skills.mjs';
 
 const CLAUDE_HOME = join(homedir(), '.claude');
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -19,6 +20,10 @@ const packageRequire = createRequire(import.meta.url);
 
 export const CONTENT_DIRECTORIES = ['rules', 'docs', 'commands', 'agents', 'system-prompts', 'scripts', '_shared', 'audit-rubrics'];
 
+const SKILL_MANIFEST_FILENAME = 'SKILL.md';
+const NEVER_PRUNED_SKILL_DIRECTORIES = new Set(['_shared']);
+const PRUNED_SKILLS_BACKUP_DIRECTORY_NAME = '.claude-dev-env-pruned';
+
 export const CORE_INCLUDE_DIRECTORIES = [
     'rules', 'docs', 'commands', 'agents', 'audit-rubrics', '_shared', 'scripts',
 ];
@@ -94,17 +99,33 @@ function resolveDependencyPackageRoot(dependencyPackageName) {
     return dirname(dependencyPackageJsonPath);
 }
 
+/**
+ * Discovers the install groups contributed by resolvable dependency packages and
+ * the names of the declared dependencies that failed to resolve.
+ *
+ * A dependency that cannot be resolved contributes no group, so its skills never
+ * enter the installed set. The retired-skill prune subtracts the installed set
+ * from the ever-shipped set, so an unresolved dependency whose skills migrated
+ * out of the main package would leave those live skills looking retired. The
+ * returned unresolved-name list lets the caller skip the prune in that degraded
+ * mode rather than delete a live skill.
+ *
+ * @returns {{groups: object, unresolvedDependencyNames: string[]}} The resolvable
+ *   dependency groups keyed by group name, and the names that failed to resolve.
+ */
 function discoverDependencyGroups() {
     const ownPackageJsonPath = join(PACKAGE_ROOT, 'package.json');
     const ownPackageJson = JSON.parse(readFileSync(ownPackageJsonPath, 'utf8'));
     const dependencies = ownPackageJson.dependencies || {};
     const discoveredGroups = {};
+    const unresolvedDependencyNames = [];
     for (const dependencyName of Object.keys(dependencies)) {
         let dependencyRoot;
         try {
             dependencyRoot = resolveDependencyPackageRoot(dependencyName);
         } catch {
             console.error(`  WARNING: Could not resolve dependency ${dependencyName}, skipping`);
+            unresolvedDependencyNames.push(dependencyName);
             continue;
         }
         const dependencyPackageJson = JSON.parse(
@@ -145,14 +166,18 @@ function discoverDependencyGroups() {
         }
         discoveredGroups[groupName] = group;
     }
-    return discoveredGroups;
+    return { groups: discoveredGroups, unresolvedDependencyNames };
 }
 
+const dependencyDiscovery = discoverDependencyGroups();
+const UNRESOLVED_DEPENDENCY_NAMES = dependencyDiscovery.unresolvedDependencyNames;
+
 const INSTALL_GROUPS = {
     core: {
         description: 'Development standards, hooks, agents, commands',
         skills: [
             'orchestrator', 'orchestrator-refresh', 'team-advisor', 'grokify',
+            'grok-spawn',
             'anthropic-plan', 'everything-search',
             'privacy-hygiene',
             'recall', 'remember', 'task-build'
@@ -164,7 +189,7 @@ const INSTALL_GROUPS = {
         description: 'Session logging and memory',
         skills: ['session-log', 'session-tidy'],
     },
-    ...discoverDependencyGroups(),
+    ...dependencyDiscovery.groups,
 };
 
 /**
@@ -511,7 +536,7 @@ function pruneManagedHooksFromEvent(settings, eventType, managedHookRelativePath
  * a new matcher group does not double-run. User-authored hooks are preserved as
  * entries, but residual $HOME / ${HOME} / ~/ tokens in every hook and statusLine
  * command are expanded to absolute home paths so hosts that require referenced
- * env vars at load time (Grok on Windows) can execute them.
+ * env vars at load time (a third-party host on Windows) can execute them.
  *
  * @param {object} settings The parsed settings.json object (mutated in place).
  * @param {{hooks: object}} hooksConfig Parsed hooks.json.
@@ -606,11 +631,99 @@ function mergeHooks(hooksSourceRoot, pythonCommand) {
     return groupCount;
 }
 
-function writeManifest(installedFiles) {
+function writeManifest(installedFiles, skillNames) {
     const manifest = { package: PACKAGE_NAME, version: PACKAGE_VERSION, installedAt: new Date().toISOString(), files: installedFiles };
+    if (skillNames) {
+        manifest.skills = skillNames;
+    }
     writeFileSync(MANIFEST_FILE, JSON.stringify(manifest, null, 2) + '\n');
 }
 
+/**
+ * Read the skill directory names the previous install recorded.
+ *
+ * Returns null when no manifest exists or the manifest predates the skills key,
+ * so a caller can treat "unknown prior skills" the same in both cases and lean
+ * on the ever-shipped set to find retired skills.
+ *
+ * @returns {string[]|null} The prior manifest's skill names, or null when absent.
+ */
+function readPriorManifestSkills() {
+    if (!existsSync(MANIFEST_FILE)) return null;
+    try {
+        const priorManifest = JSON.parse(readFileSync(MANIFEST_FILE, 'utf8'));
+        return Array.isArray(priorManifest.skills) ? priorManifest.skills : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Move retired skill directories a prior install left under ~/.claude/skills into
+ * a timestamped backup directory rather than deleting them.
+ *
+ * A directory is pruned only when the package no longer ships it and either the
+ * prior manifest recorded it or the package once shipped it. Subtracting the
+ * just-installed set from the ever-shipped set at call time means restoring a
+ * skill to the package protects it — it re-enters the installed set and never
+ * counts as retired. Matching is by directory name alone, so a personal
+ * directory a user authored under a name that collides with a retired skill
+ * (for example `code`, `implement`, `refine`, `gotcha`, `caveman`) is treated as
+ * that retired skill and moved to backup; only a name in neither set, and
+ * ~/.claude/skills/_shared, are left in place.
+ *
+ * Each pruned directory is renamed to
+ * ~/.claude/.claude-dev-env-pruned/<timestamp>/<skill-name>/ — a backup root
+ * outside ~/.claude/skills, so a moved directory is never re-discovered as a
+ * skill — under one shared timestamp per run. A backup is never cleaned up, so a
+ * user can recover a wrongly-matched directory. One directory whose rename fails
+ * (for example a read-only file or a cross-device move) is logged and left in
+ * place, never deleted, so a prune failure costs at most a cosmetic leftover.
+ *
+ * @param {Set<string>} installedSkillNames Skill names this install just wrote.
+ * @param {string[]|null} priorManifestSkills The prior manifest's skill names, or null.
+ */
+function pruneRetiredSkills(installedSkillNames, priorManifestSkills) {
+    const skillsDirectory = join(CLAUDE_HOME, 'skills');
+    if (!existsSync(skillsDirectory)) return;
+    const retiredSkillNames = new Set(
+        [...EVER_SHIPPED_SKILL_NAMES].filter(skillName => !installedSkillNames.has(skillName))
+    );
+    const priorSkillNames = new Set(priorManifestSkills || []);
+    const runTimestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupRoot = join(CLAUDE_HOME, PRUNED_SKILLS_BACKUP_DIRECTORY_NAME, runTimestamp);
+    const existingSkillDirs = readdirSync(skillsDirectory, { withFileTypes: true })
+        .filter(entry => entry.isDirectory());
+    for (const skillDir of existingSkillDirs) {
+        const skillName = skillDir.name;
+        if (NEVER_PRUNED_SKILL_DIRECTORIES.has(skillName)) continue;
+        if (installedSkillNames.has(skillName)) continue;
+        const isPruneCandidate = priorSkillNames.has(skillName) || retiredSkillNames.has(skillName);
+        if (!isPruneCandidate) continue;
+        moveRetiredSkillToBackup(skillsDirectory, backupRoot, skillName);
+    }
+}
+
+/**
+ * Move one retired skill directory into the run's backup root, leaving it in
+ * place when the move fails.
+ *
+ * @param {string} skillsDirectory The ~/.claude/skills directory holding the skill.
+ * @param {string} backupRoot The run's timestamped backup directory.
+ * @param {string} skillName The retired skill directory name to move.
+ */
+function moveRetiredSkillToBackup(skillsDirectory, backupRoot, skillName) {
+    const skillPath = join(skillsDirectory, skillName);
+    const backupPath = join(backupRoot, skillName);
+    try {
+        mkdirSync(backupRoot, { recursive: true });
+        renameSync(skillPath, backupPath);
+        console.log(`  ✗ ${join('skills', skillName)} (retired — moved to ${join(PRUNED_SKILLS_BACKUP_DIRECTORY_NAME, basename(backupRoot), skillName)})`);
+    } catch (moveError) {
+        console.warn(`  Warning: could not move retired ${join('skills', skillName)} to backup, leaving in place (${moveError.message})`);
+    }
+}
+
 function install(selectedGroups, options = {}) {
     const isUpdateRefresh = Boolean(options.isUpdateRefresh);
     if (isUpdateRefresh && !selectedGroups && existsSync(MANIFEST_FILE)) {
@@ -708,6 +821,8 @@ function install(selectedGroups, options = {}) {
     let skillsCreated = 0;
     let skillsUpdated = 0;
     const skillPaths = [];
+    const installedSkillNames = new Set();
+    const copiedSkillNames = new Set();
     for (const sourceRoot of allSourceRoots) {
         const skillsSource = join(sourceRoot, 'skills');
         if (!existsSync(skillsSource)) continue;
@@ -718,6 +833,10 @@ function install(selectedGroups, options = {}) {
             skillsCreated += stats.created;
             skillsUpdated += stats.updated;
             skillPaths.push(...stats.paths);
+            copiedSkillNames.add(skillDir.name);
+            if (existsSync(join(skillsSource, skillDir.name, SKILL_MANIFEST_FILENAME))) {
+                installedSkillNames.add(skillDir.name);
+            }
         }
     }
     summary.skills = { created: skillsCreated, updated: skillsUpdated, paths: skillPaths };
@@ -804,7 +923,21 @@ function install(selectedGroups, options = {}) {
         allInstalledFiles.push(claudeHubDest);
         console.log(`  \u2713 ${relative(CLAUDE_HOME, claudeHubDest)} (hub)`);
     }
-    writeManifest(allInstalledFiles);
+    const isFullInstall = !selectedGroups;
+    const priorManifestSkills = readPriorManifestSkills();
+    let manifestSkillNames = priorManifestSkills;
+    if (isFullInstall) {
+        if (UNRESOLVED_DEPENDENCY_NAMES.length > 0) {
+            console.log(
+                `  Skipping retired-skill prune — unresolved dependency group(s): ${UNRESOLVED_DEPENDENCY_NAMES.join(', ')}. `
+                + 'A skill that migrated to a dependency package would look retired and be moved to backup, so the prune is held until every dependency resolves.',
+            );
+        } else {
+            pruneRetiredSkills(copiedSkillNames, priorManifestSkills);
+        }
+        manifestSkillNames = [...installedSkillNames].sort();
+    }
+    writeManifest(allInstalledFiles, manifestSkillNames);
     console.log(`\nInstalled ${PACKAGE_NAME}:`);
     for (const directory of CONTENT_DIRECTORIES) {
         if (summary[directory]) {