Decision lifecycle management and archival system #85

Problem

User feedback: "we have a LOOOOOOT of old decisions and stuff. i know we've done a good deal of purging but, could we do a lot, lot more? we might want to come up with some skills for managing decisions."

Current state:

• decisions.md is 2,084 lines (as of 2026-02-16)
• Contains decisions spanning from 2026-02-07 through present (10+ days of rapid iteration)
• No archival or lifecycle management
• Scribe's consolidation helps but doesn't remove obsolete decisions
• Every agent reads the FULL decisions.md on spawn → large context cost

Proposal: Decision Lifecycle & Archival

Create a skill for Scribe: decision-management with lifecycle stages:

1. Active Decisions (current decisions.md)

• Recent decisions (last 30 days by default)
• High-impact architectural/policy decisions regardless of age
• Decisions explicitly marked status: permanent

2. Archived Decisions (new: decisions/archive/)

• Decisions older than 30 days that aren't permanent
• One-time decisions (e.g., "shipped v0.1.0", "merged PR feat: Issue Assignment & Auto-Triage for Squad Members #5")
• Implementation details that are now in code
• Organized by quarter: decisions/archive/2026-Q1.md

3. Obsolete/Superseded

• Decisions explicitly superseded by later decisions
• Moved to archive with [SUPERSEDED by 2026-02-15: {new decision}] markers
• Never deleted — kept for historical context

Decision Criteria

Keep in main decisions.md:

• Referenced in last 30 days (actively being applied)
• Architectural foundation (affects how agents think about the system)
• Team policy/workflow (e.g., proposal-first, branch model, release process)
• Explicitly marked status: permanent by Lead or user

Archive to decisions/archive/:

• Older than 30 days AND not referenced recently
• Completed one-time tasks ("shipped X", "fixed bug Y")
• Implementation details now encoded in code/docs
• Historical context valuable for audit but not day-to-day work

Example active decisions:

• Proposal-first workflow (team policy — permanent)
• Skills system adoption (architectural — permanent)
• Branching strategy (team policy — permanent)
• Release process (team policy — permanent)

Example archived decisions:

• "Shipped v0.1.0" (one-time event)
• "Fixed Scribe resilience bug" (implementation detail now in code)
• "Cleaned up decisions.md on 2026-02-08" (meta-task)
• Early platform decisions superseded by later ones

Scribe Skill: decision-management

When to run: During session logging, after merging inbox
What it does:

1. Read decisions.md
2. Identify candidates for archival (> 30 days old, not permanent, completed/historical)
3. Move qualified decisions to decisions/archive/{YYYY-QX}.md
4. Add forward references in archive: "See decisions.md for current policy"
5. Add backward references in decisions.md: "Historical decisions: see decisions/archive/"
6. Report: "Archived 12 decisions from Q1 — decisions.md now 800 lines (was 2084)"

Safeguards:

• Never archives decisions marked status: permanent
• Prompts user before first archival: "Archive 15 old decisions? [y/n]"
• Generates summary of what will be archived for review
• Dry-run mode: squad scribe --archive-decisions --dry-run

Why This Matters

• Context cost: Agents read full decisions.md on every spawn. 2K lines = high token cost.
• Signal-to-noise: New agents need foundational decisions, not "we fixed bug chore: remove internal team-docs from main #42 in v0.1.1"
• Performance: Smaller decisions.md = faster agent spawns
• Maintainability: Easier to onboard new agents/humans when decisions are curated
• Audit trail: Archive preserves history without cluttering active decisions

Alternatives Considered

1. Hard limits: "decisions.md must be < 500 lines" → rejected, too arbitrary
2. Delete obsolete decisions: Rejected — lose historical context and audit trail
3. Split by category: Rejected —agents need cohesive view, not category hunting
4. Time-based only: Keep recent, archive old — CHOSEN, simple and predictable

Acceptance Criteria

• .ai-team/decisions/archive/{YYYY-QX}.md directory structure
• Scribe skill: decision-management with archival logic
• CLI command: squad scribe --archive-decisions [--dry-run]
• 30-day default threshold (configurable via team.md)
• status: permanent tag in decision format to prevent archival
• Migration: archive appropriate decisions from current 2K line decisions.md
• Test: verify agents still find decisions after archival (via grep or semantic search fallback to archive)
• Docs: document decision lifecycle in docs/features/memory.md

Out of Scope (Defer to v0.6.0+)

• Semantic search across archived decisions (LLM-powered "find similar past decisions")
• Decision dependency graph ("this decision built on these prior decisions")
• Version history per decision (decisions.md is append-only, we rely on git history)