claude-dev-env 1.93.1 → 1.95.0

package/_shared/pr-loop/state-schema.md

@@ -31,26 +31,7 @@ Adds nothing beyond common. Single subagent loops internally and returns a final
 
 ### pr-converge
 
-Adds the same **traffic** fields whether they live in **`state.json`** or in the **conversation state line**; only the **store** differs.
-
-| Field | Type | Purpose |
-|---|---|---|
-| `phase` | enum | `BUGBOT`, `BUGTEAM` — which reviewer the current tick drives |
-| `current_head` | str | PR `.head.sha` / `git rev-parse` for the PR under work (each tick; from `pull_request_read(method="get")` when no file store) |
-| `bugbot_clean_at` | str \| null | HEAD SHA at which Cursor Bugbot last reported clean, or `null` (reset on every push) |
-| `copilot_clean_at` | str \| null | HEAD SHA at which the GitHub Copilot reviewer (`copilot-pull-request-reviewer[bot]`) last reported clean (review `state == "APPROVED"`), or `null`. Reset on every push. Convergence gates require this equals `current_head` after bugbot+bugteam are clean (see `skills/pr-converge/SKILL.md` § Convergence gates). |
-| `merge_state_status` | str \| null | Last-observed `mergeable_state` from `pull_request_read(method="get")` (e.g., `clean`, `dirty`, `blocked`, `behind`, `unknown`), or `null` before the first check. Reset on every push. `dirty` triggers the rebase invocation; non-`clean` non-`dirty` is a hard blocker per pr-converge `Stop conditions`. |
-| `inline_lag_streak` | int | Consecutive ticks where bugbot's review body claims findings but inline-comments API returns zero rows for `current_head` |
-| `tick_count` | int | Observability only — **no ceiling**; loop ends on convergence or **Stop conditions** in `pr-converge` |
-
-**Dual persistence** (normative: `skills/pr-converge/SKILL.md` § State across ticks, § Multi-PR orchestration model):
-
-| Mode | When it applies | Source of truth | `tick_count` bump |
-|---|---|---|---|
-| **`state.json`** | File exists at `<TMPDIR>/pr-converge-<session_id>/state.json` (multi-PR orchestration or other file-backed session) | JSON: top-level `session_id`; per-PR objects under `prs[<number>]` with `owner`, `repo`, `branch`, `phase`, `current_head`, `bugbot_clean_at`, `inline_lag_streak`, `tick_count`, `last_action`, `status`, `last_updated`. Optional sibling `converged.log` (append-only; multi-PR only). Writes use lock + atomic replace per skill **Concurrency** | **Orchestrator only** at tick start (locked merge for every non-terminal PR); **never** bump `tick_count` in Step 1 when this file is in use |
-| **Conversation state line** | **No** `state.json` (typical single-PR `/pr-converge` in Cursor) | Persist **`phase`**, **`bugbot_clean_at`**, **`inline_lag_streak`**, **`tick_count`** as **plain text** in each assistant turn; next tick reads them from the **most recent assistant message**. **`current_head` is not serialized in that line** — re-resolve each tick via `pull_request_read(method="get")` (same contract as `skills/pr-converge/SKILL.md` § State across ticks). | **Step 1** increments `tick_count` in that line **only** when no `state.json` — must not double-count with any file-backed path |
-
-**`status` (file-backed `prs[...]` only):** `fresh | in_progress | awaiting_bugbot | awaiting_bugteam | converged | blocked`
+Normative field list, phase enum, dual persistence, and reset semantics: [`../../skills/pr-converge/reference/state-schema.md`](../../skills/pr-converge/reference/state-schema.md). File-backed multi-PR `status` enum: [`../../skills/pr-converge/reference/multi-pr-orchestration.md`](../../skills/pr-converge/reference/multi-pr-orchestration.md).
 
 ### monitor-many
 
@@ -71,11 +52,11 @@ Adds per-PR JSON state file at `~/.claude/skills/monitor-many/state/<owner>-<rep
 
 - bugteam: cleared on each new `/bugteam` invocation
 - qbug: cleared on each new `/qbug` invocation
-- pr-converge: `bugbot_clean_at`, `copilot_clean_at`, and `merge_state_status` all reset to `null` on every push (a new commit invalidates every reviewer's prior clean and the prior mergeability snapshot by definition); `phase` cycles each tick. With `state.json`, orchestrator reads that file at tick start; without it, rely on the prior conversation state line — **never** mix both increment rules for `tick_count` on the same run
+- pr-converge: see [`../../skills/pr-converge/reference/state-schema.md`](../../skills/pr-converge/reference/state-schema.md)
 - monitor-many: persists across orchestrator runs; only `last_seen_comment_id` advances monotonically
 
 ## Convergence checks
 
 - bugteam, qbug: `last_action == "audited"` AND `last_findings.total == 0` → `converged`
-- pr-converge: `bugbot_clean_at == current_head` AND most-recent bugteam exit is `converged` AND no push during the bugteam tick AND no outstanding Copilot findings on `current_head` AND `merge_state_status == "clean"` (per `skills/pr-converge/SKILL.md` § Convergence gates) → back-to-back clean → `update_pull_request(draft=false)` (read `current_head` / `bugbot_clean_at` / `copilot_clean_at` / `merge_state_status` from `state.json` when file-backed, else from the conversation state line and Step 1 `pull_request_read(method="get")` output)
+- pr-converge: see [`../../skills/pr-converge/reference/convergence-gates.md`](../../skills/pr-converge/reference/convergence-gates.md)
 - monitor-many: no unresolved comments requiring code changes AND required checks green AND review policy satisfied → `gh pr ready`

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 |
@@ -26,4 +35,4 @@ The installer and its companion modules. Running `npx claude-dev-env` (or `node
 
 ## Install groups
 
-`install.mjs` defines install groups (`core`, `journal`, `research`) plus any dependency groups discovered from `package.json` `dependencies`. The `core` group installs skills, all hooks, and the content directories. `journal` and `research` install only their skill sets.
+`install.mjs` defines install groups (`core`, `journal`) plus any dependency groups discovered from `package.json` `dependencies`. The `core` group installs skills, all hooks, and the content directories. `journal` installs only its skill set.

package/bin/ever-shipped-skills.mjs

@@ -0,0 +1,70 @@
+/**
+ * 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',
+    'code',
+    'copilot-finding-triage',
+    'copilot-review',
+    'deep-research',
+    'everything-search',
+    'findbugs',
+    'fixbugs',
+    'fresh-branch',
+    'gh-paginate',
+    'gotcha',
+    '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/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,18 +166,20 @@ 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',
+            'orchestrator', 'orchestrator-refresh', 'team-advisor', 'grokify',
             'anthropic-plan', 'everything-search',
-            'pr-review-responder',
             'privacy-hygiene',
-            'recall', 'remember', 'task-build', 'verified-build'
+            'recall', 'remember', 'task-build'
         ],
         includeDirectories: CORE_INCLUDE_DIRECTORIES,
         includeAllHooks: true,
@@ -165,11 +188,7 @@ const INSTALL_GROUPS = {
         description: 'Session logging and memory',
         skills: ['session-log', 'session-tidy'],
     },
-    research: {
-        description: 'Deep research and citation tools',
-        skills: ['deep-research', 'research-mode'],
-    },
-    ...discoverDependencyGroups(),
+    ...dependencyDiscovery.groups,
 };
 
 /**
@@ -611,11 +630,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)) {
@@ -713,6 +820,7 @@ function install(selectedGroups, options = {}) {
     let skillsCreated = 0;
     let skillsUpdated = 0;
     const skillPaths = [];
+    const installedSkillNames = new Set();
     for (const sourceRoot of allSourceRoots) {
         const skillsSource = join(sourceRoot, 'skills');
         if (!existsSync(skillsSource)) continue;
@@ -723,6 +831,9 @@ function install(selectedGroups, options = {}) {
             skillsCreated += stats.created;
             skillsUpdated += stats.updated;
             skillPaths.push(...stats.paths);
+            if (existsSync(join(skillsSource, skillDir.name, SKILL_MANIFEST_FILENAME))) {
+                installedSkillNames.add(skillDir.name);
+            }
         }
     }
     summary.skills = { created: skillsCreated, updated: skillsUpdated, paths: skillPaths };
@@ -809,7 +920,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(installedSkillNames, priorManifestSkills);
+        }
+        manifestSkillNames = [...installedSkillNames].sort();
+    }
+    writeManifest(allInstalledFiles, manifestSkillNames);
     console.log(`\nInstalled ${PACKAGE_NAME}:`);
     for (const directory of CONTENT_DIRECTORIES) {
         if (summary[directory]) {