archive-cycle

Archive-cycle workflow

Long-running projects (100+ ТЗ, 1-2 years) require active archival. Without it specs/ and docs/agent/04_changelog.md become unsearchable swamps. This skill is invoked automatically by lifecycle-cron hook (1×day) and manually during /close-series.

What gets archived

1. Closed ТЗ folders (>30 days, has CHANGELOG.md with closure marker)

• Move specs/<series>/<TZ_N>/ → specs/<series>/_archive/<TZ_N>/
• Series stays open; only individual closed ТЗ archive to series-local archive

2. Closed series

• After /close-series passes DoD: move whole specs/<series>/ → specs/_archive/<series>/
• Final commit references series — git log preserves the closure

3. CHANGELOG quarter blocks

• When docs/agent/04_changelog.md exceeds 1000 lines, lifecycle-cron splits:
  • Keeps last 100 lines inline
  • Older content → docs/agent/changelog-archive/before-<YYYY>Q<N>.md
• Quarter naming preserves chronological searchability

4. ADRs — never archived, but indexed

• ADR files stay in docs/agent/decisions/ permanently
• INDEX.md (auto-generated by post-tool-edit hook) is the lookup mechanism
• Superseded ADRs get Status: Superseded by ADR-NNNN but file stays

5. Postmortems — never archived

• Major incidents must remain searchable forever
• File 08_postmortems.md may grow but it's high-signal content

6. Checkpoint history (>7 days)

• .claude-data/checkpoint-history/*.md older than 7 days deleted by lifecycle-cron
• Audit trail purpose only; recent ones (last week) kept for forensic debugging

What does NOT get archived

• docs/agent/00_current_state.md — single snapshot file, always current
• docs/agent/01_architecture.md — single document, evolves in place
• docs/agent/05_module_map.md — single map, regenerated as code changes
• docs/agent/decisions/INDEX.md — auto-generated, regenerated on every ADR change
• CLAUDE.md — ≤80 lines, never grows

Triggers

Automatic (via lifecycle-cron hook, 1×day from SessionStart)

• ТЗ folders older than 30 days with closure marker → series-local _archive/
• Changelog over 1000 lines → quarter-block archive
• Checkpoint history > 7 days → delete

Manual (via slash commands)

• /close-tz — moves current ТЗ to local archive immediately if closed
• /close-series — verifies DoD then moves whole series to specs/_archive/

What to do if you see series with 16+ ТЗ

• Series HARD LIMIT is 15 ТЗ (R from methodology). User got warned at SessionStart.
• Split: close current series, start new series for remaining work
• Do NOT just keep adding — that's how Simply v1 hit 100+ ТЗ in one infinite series

Anti-patterns

• ✗ Delete files (always move to archive, never rm)
• ✗ Archive ADRs (never archive — INDEX.md is the navigation)
• ✗ Skip archival because "we'll do it later" (lifecycle-cron does it for you)