[Spec 0015] Add CLEANUP protocol for codebase maintenance

[waleedkadous]

Summary

Implements the CLEANUP protocol as specified in codev/specs/0015-cleanup-protocol.md. This is a four-phase protocol for systematic codebase maintenance:

• AUDIT: Identify dead code, unused dependencies, stale documentation, orphaned tests
• PRUNE: Soft-delete identified cruft with auto-generated restore scripts
• VALIDATE: Run tests to ensure nothing broke
• INDEX: Update architecture docs and project tracking files

Key Features

• Soft-delete strategy: All removals go to .trash/ with 30-day retention
• Auto-generated restore.sh: Easy rollback if something was incorrectly removed
• Comprehensive audit report template: Checkboxes for human approval before deletion
• Scope categories: dead-code, dependencies, docs, tests, temp, metadata
• Integration points: Works with architecture-documenter agent

Files Changed

• codev/protocols/cleanup/protocol.md - Main protocol definition
• codev/protocols/cleanup/templates/audit-report.md - Audit report template
• codev/cleanup/.gitkeep - Runtime artifacts directory
• .gitignore - Added cleanup artifacts exclusions
• CLAUDE.md / AGENTS.md - Added CLEANUP to protocol list and directory structure

Test Plan

• Review protocol document for completeness
• Verify audit report template covers all categories
• Check .gitignore correctly excludes runtime artifacts
• Confirm CLAUDE.md and AGENTS.md are in sync

[waleedkadous]

Multi-Agent Review: Claude + Gemini + Codex

HIGH Priority

1. Rename INDEX phase (all 3 agents agree)

   • "INDEX" sounds like search indexing, not documentation updates
   • Suggested alternatives: SYNC, RECONCILE, DOCUMENT
   • Activities are about syncing docs with codebase state (arch.md, projectlist.md, AGENTS.md)

2. Soft-delete artifacts are gitignored (Codex)

   • .trash/ and audit-*.md are gitignored, so reviewers can't see what was deleted
   • Collaborators can't run restore.sh if validation fails after merge
   • Fix: Keep audit reports versioned, only ignore bulk file blobs

3. Simplify soft-delete strategy (Gemini)

   • Git itself is a soft-delete (git rm + git restore)
   • .trash/ adds shadow files that confuse search tools
   • Consider: Rely on git for tracked files, use .trash/ only for untracked

4. Missing integration with existing governance (Codex)

   • AGENTS.md requires "three documents per feature" and "multi-agent consultation"
   • CLEANUP never states when specs/plans/reviews or consultation should happen
   • Fix: Document whether CLEANUP requires spec/plan/review trio (or provide exception)

MEDIUM Priority

5. Scope categories incomplete (Gemini + Codex)

   • Missing: artifacts (dist/, coverage/), logs (*.log), secrets (.env audit), CI/CD configs, data fixtures
   • Fix: Broaden defaults or describe how to extend

6. Audit template not actionable (Gemini + Codex)

   • Template has placeholder data that needs manual cleanup
   • Missing fields for command provenance, owners, rollback notes
   • Fix: Provide empty tables, add "Tool/output" and "Owner/decision" columns

7. Retention guidance (Codex)

   • find -mtime +30 -delete with no dry-run first
   • No check for open PRs or in-progress validation
   • Fix: Recommend find ... -print review before deletion

LOW Priority

8. Integration with SPIDER (Gemini)
   • Both SPIDER (Review phase) and CLEANUP (INDEX phase) modify AGENTS.md
   • Avoid running CLEANUP while feature branches are active

---

Consensus on INDEX: All reviewers agree "INDEX" is a poor name. Strongest candidates:

• SYNC - emphasizes synchronizing docs with reality
• DOCUMENT - clearest about what happens

Please address HIGH priority items before merge.

[waleedkadous]

Addressed Feedback

All HIGH and MEDIUM priority items have been addressed:

HIGH Priority (all fixed)

1. INDEX -> SYNC: Renamed Phase 4 from INDEX to SYNC throughout the protocol. Updated all references, commit messages, and best practices sections.

2. Audit reports now versioned: Removed codev/cleanup/audit-*.md from .gitignore. Audit reports are now committed to git for collaboration and review. Only .trash/ (bulk deleted files) remains gitignored.

3. Simplified soft-delete strategy:

   • Tracked files: Use git rm - files remain in git history forever
   • Untracked files: Use .trash/ - for build artifacts, temp files with no git history
   • Updated rollback instructions for both scenarios
   • Updated anti-patterns to reflect this approach

4. Added governance integration section:

   • Clarified CLEANUP doesn't require spec/plan/review trio (it's operational, not feature development)
   • Documented projectlist.md update requirements
   • Added guidance on avoiding conflicts with active work

MEDIUM Priority (all fixed)

5. Improved audit template:

   • Empty tables (no placeholder data)
   • Added "Tool Output" column for command provenance
   • Added "Owner Decision" column for tracking decisions
   • Added "Tools Used" to metadata
   • Added Rollback Notes section

6. Added retention dry-run guidance:

   • Updated retention policy to recommend find ... -print before find ... -delete

Ready for re-review!

[waleedkadous]

Fixed Remaining Issues

All remaining INDEX → SYNC references and gitignore clarity issues have been fixed:

Files Updated

File	Fix
codev/plans/0015-cleanup-protocol.md	5 INDEX → SYNC fixes (lines 73, 84, 166, 213, 225)
codev/projectlist.md	2 INDEX → SYNC fixes (lines 234, 244)
codev/cleanup/.gitkeep	Clarified: audit reports versioned, only .trash/ gitignored
AGENTS.md	Clarified: audit-*.md (versioned), .trash/ (gitignored)
CLAUDE.md	Clarified: audit-*.md (versioned), .trash/ (gitignored)

Ready for re-review!