plans: add phase 5 migration

plans/git-native-kb/05-migration.md

@@ -0,0 +1,37 @@
+# Phase 5 — Migration
+
+> After Phases 1–4. One-time, per-workspace, behind the flag. Umbrella: [`00-umbrella-plan.md`](00-umbrella-plan.md).
+
+## Objective
+
+Move each existing workspace's KB from Postgres-as-truth to git-as-truth by exporting current documents/folders into an initial git repo, then flipping `KB_GIT_ENABLED` for that workspace once search parity is verified.
+
+## Locked model
+
+- **Seed commit per workspace.** Read current `folders` + `documents` (`source_markdown`/`content`) and write the real tree into the Phase-1 repo as **one seed commit** (`author=migration`).
+- **Preserve identity.** Keep the `unique_identifier_hash` ↔ path mapping so connector re-syncs and existing references stay stable.
+- **Verify before flip.** After seeding, run `reindex(workspace)` (Phase 4) and confirm the rebuilt chunk set reproduces pre-migration search behavior on a fixed query set.
+- **Rollback window.** Keep Postgres content intact until the flagged workspace is verified; flag flip is the point of no return per workspace.
+
+## Work items
+
+1. `app/kb_git/migrate.py` — `migrate_workspace(workspace_id)`: build the tree from `folders`/`documents`, preserving hierarchy + `unique_identifier_hash`, write + seed commit.
+2. Parity check: seed → `reindex` → compare chunk counts and top-k search results against a captured pre-migration baseline.
+3. Per-workspace flag flip with a guard (refuse to flip if parity check fails).
+4. Dry-run mode (build repo, report diffs, do not flip).
+
+## Tests
+
+- Round-trip: a seeded workspace's `reindex` chunk set matches the pre-migration set for the same content.
+- `unique_identifier_hash` mapping preserved (connector docs still resolve).
+- Dry-run flips nothing; failed parity check blocks the flip.
+
+## Out of scope
+
+- Binary re-import (blobs stay in the blob store).
+- Frontend cutover (separate umbrella).
+
+## Open questions
+
+1. Big-bang all-workspaces vs. staged per-workspace rollout order (recommend staged).
+2. Baseline capture method for the parity check (fixed query fixtures vs. sampled).