# v1 to v2 Migration Playbook

This playbook migrates the old 6-file memory bank to the v2 layered model.

## Mapping Table

| v1 file | v2 destination |
| --- | --- |
| `projectbrief.md` | `10_scope.md` |
| `productContext.md` | `11_product.md` |
| `systemPatterns.md` | `12_architecture.md` |
| `techContext.md` | `13_tech.md` |
| `activeContext.md` | `20_now.md` |
| `progress.md` | `21_backlog.md` + `logs/tasks/...` + `00_project_snapshot.md` |

## Migration Steps

1. Create the v2 tree from `templates/`.
2. Copy current-truth statements from v1 files into mapped v2 core files.
3. Remove historical narrative from core content while migrating.
4. Extract major decisions into ADRs (`decisions/ADR-*.md`).
5. Extract execution history into task logs (`logs/tasks/YYYY/MM/*.md`).
6. Build `00_project_snapshot.md` from current state, top risks, and top priorities.
7. Build `21_backlog.md` from remaining actionable items only.
8. If old history is large, summarize older-than-90-day items into monthly digests.
9. Run consistency checks from `OPERATIONS.md`.

## Conversion Rules
- Keep one source of truth per concept.
- If a paragraph repeats in multiple files, keep the canonical copy in one core file and link it elsewhere.
- Core files must answer "what is true now", not "what happened over time".
- Place justifications and tradeoffs in ADRs, not in core files.

## Suggested First ADRs
- `ADR-0001-memory-bank-v2-adoption.md`: why v2 was adopted.
- `ADR-0002-layered-read-protocol.md`: why layered reading is required.
- `ADR-0003-core-no-changelog-rule.md`: why history is separated from core files.

## Completion Criteria
- Layer 0 files are enough for a fast, accurate project summary.
- All backlog items are actionable and non-duplicated.
- Old historical detail is linked through task logs and digests.
- No core file breaches hard line budgets.