Todo Archive

---
name: todo-archive
disable-model-invocation: true
source: superpowers-plus
triggers: ["archive todos", "archive completed tasks", "search archived todos", "show archived todos", "todo archive", "archive history", "clean up todos", "archived tasks", "old todos", "todo history search"]
anti_triggers: ["add task", "create TODO", "what should I work on"]
description: Low-level archive engine for completed tasks in TODO.md. Companion to todo-management; routine housekeeping should usually go through todo-maintenance.sh.
summary: "Use when: archiving completed TODO items from TODO.md."
coordination:
  group: productivity
  order: 6
  requires: ["todo-management"]
  enables: []
  escalates_to: []
  internal: false
composition:
  consumes: [todo-items]
  produces: [archived-tasks]
  capabilities: [archives-tasks, searches-history]
  priority: 40
---

# 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

| Trigger | Action |
|---------|--------|
| User says "archive todos" | Run full archive of all HISTORY entries |
| Routine housekeeping run via `todo-maintenance.sh` | Use this archive engine when maintenance thresholds trigger |
| TODO.md exceeds 400 lines | Auto-archive HISTORY entries ≥7 days old |
| HISTORY has entries >30 days old | Archive regardless of line count (staleness rule) |
| User says "search archived todos for X" | Search across archive files |
| User says "show archived todos from Month Year" | Display specific monthly archive |

## Archive Workflow

### Step 1: Resolve paths

```bash
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:

   ```markdown
   # 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:

```markdown
# 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

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

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

## Archive File Format

```markdown
# 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

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

### By issue ID

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

### By month

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

### By date range

```text
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

| Scenario | Resolution |
|----------|-----------|
| Task completed then re-opened | Archive entry stays (immutable). New ACTIVE entry with `Reopened from [ID]` |
| Concurrent archive attempts | Guarded by the advisory lock — a concurrent `todo-crud.sh` write or second archive run aborts with "Could not acquire lock" rather than racing |
| Archive file already has entries for that day | Append under existing date header (no duplicate header) |
| HISTORY section is empty | No-op, report "No completed tasks to archive" |
| No HISTORY section exists | No-op, report "No HISTORY section found" |

## Failure Modes

| Failure | Fix |
|---------|-----|
| Concurrent write with todo-crud.sh corrupts archive | Acquires the advisory lock — aborts if TODO.md is already locked |
| Losing task metadata (tags, issue links) during archival | Verify archived block matches source block character-for-character |
| Archive runs during active task operations — split-brain | Lock acquisition serializes against `todo-crud.sh`; a held lock aborts the archive run instead of racing it |
| Count mismatch after archive but error suppressed | Hard abort + restore from backup on ANY integrity mismatch |