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.