Cleanup Audit

Audits the codebase for accumulated dead weight: unused TypeScript/JS exports, orphaned source files, npm dependencies that are declared but never imported, and manifest entries that point to files that do not exist. Every finding carries a confidence rating. Only HIGH confidence findings are safe to auto-fix.

Natural Language Triggers

Users may say:

• "cleanup audit"
• "dead code audit"
• "find dead code"
• "orphan files"
• "unused exports"
• "cleanup analysis"
• "find unused dependencies"
• "stale manifest entries"
• "what can I delete"
• "codebase cleanup"

Parameters

--scope

<path>

Restrict analysis to a subtree. Default is the full repository root.

aiwg cleanup-audit --scope src/cli/
aiwg cleanup-audit --scope agentic/code/addons/

--type

<exports|files|deps|manifests>

Run only the specified audit type. Omit to run all four.

exports

files

deps

manifests

Multiple types can be combined:

aiwg cleanup-audit --type exports --type deps

--json

Emit findings as newline-delimited JSON to stdout instead of the formatted report. Useful for piping into other tools or CI scripts.

aiwg cleanup-audit --json | jq 'select(.confidence == "HIGH")'

--fix

Auto-apply removals for all HIGH confidence findings. Has no effect without confirmation when any HIGH finding involves a non-trivial deletion (more than 10 lines or a full file). Combine with

--dry-run

--fix

--dry-run

Show what

--fix

--fix

Execution Flow

Phase 1: Determine Analysis Scope

1. Parse

   --scope

   — default to repo root
2. Parse

   --type

   — default to all four types
3. Parse

   --json

   ,

   --fix

   ,

   --dry-run

   flags
4. Build file inventory for the scope:
   • All

     .ts

     ,

     .tsx

     ,

     .js

     ,

     .mjs

     files (for exports and files audits)

   • package.json

     (for deps audit)
   • All

     manifest.json

     files under

     agentic/

     (for manifests audit)
5. Communicate scope before analysis begins

Communicate:

Cleanup Audit
Scope: {scope}
Types: {types}
Mode: {read-only | fix | dry-run fix}

Building file inventory...
  Source files: {N}
  Manifests: {N}

Phase 2: Analyze Unused Exports

Applies to

--type exports

Detection approach:

1. Glob all source files in scope:

   **/*.ts

   ,

   **/*.tsx

   ,

   **/*.js

   ,

   **/*.mjs

2. Extract all export declarations:

   export function

   ,

   export class

   ,

   export const

   ,

   export type

   ,

   export interface

   ,

   export enum

3. For each exported identifier, grep all source files for imports of that identifier
4. An export is unused if: zero import matches AND it is not referenced in a manifest entry AND it is not a re-export pattern (

   export * from

   )

Confidence rules:

index

default

index.ts

main.ts

index.ts

Output per finding:

[UNUSED-EXPORT] HIGH
  File: src/extensions/registry.ts:45
  Export: registerExtension
  Declared: export function registerExtension(ext: Extension): void
  Importers found: 0
  Safe to remove: yes

Phase 3: Detect Orphaned Files

Applies to

--type files

Detection approach:

1. Build full file list for scope
2. For each file, check whether its path appears in:
   • Any

     import

     or

     require

     statement in any other source file
   • Any

     manifest.json

     scripts

     or

     path

     field
   • Any

     package.json

     main

     ,

     exports

     , or

     bin

     field
3. A file is orphaned if none of the above references exist

Confidence rules:

Output per finding:

[ORPHANED-FILE] HIGH
  File: src/legacy/old-config-reader.ts
  References found: 0 (imports: 0, manifests: 0, package.json: 0)
  Last modified: 2025-11-02
  Safe to remove: yes

Phase 4: Audit Dependencies

Applies to

--type deps

package.json

import

require

Detection approach:

1. Read

   dependencies

   and

   devDependencies

   from

   package.json

2. For each package name, grep source files for:

   • import ... from '{package}'

   • require('{package}')

   • import('{package}')

   • Scoped sub-path imports:

     import ... from '{package}/...'

3. Also check config files for tool references:

   .eslintrc

   ,

   jest.config.*

   ,

   tsconfig.json

Confidence rules:

peerDependency

@types/...

Output per finding:

[UNUSED-DEP] HIGH
  Package: lodash
  Version: ^4.17.21
  Type: dependency
  Usage in source: 0 files
  Config references: 0
  Safe to remove: yes (run: npm uninstall lodash)

Phase 5: Check Manifest Entries

Applies to

--type manifests

manifest.json

Detection approach:

1. Glob all

   manifest.json

   files:

   **/manifest.json

2. For each manifest, inspect entries that reference file paths:

   • skills[].scripts[]

   • agents[].path

   • commands[].handler

   • Any field ending in

     path

     ,

     file

     , or

     script

3. Resolve each path relative to the manifest file location
4. Check whether the resolved path exists on disk
5. Also flag entries where the declared

   name

   has no corresponding

   {name}/SKILL.md

   or

   {name}/AGENT.md

   directory

Confidence rules:

Output per finding:

[STALE-MANIFEST] HIGH
  Manifest: agentic/code/addons/aiwg-utils/skills/manifest.json
  Entry: skills[12].name = "old-voice-converter"
  Expected path: skills/old-voice-converter/
  Path exists: no
  Safe to remove: yes (remove entry from manifest)

Phase 6: Compile Confidence-Rated Report

Aggregate all findings from Phases 2–5 into a unified report. Sort by confidence (HIGH first), then by type, then by file path.

Report format:

# Cleanup Audit Report
Generated: {timestamp}
Scope: {scope}
Types: {types}

## Summary

| Type | HIGH | MEDIUM | LOW | Total |
|------|------|--------|-----|-------|
| Unused exports | {N} | {N} | {N} | {N} |
| Orphaned files | {N} | {N} | {N} | {N} |
| Unused deps | {N} | {N} | {N} | {N} |
| Stale manifests | {N} | {N} | {N} | {N} |
| **Total** | **{N}** | **{N}** | **{N}** | **{N}** |

Auto-fixable (HIGH confidence): {N} findings

## HIGH Confidence Findings

### Unused Exports
...

### Orphaned Files
...

### Unused Dependencies
...

### Stale Manifest Entries
...

## MEDIUM Confidence Findings (manual review recommended)
...

## LOW Confidence Findings (informational)
...

## Recommended Actions

1. Run `aiwg cleanup-audit --fix` to remove {N} HIGH confidence findings automatically
2. Manually review {N} MEDIUM confidence findings
3. Ignore or suppress {N} LOW confidence findings if intentional

Save to:

.aiwg/reports/cleanup-audit-{timestamp}.md

If

--json

{"type": "UNUSED-EXPORT", "confidence": "HIGH", "file": "src/extensions/registry.ts", "line": 45, "detail": "registerExtension", "safe_to_remove": true}

If

--fix

--dry-run

Confidence Rating Reference

Never auto-fix MEDIUM or LOW findings. These exist to inform human decisions, not drive automated removal.

Error Handling

Scope Path Not Found

Error: --scope path does not exist: {path}
Verify the path is relative to the project root or use an absolute path.

Parse Failure on Manifest

Warning: Could not parse manifest at {path}
  Error: {JSON parse error}
  Action: Skipping this manifest — listed in report as PARSE_ERROR

Zero Files in Scope

Warning: No source files found in scope: {scope}
  Checked patterns: **/*.ts, **/*.tsx, **/*.js, **/*.mjs
  Confirm the scope path contains source files.

Examples

Example 1: Full audit before a release

aiwg cleanup-audit

Runs all four audit types on the full repository. Generates report at

.aiwg/reports/cleanup-audit-{timestamp}.md

Example 2: Auto-fix high-confidence findings

aiwg cleanup-audit --fix --dry-run

Shows exactly what

--fix

aiwg cleanup-audit --fix

Removes all HIGH confidence findings: unused exports, orphaned files, stale manifest entries. For unused deps, prints the

npm uninstall

Example 3: CI integration with JSON output

aiwg cleanup-audit --type manifests --type files --json \
  | jq 'select(.confidence == "HIGH") | .file' \
  | sort -u

Extracts only HIGH confidence file-level findings as a sorted list. Suitable for a CI step that blocks merge if orphaned files are introduced.

Example 4: Scoped audit during active development

aiwg cleanup-audit --scope src/cli/ --type exports

Targeted export audit for the CLI subtree only. Fast enough to run after each feature branch merge.

References

• @$AIWG_ROOT/src/cli/handlers/utilities.ts — Cleanup audit command handler
• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/skills/manifest.json — Skills manifest (audited by manifests type)
• @$AIWG_ROOT/docs/cli-reference.md — CLI reference for this command