chore(flowpilot-migration): remove migration handoff note after verification
All checks were successful
Mirror to GitHub / mirror (push) Successful in 11s
All checks were successful
Mirror to GitHub / mirror (push) Successful in 11s
Gate 1 complete on Proxmox dev host (docker-01): - Alembic at f07010f17b01 (single head); downgrade/upgrade roundtrip clean. - Phase 0 prompt-cache verified: direct provider probe shows cache_create=5398 → cache_read=5398 across two calls; chat path emitted two anthropic.cache events 55s apart on a real FlowPilot session. - Frontend npm run build clean (57.63s, no TS errors, no stale FlowPilotSessionPage imports). - /assistant/:id → /pilot/:id redirect fires correctly and session detail loads (GET /api/v1/ai-sessions/<id> 200); a blank-until-click UX polish will be tracked separately. - Dashboard session-tile dispatcher routes to /pilot/:id. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -1,120 +0,0 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user