config-audit/commands/cleanup.md

---
name: config-audit:cleanup
description: Clean up old config-audit sessions to reclaim disk space
allowed-tools: Read, Write, Glob, Bash, AskUserQuestion
model: sonnet
---

# Config-Audit: Session Cleanup

Manage and clean up accumulated config-audit sessions in `~/.claude/config-audit/sessions/`.

## Usage

```
/config-audit cleanup
/config-audit cleanup --raw   # pass-through accepted; no-op (cleanup is file-management only, no findings prose)
```

## Implementation Steps

0. **Parse flags**:

   ```bash
   RAW_FLAG=""
   if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
   ```

   `--raw` is accepted for CLI surface consistency but is a no-op here — cleanup manages session directories on disk, it does not produce findings prose.

1. **List all sessions**:
   - Glob `~/.claude/config-audit/sessions/*/state.yaml`
   - Use the Read tool on each session's state.yaml and extract:
     - Session ID
     - Created timestamp
     - Current phase
     - Whether session is active (has `next_phase` and `current_phase` is not `verify` or `complete`)

2. **Calculate disk usage**:
   - Use `du -sh ~/.claude/config-audit/sessions/{session-id}/` for each session
   - Calculate the total amount of disk space used

3. **Display session table**:
   ```
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   Config-Audit Sessions
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

   | # | Session ID | Age | Phase | Status | Size |
   |---|------------|-----|-------|--------|------|
   | 1 | 20260127_102527 | 15d | implement | active | 12K |
   | 2 | quick-20260126 | 16d | analyze | complete | 8K |
   | 3 | 20260120_091500 | 22d | analyze | complete | 6K |

   Total: 3 sessions, 26K disk usage
   ```

4. **Ask cleanup action**:
   ```
   AskUserQuestion:
     question: "Which sessions should I clean up?"
     header: "Cleanup"
     options:
       - label: "Completed sessions only (Recommended)"
         description: "Delete sessions where phase is verify/complete. Keeps active sessions safe."
       - label: "Older than 14 days"
         description: "Delete all sessions older than 14 days, regardless of status."
       - label: "All except current"
         description: "Delete everything except the most recent active session."
       - label: "Cancel"
         description: "Don't delete anything."
   ```

5. **Safety guards**:
   - NEVER delete sessions where `current_phase` is not `verify` or `complete` AND `next_phase` exists, unless user explicitly chose age-based or all-except-current
   - Warn before deleting active sessions: "Session {id} is still active (phase: {phase}). Delete anyway?"

6. **Execute cleanup**:
   - **Validate the id before it ever reaches `rm -rf`.** Each `{session-id}`
     must match `^[0-9]{8}_[0-9]{6}$` (the id format `discover` generates) or be
     an existing directory name read verbatim from the Glob in step 1. If an id
     is empty or fails to match, **refuse to delete it**, report it, and continue
     with the rest. An empty id expands the path to
     `~/.claude/config-audit/sessions//`, which deletes *every* session.
   - For each validated session: `rm -rf ~/.claude/config-audit/sessions/{session-id}/`
   - Track deleted count and freed space

7. **Output summary**:
   ```
   ✓ Cleanup complete

   Deleted: 2 sessions
   Freed: 14K disk space
   Remaining: 1 session (active)
   ```

## Session Status Detection

A session is considered **active** if ALL of these are true:
- `current_phase` is not `verify` and not `complete`
- `next_phase` exists and is not empty

A session is considered **complete** if ANY of these are true:
- `current_phase` is `verify` or `complete`
- `next_phase` is empty or null

## Error Handling

- **Legacy path:** Also check `~/.config-audit/sessions/` for sessions created before v2.2.0. If found, include them in the session list and note: "Found {n} session(s) at legacy path (~/.config-audit/). These will be cleaned up normally."
- If `~/.claude/config-audit/sessions/` doesn't exist (and no legacy sessions): "No sessions found. Nothing to clean up."
- If no sessions match criteria: "No sessions match the selected criteria."
- If deletion fails: Log error, continue with other sessions