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

[syzx8]

Problem

gstack's design documents (root-*-design-*.md, root-*-eng-review-*.md, autoplan-restore-*.md) accumulate indefinitely in ~/.gstack/projects/<slug>/. 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/<slug>/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)