Versioning & migration of adoption/KB (docs prompts + version check)

[rucka]

Epic Information

Epic ID: EP-214
Initiative: Dynamic Knowledge Base Management #64
Theme: KB/adoption versioning & migration
Epic Owner: Foomakers Product Team
Status: Planning
Priority: P1
Epic Points: 13 (estimated)
Target Release: Slice ② (after canonical states/context structure definitions)

Epic Statement

As a project on an older pair version
I need docs-published migration prompts per version jump and a CLI version check
So that upgrading adoption/KB structure is safe, repeatable and requires no logic inside skills

Epic Context

D20: every pair release changing adoption/KB structure publishes a docs page with ready copy-paste migration prompts — NO migration logic in skills; the CLI exposes the version check (installed KB vs current; base exists in kb-info). Pair itself is the first structured migration (canonical states, context-map, .pair/working/): dogfood first, then distribute the recipe.

Business Value & Objectives

Primary Business Goals

1. Goal 1: Safe upgrades: breaking structure changes always ship with a migration page.
2. Goal 2: Version drift visible: CLI reports installed vs current KB version.
3. Goal 3: Recipe validated by dogfood before distribution.

Success Metrics (KPIs)

• Breaking releases with migration page - Target: 100%
  • Measurement method: release checklist
  • Current baseline: no migration path exists
• Version mismatch detection - Target: CLI reports drift on every install/update
  • Measurement method: CLI behavior test
  • Current baseline: kb-info shows metadata only

Problem Statement & Market Opportunity

Current State

No migration path between pair versions; projects upgrading KB risk breaking adoption references; no version drift signal.

Target State

Docs migration pages (one per version jump) + CLI version check + pair repo migrated as first case.

Solution Overview

Key Capabilities

1. Docs migration pattern + first page — prompt-based, copy-paste, per version jump.
2. CLI version check — installed KB vs current (extends kb-info).
3. Dogfood migration of pair itself — states, context-map, working/ (first story of the new structure adoption).

Epic Breakdown

User Stories (High-Level)

Must-Have Stories (P0)

• US: As a maintainer I want the docs migration-page pattern + first page so that upgrades have a repeatable recipe
• US: As a CLI user I want the KB version check so that drift is visible

Should-Have Stories (P1)

• US: As pair maintainers we want pair itself migrated (states, context, working/) so that the recipe is validated by dogfood

Epic Acceptance Criteria

• AC1: Upgrade with breaking change has its migration page/prompt
• AC2: CLI reports KB version mismatch
• AC3: No migration logic inside skills

Timeline & Roadmap

Critical Path Dependencies

• Requires: Canonical states (Canonical states, n-m mapping, DoR/DoD, refine=Draft→Ready #202) and Domain model (Domain model: context map, DDR, analysis log #203) — the new structure to migrate to

Success Validation

Launch Criteria

• Functionality: All must-have stories completed and tested
• Documentation: Docs site updated (migration pages ARE the deliverable)
• CLI: apps/pair-cli updated (version check)

---

Appendix

Related Documentation

• Decision D20 in pair-requirements-triage.md (emerged during grilling; no source requirement ID)