Significant rewrite of FLOWPILOT-MIGRATION.md after post-Codex plan review
and the Phase 0 in-flight audit. Archives the pre-rewrite version as
FLOWPILOT-MIGRATION-v1.md and keeps the Codex review under
CODEX-FlowAssist-Migration-PLAN.md for traceability.
Substantive changes that affect implementation:
- Section 0.1 adds a spec-drift note listing corrections integrated into
this revision (API namespace, task-lane item UUIDs, account_settings
creation, missing /tickets/ai-parse endpoint).
- Section 2 adds "Task lane item ID" terminology — stable UUID assigned
to items inside ai_sessions.pending_task_lane so session_facts.source_ref
has something reliable to point to.
- Section 4.1 adds ai_sessions.state_version (INTEGER NOT NULL DEFAULT 0)
and escalation_package_external_id. state_version drives preview cache
invalidation; incremented atomically on writes to facts / suggested
fixes / script_generations.
- Section 4.6 creates account_settings as a new table with JSONB
preferences column, lazy row creation, and a promotion rule for when a
setting should graduate to a typed column.
- Section 5 namespaces all session-scoped routes under
/api/v1/ai-sessions/{id}/... to match the existing codebase pattern.
- Section 5.5 documents the preview caching strategy (state_version
keyed, 500ms client debounce, Redis planned).
- Section 6.6 adds per-service MCP capability flags alongside the model
tier flags.
- Section 7.1 makes the /assistant -> /pilot redirect include the
session-deep-link path and preserve the session ID.
- Section 8.2 adds supersession semantics for [SUGGEST_FIX] markers.
- Section 9 Phase 1 now explicitly includes account_settings and
state_version; Phase 3 uses state_version-keyed caching; Phase 5
mentions MCP inheritance via chat_call_cached wrapper.
- Section 11 adds a dedicated test plan (migrations, backend, frontend,
manual QA).
- Section 14 captures the eight planning decisions made during the
Phase 0 conversation so they are traceable.
No code changes in this commit.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Michael Chihlas
92fadfb90a