Stale Module Pruner

Overview

Ripgrep-powered dead-code crawler for the Agent Studio framework. Walks a target directory (default: .claude/lib), then for each .js/.cjs/.mjs file checks whether its module name appears in any other file across the codebase. Files with no external references are flagged as STALE and optionally deleted.

Core principle: Dead modules that stay in .claude/lib/ create false positive references in the ecosystem scanner, inflate the registry, and mislead other tools about what capabilities are actually active. Regular pruning keeps the framework lean and the scanner signal clean.

When to Invoke

Skill({ skill: 'stale-module-pruner' });

Invoke when:

• Post-archival cleanup: after moving modules to _archive/, run pruner on lib/
• After bulk refactors that relocated or merged modules
• Before running validate-ecosystem-integrity.cjs to reduce noise
• As part of a maintenance sprint

Mandatory Skills

Skill	Purpose	When
task-management-protocol	Track pruning progress	Always
ripgrep	Search for module references	During scan
code-semantic-search	Verify intent when uncertain	On ambiguous hits
context-compressor	Compress large result sets	When output is large
verification-before-completion	Gate completion	Before marking done
memory-search	Check prior pruning patterns	At start

Iron Laws

1. Always dry-run first. Run without --delete and save the STALE list before any destructive pass. Never delete files on a first invocation without reviewing the candidates. One false positive can remove an actively-used module.

2. Never rely on filename alone. The pruner matches by module name (filename without extension). Files named utils.cjs may be legitimately unreferenced by that exact name but still used via a barrel import or index re-export. Verify ambiguous hits against barrel/index files before treating as truly stale.

3. Always check test files. A module may have zero production references but an active test. The pruner skips .json and .md matches but not test .cjs files. If the only reference is in a test, the module may still be needed.

4. Never delete archived modules as stale. Modules in _archive/ or _archive/dead/ are already archived — the pruner skips _archive/ dirs by default. Do not point --targetDir at an archive path.

5. Always save the prune report before completing. Write findings to .claude/context/reports/qa/stale-module-prune-{ISO-date}.md before marking the task complete.

Anti-Patterns

Anti-Pattern	Risk	Correct Approach
Running with --delete on first invocation	Destroys modules with barrel/index re-exports	Always dry-run first, review candidates, then delete
Treating zero-reference as definitive stale	Barrel imports and test-only references create false stale	Verify each STALE candidate against index files + tests
Running from a non-project-root CWD	All path resolution breaks; misleading output	Always run from project root (process.cwd())
Pointing --targetDir at .claude/lib only	Misses stale modules in scripts/ or tools/	Run separate passes with different --targetDir values
Deleting without a prune report artifact	No audit trail; next session can't identify what was lost	Always save report before deletion

Step 1: Dry-Run Scan

# Default: scan .claude/lib for stale CJS/MJS/JS modules (dry-run)
node .claude/skills/stale-module-pruner/scripts/main.cjs

# Scan a different target directory
node .claude/skills/stale-module-pruner/scripts/main.cjs --targetDir .claude/tools/cli

# Scan with custom search scope
node .claude/skills/stale-module-pruner/scripts/main.cjs --targetDir .claude/lib \
  --searchDirs .claude,tests,scripts,package.json

The script outputs one line per stale module:

STALE: .claude/lib/utils/old-helper.cjs
STALE: .claude/lib/routing/deprecated-matcher.cjs

Total stale items processed: 2

Step 2: Review Candidates

For each STALE: line:

1. Open the file — understand its purpose
2. Search for indirect references: barrel imports, require('./'), index.cjs re-exports
3. Check test files: grep -r "{filename}" tests/
4. Confirm it is genuinely unused before approving for deletion

Create a prune report at .claude/context/reports/qa/stale-module-prune-{ISO-date}.md:

# Stale Module Prune Report

<!-- Agent: developer | Task: #{id} | Session: {date} -->

**Date:** YYYY-MM-DD
**Target:** .claude/lib
**Candidates:** N

## Confirmed Stale (delete)

- .claude/lib/utils/old-helper.cjs — no references, no tests, no barrel export

## Kept (false positive)

- .claude/lib/utils/common.cjs — referenced by index.cjs barrel (not caught by name match)

Step 3: Delete Pass (Conditional)

Only after the prune report is reviewed and candidates confirmed:

node .claude/skills/stale-module-pruner/scripts/main.cjs \
  --targetDir .claude/lib --delete

After deletion, re-run validate-ecosystem-integrity.cjs to confirm no new [PHANTOM_REQUIRE] errors were introduced.

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md
cat .claude/context/memory/issues.md

Review prior pruning patterns and known barrel-import false positives.

After completing:

• Pruning pattern → .claude/context/memory/learnings.md
• False positive suppression decision → .claude/context/memory/decisions.md
• Unresolved stale candidate needing owner review → .claude/context/memory/issues.md

Assume interruption: If the prune report isn't saved to disk, it didn't happen.