# Feature: Design document lifecycle management (archive/prune)

## Problem

gstack's design documents (`root-*-design-*.md`, `root-*-eng-review-*.md`, `autoplan-restore-*.md`) accumulate indefinitely in `~/.gstack/projects//`. There is no mechanism to archive, prune, or compact historical design docs. Over multiple iterations, this creates two compounding problems:

### 1. CLAUDE.md bloat from design doc references

Each iteration's design doc gets referenced in the project CLAUDE.md. Completed phases leave behind detailed review findings, architecture changes, and fix records that are never cleaned up. Example from a project with 7 phases:

| Metric | Value |
|--------|-------|
| CLAUDE.md size | 25KB (360 lines) |
| Referenced design docs | 5 files, 62KB total |
| Fixed context prefix per turn | ~26K tokens |
| Phases completed | 7 (Phase 1 → 6D) |

### 2. Growing artifact footprint across projects

From real usage across 5 active projects over 30 days:

| Project | Design doc accumulation | CLAUDE.md size |
|---------|------------------------|----------------|
| adplatform-revenue-analyze | 272KB (18 files) | 7KB |
| indicator-lineage-query | 148KB (15 files) | 25KB |
| suggestion-sla-bot | 107KB (4 files) | 2.5KB |
| anomaly-skills | 64KB (7 files) | 3.6KB |

Total: **~820KB of design docs** across 5 projects, most of which are historical versions superseded by newer iterations.

### 3. Token cost impact on non-cached models

For models that support prompt caching (glm-5.1, glm-5-turbo), the fixed prefix hits cache at 94-95% rate, so the cost is mitigated. But for models without cache support (0% cache hit rate), every byte in the fixed prefix is billed at full price per turn. A 26K-token fixed prefix over 20 turns = **520K tokens of fresh input**, a significant portion of which is stale design doc content.

## What exists today

| Artifact | Lifecycle management | Tool |
|----------|---------------------|------|
| `learnings.jsonl` | Has confidence decay + `/learn prune` | `gstack-learnings-search`, `/learn` |
| `timeline.jsonl` | Append-only, no prune | `gstack-timeline-log` |
| `root-*-design-*.md` | **Append-only, no archive** | None |
| `root-*-eng-review-*.md` | **Append-only, no archive** | None |
| `autoplan-restore-*.md` | **Append-only, no archive** | None |
| Project CLAUDE.md references | **Manual only** | None |

`/learn` already has a prune workflow (stale file detection, contradiction checks, interactive removal). Design docs have nothing equivalent.

## Proposed solution

### Option A: `/learn` subcommand for design docs

Extend `/learn` with design doc awareness:

```
/learn archive # Interactive: archive superseded design docs
/learn compact # Merge completed phases into one-line summaries in CLAUDE.md
/learn stats # Show artifact sizes and growth trends
```

**Archive behavior:**
- Move superseded design docs to `~/.gstack/projects//archive/`
- Keep the latest N design docs in the active directory (configurable, default: 2)
- Archived docs remain readable by `/autoplan` when it needs historical context, but are excluded from CLAUDE.md references

**Compact behavior:**
- For completed phases in CLAUDE.md: replace detailed review findings, architecture diffs, and fix records with a one-line summary
- Preserve the design doc path reference so `/autoplan` can still find the full history
- Interactive: show before/after diff, let user approve

### Option B: Automatic archival on `/ship`

When `/ship` completes:
1. Detect which design docs correspond to the shipped iteration
2. Auto-archive older design docs for the same branch/feature
3. Compact the corresponding CLAUDE.md section (keep summary, drop details)

### Option C: Lightweight — just a bin tool

Add `gstack-artifacts-prune` to `bin/`:
- List all design docs sorted by date
- Flag superseded versions (same branch prefix, older timestamp)
- Move flagged docs to `archive/`
- Optionally trim CLAUDE.md references

This avoids modifying existing skills and gives users a manual tool they can run periodically.

## Why this matters

gstack's "Boil the Lake" principle works great for completeness — do the whole thing when AI makes marginal cost near zero. But the lake should also have a drain. Design docs that served their purpose (guiding implementation) become dead weight in every subsequent session's context window.

The `/learn` skill already proves this pattern works: confidence decay handles staleness, prune handles cleanup. Design docs need the same lifecycle.

## Environment

- gstack v1.39.0.0
- 5 active projects, 7+ iterations on the heaviest one
- 30-day usage data: 2.04B total tokens, 831M input, 13.5M output
- Models: glm-5.1 (94% cache), glm-5-turbo (95% cache), deepseek-v4-pro-saas (0% cache，problem for check)