resolutionflow/docs/FlowAssist_Migration/MIGRATION-HANDOFF.md

# FlowPilot Migration — Handoff Note

> **Purpose:** Self-contained status snapshot for picking up Phase 0 + Phase 1 work after the Proxmox dev-environment migration.
> **Lifespan:** Ephemeral. Delete this file once Phase 0 + Phase 1 verification has passed on the new environment.
> **Branch:** `feat/flowpilot-migration` (pushed to Gitea; mirrors to GitHub).
> **Last commit as of this writing:** `f3c3ee5 feat(pilot): unify AI troubleshooting surface at /pilot, redirect /assistant (Phase 1)`

---

## 1. Read order for a fresh Claude Code session

1. `CLAUDE.md` at repo root — Lessons 41+ are current project context; lessons written for the old VPS (especially 66 and 103) may be outdated on Proxmox.
2. `DEV-ENV.md` — post-migration rewrite. If you are setting up the dev environment on Proxmox for the first time, start there.
3. `docs/FlowAssist_Migration/FLOWPILOT-MIGRATION.md` — the locked design doc. Section 0.1 lists the spec drift already integrated into this revision. Section 9 lists all phases and their verification steps.
4. This file — the handoff-state snapshot. Tells you what is pushed, what is verified, and what is owed.
5. `git log --oneline origin/main..HEAD` — should show ten commits ending at `f3c3ee5`. If it shows something different, ground yourself before acting.

---

## 2. What is done, committed, and pushed

Ten commits on `feat/flowpilot-migration`:

| Commit | Phase | Summary |
|---|---|---|
| `46291f3` | Setup | Migration design doc + mockups brought onto the branch |
| `0fbc1e0` | 0.5 | MCP per-turn structured-log telemetry (`mcp.turn`, `mcp.fallback`) |
| `b3be666` | 0.1 | Structured-system-block caching in `AnthropicProvider` (policy α) |
| `56fd440` | 0.2 | Doc-drift note — `/tickets/ai-parse` endpoint does not exist; target pending |
| `da93ae5` | 0.3 | Opt-in caching for `ai_tree_generator`, `kb_conversion`, `ai_fix`, `script_builder` |
| `3f0a132` | 0.4 | `_call_anthropic_cached` → `chat_call_cached`; cache plumbing extracted |
| `92fadfb` | Docs | Codex plan review + Phase 0 audit findings integrated into migration doc |
| `210d310` | 1 | Alembic migration `f07010f17b01` — new tables + column adds + RLS |
| `b49772f` | 1 | SQLAlchemy models: `SessionFact`, `SessionSuggestedFix`, `DraftTemplate`, `AccountSettings` |
| `f3c3ee5` | 1 | `/pilot` = unified surface; `/assistant` redirects; `FlowPilotSessionPage` unmounted |

All ten are on `origin/feat/flowpilot-migration`.

---

## 3. What is NOT done (verification owed on the new env)

Every item below was deferred because the old dev environment was offline during the work.

### Gate 1 — runtime verification

1. **Alembic upgrade.** `cd backend && alembic upgrade head` — must end on revision `f07010f17b01`. Fresh database, no other branches of the history polluting it.
2. **Alembic downgrade reversibility.** From `f07010f17b01`, run `alembic downgrade -1`, then `alembic upgrade head` again. Must succeed both ways.
3. **Cache-hit verification (Phase 0 TODO).** The `TODO(phase0-verify)` note in `backend/app/core/ai_provider.py` module docstring describes the procedure:
   - Start the backend with `AI_PROVIDER=anthropic` and `ANTHROPIC_API_KEY` set.
   - Hit any FlowPilot endpoint twice within 5 minutes (the ephemeral-cache TTL).
   - Grep backend logs for `anthropic.cache` log events.
   - First turn should show `cache_creation_input_tokens > 0`.
   - Second turn should show `cache_read_input_tokens > 0`.
   - If the second turn returns zero reads, inspect the prefix for silent invalidators (timestamps, unsorted JSON keys, varying tool list ordering). Fix before proceeding.
4. **Frontend build.** `cd frontend && npm run build` — must complete. TypeScript `noUnusedLocals` hard-errors on orphan imports (CLAUDE.md Lesson 92). Particular risk: `FlowPilotSessionPage.tsx` is unmounted but on disk — I removed the router import, but a missed reference elsewhere in the tree would surface as a build error.
5. **Redirect smoke test.** Open `http://<new-host>:5173/assistant/<any-real-session-id>` in a browser. Must land on `/pilot/<that-id>` with the ID preserved.
6. **Dispatcher smoke test.** On the dashboard, click a session in `ActiveFlowPilotSessions` or `RecentFlowPilotSessions`. Must route to `/pilot/:id` regardless of the session's `session_type` value.

If any of these fail, they are debug tasks on the new env. They are not reasons to revert Phase 0 or Phase 1.

### Gate 2 — Phase 2 prerequisites (not blocking verification, blocking Phase 2 start)

- Task-lane item stable UUID assignment. Section 4.2 + Phase 2 Deliverable 1 of the design doc. Must land before any `session_facts.source_ref` can point at anything reliable.
- GitNexus re-index. Run `npx gitnexus analyze` before Phase 2 starts — Phase 2 touches `unified_chat_service` and the marker parser, which are load-bearing across the app. I deferred the re-index through all of Phase 0 and Phase 1 because both were file-scoped.

---

## 4. Known drift and intentional deferrals

### Patherly / Resolutionflow naming

49 references to `patherly` remain across the repo (most in historical docs). Live-code hits you may touch during setup:

- `backend/alembic.ini`
- `backend/app/core/config.py`
- `backend/docker-compose.yml`
- `backend/tests/conftest.py`
- `backend/tests/test_rls_isolation.py`
- `frontend/src/lib/sessionRatings.ts` (localStorage key — renaming drops user rating state; flag but do not change)
- `README.md`
- `SESSION-HANDOFF.md`
- `CLAUDE.md`

The canonical name going forward is `resolutionflow`. Sweep is owner-driven in a dedicated commit — do not silently rename as a side effect of setup work.

### FlowPilotSessionPage.tsx still on disk

The file is retained but unreachable. Delete it in a follow-up commit once nothing else in the tree imports it. The comment in `frontend/src/router.tsx` around the old import location explains the disposition.

### Sidebar UX decision deferred

Whether FlowPilot deserves its own sidebar rail entry (currently it's only under the "History" group's `matchPaths`) is a product decision, not Phase 1 scope.

### Pre-existing local alembic divergence

During Phase 1 I surfaced that the local branch showed five alembic heads, but production `main` has a single head at `074` — the extra local heads were branch artifacts. My Phase 1 migration `f07010f17b01` chains from `074`. If `alembic heads` on a fresh DB after `upgrade head` shows anything other than one head ending at `f07010f17b01`, stop and investigate.

---

## 5. Recommended order of operations after the move

1. Clone the repo on the new host. Check out `feat/flowpilot-migration`. Confirm `git log --oneline origin/main..HEAD` shows the ten commits above.
2. Follow `DEV-ENV.md` to stand up the dev environment on Proxmox.
3. Work Gate 1 (items 1 through 6 above) in order. Stop at the first failure.
4. If Gate 1 passes, decide whether to PR `feat/flowpilot-migration` into `main` or keep it open pending Phase 2 work.
5. Before starting Phase 2, complete Gate 2 (task-lane UUIDs + GitNexus re-index).
6. Delete this file (`docs/FlowAssist_Migration/MIGRATION-HANDOFF.md`) once Gate 1 is fully passed. Commit message: `chore(flowpilot-migration): remove migration handoff note after verification`.

---

## 6. Contact surface for context

This migration was authored by Claude Code in a session with Michael. If you are a different Claude Code session or developer:

- The full decision log lives in `docs/FlowAssist_Migration/FLOWPILOT-MIGRATION.md` Section 14.
- The pre-rewrite version is at `docs/FlowAssist_Migration/FLOWPILOT-MIGRATION-v1.md`.
- The Codex plan review is at `docs/FlowAssist_Migration/CODEX-FlowAssist-Migration-PLAN.md`.

If any of those three files are missing or out of date relative to the branch state described here, flag it rather than guess.