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

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.

1. 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.

1. 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.

1. 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.

1. 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

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.