diff --git a/docs/FlowAssist_Migration/MIGRATION-HANDOFF.md b/docs/FlowAssist_Migration/MIGRATION-HANDOFF.md new file mode 100644 index 00000000..cc14db43 --- /dev/null +++ b/docs/FlowAssist_Migration/MIGRATION-HANDOFF.md @@ -0,0 +1,120 @@ +# 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.