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 onlib/ - After bulk refactors that relocated or merged modules
- Before running
validate-ecosystem-integrity.cjsto 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
- Always dry-run first. Run without
--deleteand 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. - Never rely on filename alone. The pruner matches by module name (filename without extension). Files named
utils.cjsmay 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. - Always check test files. A module may have zero production references but an active test. The pruner skips
.jsonand.mdmatches but not test.cjsfiles. If the only reference is in a test, the module may still be needed. - 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--targetDirat an archive path. - Always save the prune report before completing. Write findings to
.claude/context/reports/qa/stale-module-prune-{ISO-date}.mdbefore 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.jsonThe 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: 2Step 2: Review Candidates
For each STALE: line:
- Open the file — understand its purpose
- Search for indirect references: barrel imports,
require('./'),index.cjsre-exports - Check test files:
grep -r "{filename}" tests/ - 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 --deleteAfter 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.mdReview 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.