TODO Archive System

Companion to: todo-management (from superpowers-plus) Archive location: $(dirname $TODO_FILE_PATH)/todo-archives/ Index: todo-archives/INDEX.md

Wrong skill? Managing active tasks → todo-management. Task CRUD operations → use todo-crud.sh directly.

Companion Skills

• todo-management: Active task management (this skill handles archival)

When to Use

Archive Workflow

Step 1: Resolve paths

EXPLICIT_TODO_FILE_PATH="${TODO_FILE_PATH:-}"
if command -v cb-env &>/dev/null; then
  TODO_FILE_PATH=$(cb-env -- bash -c 'printf "%s" "$TODO_FILE_PATH"')
else
  source ~/.codex/.env 2>/dev/null || true
fi
TODO_FILE_PATH="${EXPLICIT_TODO_FILE_PATH:-${TODO_FILE_PATH:-$HOME/.codex/TODO.md}}"
TODO_PATH="${TODO_FILE_PATH:-$HOME/.codex/TODO.md}"
ARCHIVE_DIR="$(dirname "$TODO_PATH")/todo-archives"

Step 2: Determine what to archive

Parse the # HISTORY section of TODO.md. Identify completed ([x]) and cancelled ([-]) tasks.

Archival criteria (any match triggers archival):

• Manual trigger (archive todos) → archive ALL HISTORY entries
• TODO.md > 400 lines AND entry is ≥7 days old → archive
• Entry is >30 days old → archive (staleness rule)

Step 3: Partition by completion month

For each task, extract the Done: or Cancelled: date. Compute target file: YYYY-MM.md.

Step 4: Write to archive files

For each target month file:

1. If file doesn't exist → create with header:

   # TODO Archive — {Month Name} {Year}
   
   > Tasks archived from TODO.md
   

2. Check for duplicate task IDs (idempotency guard) and skip re-appending blocks already present in the month file
3. Append tasks under ## YYYY-MM-DD date headers (reverse-chronological)
4. Compute and add metadata: Duration:, Issue: (extract ticket IDs from tags/description)

Step 5: Update INDEX.md

Rebuild INDEX.md from all archive files:

# TODO Archive Index

> Total archived: {count} tasks across {n} months

| Month | Tasks | Top Tags | Related Issues |
|-------|-------|----------|---------------|
| 2026-03 | 42 | #engineering (18) | PROJ-$1, PROJ-$1 |
| 2026-02 | 38 | #recruiting (12) | PROJ-$1 |

Step 6: Remove archived tasks from TODO.md

Remove only the archived entries from the HISTORY section. Keep any entries that didn't meet archival criteria.

Step 7: Integrity verification

pre_history_count = {N}
removed_from_history = {M}
post_history_count = {N - M}

If mismatch → ABORT, restore from backup, report error.

Archive File Format

# TODO Archive — March 2026

> Tasks archived from TODO.md


## 2026-03-18
- [x] [20260315-01] Fix alarm tuning across repos #engineering-backend
  - Added: 2026-03-15
  - Done: 2026-03-18T14:30:00
  - Duration: 3 days
  - Progress: Tuned P1/P2 alarms, added runbook URLs
  - Issue: PROJ-$1

## 2026-03-15
- [x] [20260314-02] Review config PR #engineering-backend
  - Added: 2026-03-14
  - Done: 2026-03-15T10:30:00
  - Duration: 1 day
  - Progress: Approved with minor suggestions

Search Interface

By keyword

search archived todos for "alarm tuning"
→ grep -rn "alarm tuning" "$ARCHIVE_DIR"/*.md

By issue ID

search archived todos for PROJ-$1
→ grep -rn "PROJ-$1" "$ARCHIVE_DIR"/*.md

By month

show archived todos from March 2026
→ cat "$ARCHIVE_DIR/2026-03.md"

By date range

show archived todos from 2026-02-01 to 2026-03-15
→ cat 2026-02.md 2026-03.md (then filter by date headers)

Integrity & Safety

• Locking: Acquires the same advisory lock todo-crud.sh uses (via todo-engine.py's acquire_lock()) before snapshotting TODO.md, and holds it until the rebuild is committed or aborted. Declares a longer TTL than the default (archive rebuilds can run longer than a typical write) — see the todo-management skill's Failure Modes section for lock-recovery guidance (including how long a caller should expect to wait) rather than duplicating it here.
• Backup: TODO.md backed up before any modification (existing mechanism)
• Idempotency: Task IDs checked before appending — duplicates skipped
• Dry-run: Report what would be archived without modifying files
• Recovery: If counts mismatch post-archive → restore from backup

Edge Cases

Failure Modes