# 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://:5173/assistant/` in a browser. Must land on `/pilot/` 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.