resolutionflow/docs/FlowAssist_Migration/CODEX-FlowAssist-Migration-PLAN.md

# FlowPilot Migration Plan: Phase 0 Through Phase 7

## Summary
- Stay code-change-free until execution is explicitly requested.
- Implement in commit-sized phases, with Phase 0 as a prerequisite for AI-heavy Phases 2+.
- Use this repo’s existing `/api/v1/ai-sessions` API namespace instead of the doc’s generic `/sessions` path.
- Move the existing chat-first `AssistantChatPage` to `/pilot`; `/assistant` becomes a permanent redirect.
- Keep `ai_sessions.session_type` for compatibility, but the user-facing product becomes one FlowPilot surface.

## Phase 0: Prompt Caching Infrastructure
- Consolidate Anthropic prompt caching into `backend/app/core/ai_provider.py`, then route all Anthropic calls through that provider.
- Preserve the existing cached behavior from `assistant_chat_service`, but remove the private duplicate cached implementation once provider parity exists.
- Add cache-control blocks for static system prompt sections and stable tool/context prefixes; keep volatile user messages outside the cached prefix.
- Update one-shot AI generators and `/tickets/ai-parse` to separate stable context from changing request content.
- Instrument every Anthropic response with `cache_read_input_tokens` and `cache_creation_input_tokens`.
- Acceptance: two identical FlowPilot/provider-backed calls within 5 minutes show creation tokens on the first call and read tokens on the second.

## Phase 1: Schema + Route Rename
- Add Alembic migration after current repo head with:
  - `session_facts`
  - `session_suggested_fixes`
  - `draft_templates`
  - `account_settings`
  - new artifact columns on `ai_sessions`
  - provenance columns on `script_templates`
- Create `account_settings` as one lazy row per account:
  - `account_id` primary key, FK to `accounts(id)` with cascade delete
  - `preferences JSONB NOT NULL DEFAULT '{}'`
  - timestamps
  - `get_setting(key, default)` helper on the SQLAlchemy model
  - `templatize_prompt_enabled` default read as `true` when the row/key is absent
- Apply RLS to all new tenant-scoped tables using the repo’s `app.current_account_id` policy pattern.
- Route `/pilot` and `/pilot/:sessionId` to the existing chat UI; redirect `/assistant` and `/assistant/:sessionId` permanently.
- Update sidebar, command palette, dashboard cards, session list links, and visible labels from “AI Assistant”/ResolutionAssist to “FlowPilot” where they describe the troubleshooting surface.
- Acceptance: `/pilot` renders the chat UI, `/assistant` redirects, RLS grep/check passes, and no Phase 2 UI is introduced yet.

## Phase 2: What We Know
- Add `FactSynthesisService` for conservative conversion of answers/check outputs into facts.
- Add fact APIs under `/api/v1/ai-sessions/{id}/facts`:
  - list, create manual note, update editable fact, soft-delete, promote source item.
- Extend `unified_chat_service` marker parsing with `[PROMOTE]`; do not create a separate marker pipeline.
- Because current questions/checks live in `ai_sessions.pending_task_lane` JSON, Phase 2 must assign stable UUIDs to task-lane questions/actions/checks when they are first persisted. `session_facts.source_ref` points to those stable JSON item IDs; it remains polymorphic and unconstrained at the DB level.
- Add frontend task lane components under the new FlowPilot component namespace:
  - `TaskLane`
  - `WhatWeKnow`
  - `WhatWeKnowItem`
  - `AddNoteButton`
  - moved/refactored Questions and Diagnostic Checks sections
- Place What We Know above Questions. Facts from questions/checks are read-only at the fact card level; manual and AI-synthesis facts are editable.
- Acceptance: answering a question or completing a check can promote a fact within 2 seconds; manual notes persist; page reload preserves facts; cross-account access is blocked.

## Phase 3: Suggested Fix + Resolve Preview
- Add suggested-fix APIs under `/api/v1/ai-sessions/{id}/suggested-fixes`:
  - get active suggested fix
  - record decision for one-off/draft-template/build-template/dismissed
- Extend `unified_chat_service` marker parsing with `[SUGGEST_FIX]`; supersede the prior active fix when a new one is persisted.
- Add `ResolutionNoteGeneratorService` that builds the fixed markdown shape:
  - Problem
  - What we confirmed
  - Root cause
  - Resolution
- Add preview endpoint at `/api/v1/ai-sessions/{id}/resolution-note/preview`.
- Generate the preview from `ai_sessions`, `session_facts`, active suggested fix, and linked script generations; redact sensitive script parameters.
- Cache preview output by session-state version or content hash; invalidate on fact/suggested-fix/script-generation writes.
- Add `SuggestedFix`, `ResolveButton`, and `ResolutionNotePreview` popover. Debounce preview refresh to 500ms.
- Acceptance: a session with facts and a suggested fix shows a four-section preview; editing a fact refreshes preview; human review confirms no unsupported claims.

## Phase 4: Resolve + Escalate Writebacks
- Add `EscalationPackageGeneratorService` with handoff-oriented markdown:
  - Problem
  - What we’ve confirmed
  - What we’ve tried
  - Current hypothesis
  - Suggested next steps
- Add preview/post endpoints under `/api/v1/ai-sessions/{id}`:
  - `/resolution-note/preview`
  - `/resolution-note/post`
  - `/escalation-package/preview`
  - `/escalation-package/post`
- Extend PSA writeback service using the existing PSA provider registry and `post_note` seam.
- Implement “confirm and fire”: engineer edits preview, clicks Confirm & post, then server posts to PSA and stores result metadata.
- Ticket status transitions must verify by re-fetching status; failed verification is surfaced as an error, not silent success.
- Resolving without a linked PSA ticket stores markdown and marks the session resolved without external posting.
- Acceptance: ConnectWise test ticket receives the note/package, status verification works, and unlinked sessions resolve locally.

## Phase 5: Inline Script Generator Integration
- Add inline Script Generator components:
  - `TemplateMatchPanel`
  - `NoTemplateDialog`
  - `ParameterizationPreview`
- For template matches, clicking the suggested fix opens the existing Script Generator flow with parameters prefilled from facts, ticket context, account/PSA config, and AI-suggested values.
- For no-template matches, show the three-option dialog:
  - Run as one-off
  - Run now, templatize after resolve
  - Build as template now
- Persist the selected path on `session_suggested_fixes.user_decision`.
- Add `TemplateExtractionService` for converting concrete scripts into proposed parameter schemas and templated bodies.
- Link every script generation back to `ai_sessions` via existing `script_generations.ai_session_id`.
- `Cmd+K → script` opens the inline generator from the FlowPilot session; no Resolve keyboard shortcut is added.
- Acceptance: matched templates prefill parameters; no-match flow shows three options; all options produce the correct session/template side effects.

## Phase 6: Post-Resolve Templatize Prompt
- Add `TemplatizePrompt` after successful Resolve only when:
  - the account setting allows prompts
  - the session has pending `draft_templates`
  - the user chose “Run now, templatize after resolve”
- Accept flow creates a real `script_templates` row with:
  - `source_session_id`
  - `source_user_id`
  - `source_ticket_ref`
  - accepted parameter schema/body edits
- Skip flow marks the draft rejected.
- “Don’t ask me again for this team” writes `{"templatize_prompt_enabled": false}` to `account_settings.preferences`.
- Script Library shows a pending-drafts badge/count for the account.
- Acceptance: accept creates a visible template with provenance; skip creates no template; disabled prompt is respected on the next resolve.

## Phase 7: Polish
- Match the authoritative mockup HTML for spacing, colors, typography, and component structure; use PNGs for visual target confirmation.
- Add loading states for fact synthesis, preview generation, template extraction, PSA post/verify, and script generation.
- Add empty states for:
  - no facts
  - no questions
  - no checks
  - no suggested fix
  - no pending draft templates
- Add keyboard shortcuts except Resolve:
  - `Cmd+K` command palette
  - `Cmd+Enter` send composer
  - `Cmd+G` script generator
- At widths below 1200px, collapse the task lane into a bottom drawer.
- Use existing design tokens where present; add missing tokens only if needed to match the mockups.
- Acceptance: major screens visually compare within the doc’s tolerance, no horizontal scroll at 1280px, mobile task lane works, and shortcuts do not conflict with browser reload.

## Public Interfaces
- New backend routes use `/api/v1/ai-sessions/{id}/...`, not `/api/v1/sessions/{id}/...`.
- Existing chat creation/message APIs remain compatible.
- `session_type` remains queryable and stored, but frontend routing no longer sends chat sessions to `/assistant`.
- New persistent entities:
  - `session_facts`
  - `session_suggested_fixes`
  - `draft_templates`
  - `account_settings`
- New persisted artifact columns on `ai_sessions` store resolution/escalation markdown and PSA post metadata.

## Test Plan
- Migration tests:
  - fresh DB upgrade succeeds
  - downgrade succeeds if the repo expects reversible migrations
  - new tables have RLS enabled/forced
  - tenant policy includes `app.current_account_id`
- Backend tests:
  - fact CRUD and promotion authorization
  - suggested-fix supersession and decision persistence
  - preview generation cache invalidation
  - Resolve/Escalate local-only behavior without PSA
  - PSA status verification failure path
  - draft-template accept/reject behavior
- Frontend tests:
  - route redirects
  - task lane rendering and persistence
  - inline editing and preview refresh
  - script generator option flows
  - templatize prompt settings behavior
  - responsive drawer behavior
- Manual QA:
  - run through one ConnectWise linked Resolve
  - run through one Escalate
  - run one template-match script path
  - run one no-template draft-template path through post-resolve save

## Assumptions
- Phase 0 is included and must be complete before Phase 2 begins.
- No Resolve keyboard shortcut in this migration.
- Templatize prompt defaults to enabled.
- Resolution notes use engineer review plus Confirm & post, not supervisor staging.
- Existing component folders may be renamed opportunistically, but behavior and route migration matter more than directory-name purity.
- No backfill of What We Know for old sessions.
- Team Wiki compilation, SharePoint integration, marketplace sharing, and confidence-tier UI are out of scope.