React 19 runtime migration complete, AI-assisted migration underway

2026-01-12 07:12:54 +01:00 · 2025-12-20 23:32:50 +01:00
parent 7d307066d8
commit 03a464f6ff
22 changed files with 3081 additions and 145 deletions
--- a/dev-docs/tasks/phase-2/TASK-007-wire-ai-migration/CHANGELOG.md
+++ b/dev-docs/tasks/phase-2/TASK-007-wire-ai-migration/CHANGELOG.md
@@ -0,0 +1,53 @@
+# TASK-007 Changelog
+
+## [Date TBD] - Initial Task Creation
+
+### Summary
+
+Created TASK-007 to document the work required to wire the AI migration backend into the MigrationSession. All AI infrastructure components (AIMigrationOrchestrator, ClaudeClient, BudgetController, AIConfigPanel, BudgetApprovalDialog) were built in TASK-004 but the integration point in `executeAIAssistedPhase()` was intentionally left as a stub.
+
+### Task Documents Created
+
+- `README.md` - Full task specification with background, scope, and implementation steps
+- `CHECKLIST.md` - Step-by-step checklist for implementation
+- `CHANGELOG.md` - This file
+- `NOTES.md` - Working notes template
+
+### Next Steps
+
+- Create branch `task/007-wire-ai-migration`
+- Begin Phase 1: Create DecisionDialog component
+- Follow checklist through to completion
+
+### Known Issues
+
+None yet - task not started.
+
+---
+
+## [Date TBD] - Implementation Progress
+
+_Add entries here as implementation progresses_
+
+### Files Modified
+
+- `packages/noodl-editor/src/editor/src/models/migration/MigrationSession.ts` - [What changed and why]
+- `packages/noodl-editor/src/editor/src/views/migration/MigrationWizard.tsx` - [What changed and why]
+
+### Files Created
+
+- `packages/noodl-editor/src/editor/src/views/migration/DecisionDialog.tsx` - [Purpose]
+- `packages/noodl-editor/src/editor/src/views/migration/DecisionDialog.module.scss` - [Purpose]
+
+### Testing Notes
+
+- [What was tested]
+- [Any edge cases discovered]
+
+### Breaking Changes
+
+- None expected
+
+### Known Issues
+
+- [Any remaining issues or follow-up needed]
--- a/dev-docs/tasks/phase-2/TASK-007-wire-ai-migration/CHECKLIST.md
+++ b/dev-docs/tasks/phase-2/TASK-007-wire-ai-migration/CHECKLIST.md
@@ -0,0 +1,166 @@
+# TASK-007 Checklist
+
+## Prerequisites
+
+- [x] Read README.md completely
+- [x] Understand the scope and success criteria
+- [ ] Create branch: `git checkout -b task/007-wire-ai-migration`
+- [ ] Verify build works: `npm run build:editor`
+- [ ] Verify existing AI components work in isolation
+
+## Phase 1: Create DecisionDialog Component
+
+- [ ] Create `DecisionDialog.tsx`
+  - [ ] Define props interface (componentName, attempts, costSpent, etc.)
+  - [ ] Add UI for showing retry history
+  - [ ] Add 4 action buttons (Retry, Skip, Get Help, Accept Partial)
+  - [ ] Handle "Get Help" to display AI suggestions
+  - [ ] Export component
+- [ ] Create `DecisionDialog.module.scss`
+  - [ ] Style the dialog layout
+  - [ ] Style retry history display
+  - [ ] Style action buttons
+  - [ ] Add responsive layout
+- [ ] Document in CHANGELOG.md
+
+## Phase 2: Wire Budget Approval Flow
+
+- [ ] Modify `MigrationWizard.tsx`
+  - [ ] Add `budgetApprovalRequest` state
+  - [ ] Create `handleBudgetApproval` callback
+  - [ ] Create `handleBudgetDenial` callback
+  - [ ] Pass callbacks to MigratingStep
+- [ ] Modify `MigratingStep.tsx`
+  - [ ] Import BudgetApprovalDialog
+  - [ ] Receive budget callback props
+  - [ ] Conditionally render BudgetApprovalDialog
+  - [ ] Connect approve/deny to callbacks
+- [ ] Test budget approval flow manually
+- [ ] Document in CHANGELOG.md
+
+## Phase 3: Wire Decision Flow
+
+- [ ] Modify `MigrationWizard.tsx`
+  - [ ] Add `decisionRequest` state
+  - [ ] Create `handleDecision` callback
+  - [ ] Pass callbacks to MigratingStep
+- [ ] Modify `MigratingStep.tsx`
+  - [ ] Import DecisionDialog
+  - [ ] Receive decision callback props
+  - [ ] Conditionally render DecisionDialog
+  - [ ] Handle all 4 decision types
+  - [ ] Display AI help text if provided
+- [ ] Test decision flow manually
+- [ ] Document in CHANGELOG.md
+
+## Phase 4: Implement executeAIAssistedPhase()
+
+- [ ] Open `MigrationSession.ts`
+- [ ] Import required dependencies
+  - [ ] Import AIMigrationOrchestrator
+  - [ ] Import filesystem for reading/writing
+  - [ ] Import types (DecisionRequest, ProgressUpdate, etc.)
+- [ ] Replace stub implementation
+  - [ ] Remove TODO comment and simulateDelay
+  - [ ] Initialize AIMigrationOrchestrator with API key and budget
+  - [ ] Create onBudgetPause callback that notifies listeners
+  - [ ] Create onProgress callback that updates progress
+  - [ ] Create onDecisionRequired callback that notifies listeners
+- [ ] Loop through needsReview components
+  - [ ] Get component file path
+  - [ ] Read source code using filesystem
+  - [ ] Call orchestrator.migrateComponent()
+  - [ ] Handle 'success' result: write to target, log success
+  - [ ] Handle 'partial' result: write code, log warning
+  - [ ] Handle 'failed' result: log error, don't write
+  - [ ] Handle 'skipped' result: log info
+  - [ ] Update budget spending in session.ai.budget.spent
+- [ ] Add error handling with try-catch
+- [ ] Ensure orchestrator is cleaned up
+- [ ] Document in CHANGELOG.md
+
+## Phase 5: Handle Session Abort
+
+- [ ] Add orchestrator instance tracking in MigrationSessionManager
+- [ ] Modify `cancelSession()` method
+  - [ ] Call orchestrator.abort() if exists
+  - [ ] Clean up orchestrator reference
+- [ ] Modify `startMigration()` error handling
+  - [ ] Ensure orchestrator aborts on error
+  - [ ] Clean up resources
+- [ ] Test abort scenarios
+- [ ] Document in CHANGELOG.md
+
+## Phase 6: Manual Testing
+
+### Scenario 1: Successful Migration
+
+- [ ] Set up test project with 1 needsReview component
+- [ ] Configure valid API key
+- [ ] Set $2 budget
+- [ ] Start migration
+- [ ] Verify Claude API is called
+- [ ] Verify migrated code is written to target
+- [ ] Verify success log entry
+- [ ] Verify budget spending tracked
+
+### Scenario 2: Budget Pause
+
+- [ ] Configure $2 budget with $0.50 pause increment
+- [ ] Scan project with multiple components
+- [ ] Start migration
+- [ ] Wait for BudgetApprovalDialog
+- [ ] Test "Stop Here" button
+- [ ] Restart and test "Continue" button
+
+### Scenario 3: Failed Migration
+
+- [ ] Find or create complex component likely to fail
+- [ ] Start migration
+- [ ] Observe retry attempts in log
+- [ ] Wait for DecisionDialog
+- [ ] Test "Retry" button
+- [ ] Test "Skip" button
+- [ ] Test "Get Help" button (verify AI suggestions shown)
+- [ ] Test "Accept Partial" button
+
+### Scenario 4: Abort During Migration
+
+- [ ] Start migration
+- [ ] Click cancel mid-migration
+- [ ] Verify orchestrator stops
+- [ ] Verify partial results saved
+- [ ] Verify budget tracking accurate
+
+### Scenario 5: Invalid API Key
+
+- [ ] Configure invalid/expired API key
+- [ ] Try to migrate
+- [ ] Verify clear error message
+- [ ] Verify session not in broken state
+- [ ] Verify can reconfigure and retry
+
+## Phase 7: Code Quality
+
+- [ ] Run type check: `npx tsc --noEmit`
+- [ ] Fix any TypeScript errors
+- [ ] Run linter: `npx eslint packages/noodl-editor/src/editor/src/models/migration/MigrationSession.ts --fix`
+- [ ] Fix any ESLint warnings
+- [ ] Add JSDoc comments to new public methods
+- [ ] Remove any debug console.log statements
+- [ ] Ensure all imports are used
+
+## Phase 8: Documentation
+
+- [ ] Update CHANGELOG.md with final summary
+- [ ] Add discoveries to NOTES.md
+- [ ] Update TASK-004 CHANGELOG noting TASK-007 completion
+- [ ] Check if any dev-docs/reference/ files need updates
+
+## Phase 9: Completion
+
+- [ ] Self-review all changes
+- [ ] Verify all success criteria met
+- [ ] Verify all checklist items completed
+- [ ] Commit changes with proper message
+- [ ] Mark task as complete in phase-2 tracking
--- a/dev-docs/tasks/phase-2/TASK-007-wire-ai-migration/NOTES.md
+++ b/dev-docs/tasks/phase-2/TASK-007-wire-ai-migration/NOTES.md
@@ -0,0 +1,181 @@
+# TASK-007 Working Notes
+
+## Research
+
+### Existing Patterns Found
+
+#### AIMigrationOrchestrator Interface
+
+- Located in: `packages/noodl-editor/src/editor/src/models/migration/AIMigrationOrchestrator.ts`
+- Constructor signature:
+
+```typescript
+constructor(
+  apiKey: string,
+  budgetConfig: AIConfig['budget'],
+  config: OrchestratorConfig,
+  onBudgetPause: (state: BudgetState) => Promise<boolean>
+)
+```
+
+- Main method: `migrateComponent(component, code, preferences, onProgress, onDecisionRequired)`
+- Returns: `ComponentMigrationResult`
+
+#### Callback Patterns
+
+The orchestrator expects two key callbacks:
+
+1. **onBudgetPause**: `(state: BudgetState) => Promise<boolean>`
+
+   - Called when spending reaches pause increment
+   - Should show BudgetApprovalDialog
+   - Returns true to continue, false to stop
+
+2. **onDecisionRequired**: `(request: DecisionRequest) => Promise<Decision>`
+   - Called after max retries exhausted
+   - Should show DecisionDialog
+   - Returns user's choice (retry/skip/getHelp/manual)
+
+#### Event Flow in MigrationSession
+
+MigrationSession uses EventDispatcher pattern:
+
+- Notifies listeners with `this.notifyListeners(eventName, payload)`
+- MigrationWizard subscribes to events
+- Events include: 'sessionCreated', 'stepChanged', 'scanProgress', 'progressUpdated', 'logEntry', etc.
+
+### Questions to Resolve
+
+- [x] Where are DecisionRequest and Decision types defined?
+  - Answer: Should be in `packages/noodl-editor/src/editor/src/models/migration/types.ts`
+- [x] How does MigrationWizard subscribe to session events?
+  - Answer: Uses `migrationSessionManager.on(eventName, handler)` pattern
+- [x] Where do we read source code files from?
+  - Answer: From `session.source.path` (original project), not target (copy)
+- [x] How do we construct file paths for components?
+  - Answer: ComponentMigrationInfo should have a `filePath` property from scan results
+
+### Assumptions
+
+- Assumption 1: ComponentMigrationInfo includes `filePath` property - ✅ Need to verify in types.ts
+- Assumption 2: Target path already has directory structure copied - ✅ Validated (executeCopyPhase does this)
+- Assumption 3: BudgetApprovalDialog can be shown during migration - ✅ Validated (async callback pattern supports this)
+- Assumption 4: filesystem.readFile returns string content - ✅ Need to verify API
+
+## Implementation Notes
+
+### Approach Decisions
+
+#### Why Not Use React State for Budget/Decision Dialogs?
+
+**Decision**: Use EventDispatcher pattern instead of lifting state to MigrationWizard
+
+**Reasoning**:
+
+- Keeps orchestrator decoupled from React
+- Follows existing pattern used for scan progress
+- Makes testing easier (can test orchestrator without UI)
+
+#### Where to Store Orchestrator Instance?
+
+**Decision**: Store as class property in MigrationSessionManager
+
+**Reasoning**:
+
+- Needs to be accessible to cancelSession() for abort
+- Scoped to migration lifecycle
+- Follows pattern used for session state
+
+### File Reading Strategy
+
+```typescript
+// Read from SOURCE (original project)
+const sourcePath = `${this.session.source.path}/${component.filePath}`;
+const code = await filesystem.readFile(sourcePath);
+
+// Write to TARGET (copy)
+const targetPath = `${this.session.target.path}/${component.filePath}`;
+await filesystem.writeFile(targetPath, migratedCode);
+```
+
+### Event Names to Add
+
+Need to add new events to MigrationSessionManager:
+
+- `budgetPauseRequired` - When orchestrator needs budget approval
+- `decisionRequired` - When orchestrator needs retry decision
+- `componentMigrated` - After each component completes (for progress updates)
+
+### Gotchas / Surprises
+
+- None yet - implementation not started
+
+### Useful Commands
+
+```bash
+# Search for ComponentMigrationInfo type definition
+grep -r "interface ComponentMigrationInfo" packages/noodl-editor/
+
+# Find how filesystem API is used
+grep -r "filesystem.readFile" packages/noodl-editor/src/editor/
+
+# Check existing event listener patterns
+grep -r "migrationSessionManager.on" packages/noodl-editor/src/editor/
+
+# Test build after changes
+npm run build:editor
+
+# Type check only
+npx tsc --noEmit -p packages/noodl-editor/tsconfig.json
+```
+
+## Debug Log
+
+_Add entries as you work through implementation_
+
+### [Date/Time] - Phase 1: DecisionDialog Component
+
+- Trying: [what you're attempting]
+- Result: [what happened]
+- Next: [what to try next]
+
+### [Date/Time] - Phase 2: Budget Approval Flow
+
+- Trying: [what you're attempting]
+- Result: [what happened]
+- Next: [what to try next]
+
+### [Date/Time] - Phase 3: Decision Flow
+
+- Trying: [what you're attempting]
+- Result: [what happened]
+- Next: [what to try next]
+
+### [Date/Time] - Phase 4: executeAIAssistedPhase Implementation
+
+- Trying: [what you're attempting]
+- Result: [what happened]
+- Next: [what to try next]
+
+## Discoveries for LEARNINGS.md
+
+_Note any non-obvious patterns or gotchas discovered during implementation that should be added to dev-docs/reference/LEARNINGS.md_
+
+### Example Discovery Template
+
+**Context**: What were you trying to do?
+
+**Discovery**: What did you learn?
+
+**Location**: What files/areas does this apply to?
+
+**Keywords**: [searchable terms for future reference]
+
+---
+
+## References
+
+- [AIMigrationOrchestrator.ts](../../../packages/noodl-editor/src/editor/src/models/migration/AIMigrationOrchestrator.ts)
+- [BudgetController.ts](../../../packages/noodl-editor/src/editor/src/models/migration/BudgetController.ts)
+- [MigrationSession.ts](../../../packages/noodl-editor/src/editor/src/models/migration/MigrationSession.ts)
+- [types.ts](../../../packages/noodl-editor/src/editor/src/models/migration/types.ts)
--- a/dev-docs/tasks/phase-2/TASK-007-wire-ai-migration/README.md
+++ b/dev-docs/tasks/phase-2/TASK-007-wire-ai-migration/README.md
@@ -0,0 +1,348 @@
+# TASK-007: Wire AI Migration Backend
+
+## Metadata
+
+| Field              | Value                        |
+| ------------------ | ---------------------------- |
+| **ID**             | TASK-007                     |
+| **Phase**          | Phase 2                      |
+| **Priority**       | 🟠 High                      |
+| **Difficulty**     | 🟡 Medium                    |
+| **Estimated Time** | 3-4 hours                    |
+| **Prerequisites**  | TASK-004 (complete)          |
+| **Branch**         | `task/007-wire-ai-migration` |
+
+## Objective
+
+Connect the fully-built AI migration infrastructure (AIMigrationOrchestrator, ClaudeClient, BudgetController) to the MigrationSession's `executeAIAssistedPhase()` stub to enable end-to-end AI-powered component migration.
+
+## Background
+
+TASK-004 implemented a comprehensive React 19 migration system with optional AI assistance. During development, all the AI infrastructure components were built and tested:
+
+- **ClaudeClient**: Handles Anthropic API communication with proper prompt engineering
+- **BudgetController**: Manages spending limits, pause increments, and approval flow
+- **AIMigrationOrchestrator**: Coordinates component migration with retry logic, verification, and decision points
+- **AIConfigPanel**: UI for configuring API key, budget, and preferences
+- **BudgetApprovalDialog**: UI for budget pause confirmations
+- **keyStorage**: Encrypted API key storage with Electron safeStorage
+
+However, the actual integration point in `MigrationSession.executeAIAssistedPhase()` was intentionally left as a stub with a TODO comment. This was done to:
+
+1. Allow the UI and scanning flow to be tested independently
+2. Avoid consuming API credits during development
+3. Defer the wiring work to a focused integration task
+
+**Current Behavior:**
+When a user clicks "Migrate with AI", the system:
+
+- Immediately marks all `needsReview` components as "AI migration not yet implemented"
+- Completes the migration instantly without calling Claude
+- Logs warnings instead of performing actual migrations
+
+**The Problem:**
+Users who configure an API key and budget cannot actually use AI migration, making the entire AI feature non-functional.
+
+## Current State
+
+### Working Components
+
+- ✅ AI configuration UI (AIConfigPanel)
+- ✅ API key validation and encrypted storage
+- ✅ Budget configuration UI
+- ✅ ClaudeClient with prompt engineering
+- ✅ BudgetController with spending tracking
+- ✅ AIMigrationOrchestrator with retry logic
+- ✅ BudgetApprovalDialog component
+- ✅ Scan results correctly identify `needsReview` components
+
+### Non-Working Code Path
+
+- ❌ `MigrationSession.executeAIAssistedPhase()` is a stub (lines ~500-520)
+- ❌ Orchestrator never initialized
+- ❌ Claude API never called
+- ❌ Budget approval dialog never shown
+- ❌ Decision dialog for failed retries doesn't exist
+- ❌ Migrated code never written to target files
+
+### Current Stub Implementation
+
+```typescript
+private async executeAIAssistedPhase(): Promise<void> {
+  if (!this.session?.scan || !this.session.ai?.enabled) return;
+
+  this.updateProgress({ phase: 'ai-assisted' });
+  this.addLogEntry({
+    level: 'info',
+    message: 'Starting AI-assisted migration...'
+  });
+
+  const { needsReview } = this.session.scan.categories;
+
+  for (let i = 0; i < needsReview.length; i++) {
+    const component = needsReview[i];
+
+    this.updateProgress({
+      currentComponent: component.name
+    });
+
+    // TODO: Implement actual AI migration using Claude API
+    await this.simulateDelay(200);
+
+    this.addLogEntry({
+      level: 'warning',
+      component: component.name,
+      message: 'AI migration not yet implemented - marked for manual review'
+    });
+  }
+}
+```
+
+## Desired State
+
+When a user clicks "Migrate with AI" after configuring their API key and budget:
+
+1. **Orchestrator Initialization**: AIMigrationOrchestrator is created with the user's API key and budget settings
+2. **Component Processing**: Each `needsReview` component is sent to Claude for migration
+3. **Budget Pauses**: BudgetApprovalDialog appears when spending reaches pause increments
+4. **Retry Logic**: Failed migrations are automatically retried with different approaches
+5. **Decision Points**: After max retries, user chooses to retry, skip, get help, or accept partial result
+6. **Result Application**: Successfully migrated code is written to target files
+7. **Accurate Reporting**: Final counts reflect actual migration outcomes, not stubs
+
+### User Experience Flow
+
+```
+[Click "Migrate with AI"]
+  ↓
+[Orchestrator initializes]
+  ↓
+[For each component needing AI:]
+  ├─ Read source code from original location
+  ├─ Send to Claude with migration request
+  ├─ [Budget pause?] → Show BudgetApprovalDialog
+  ├─ [Success?] → Write migrated code to target
+  └─ [Failed after retries?] → Show DecisionDialog
+  ↓
+[Display accurate results]
+```
+
+## Scope
+
+### In Scope
+
+- [x] Initialize AIMigrationOrchestrator in `executeAIAssistedPhase()`
+- [x] Read source code for each `needsReview` component
+- [x] Call `orchestrator.migrateComponent()` with proper callbacks
+- [x] Implement `onBudgetPause` callback to show approval dialog
+- [x] Implement `onDecisionRequired` callback for retry decisions
+- [x] Create DecisionDialog component for failed migrations
+- [x] Write successful migrations to target files
+- [x] Update progress log with real results
+- [x] Track actual budget spending
+- [x] Handle orchestrator abort on session cancel
+
+### Out of Scope
+
+- Improving Claude prompts (already done in TASK-004)
+- Changing budget UI (already done in TASK-004)
+- Adding new migration strategies (orchestrator already supports them)
+- Changing the scan logic (TASK-004 complete)
+- Optimizing API costs (can be a future task)
+
+## Technical Approach
+
+### Key Files to Modify
+
+| File                                                                           | Changes                                                                    |
+| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| `packages/noodl-editor/src/editor/src/models/migration/MigrationSession.ts`    | Replace `executeAIAssistedPhase()` stub with real orchestrator integration |
+| `packages/noodl-editor/src/editor/src/views/migration/MigrationWizard.tsx`     | Add state for budget/decision dialogs, wire callbacks                      |
+| `packages/noodl-editor/src/editor/src/views/migration/steps/MigratingStep.tsx` | Display budget approval and decision dialogs during migration              |
+
+### New Files to Create
+
+| File                                                                              | Purpose                                                   |
+| --------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `packages/noodl-editor/src/editor/src/views/migration/DecisionDialog.tsx`         | UI for choosing what to do after failed migration retries |
+| `packages/noodl-editor/src/editor/src/views/migration/DecisionDialog.module.scss` | Styles for DecisionDialog                                 |
+
+### Dependencies
+
+- ✅ `AIMigrationOrchestrator` (already exists)
+- ✅ `ClaudeClient` (already exists)
+- ✅ `BudgetController` (already exists)
+- ✅ `BudgetApprovalDialog` (already exists)
+- ✅ API key storage (already exists)
+- ✅ Types for all interfaces (already exists in `types.ts`)
+
+## Implementation Steps
+
+### Step 1: Create DecisionDialog Component
+
+Create the UI for handling failed migration retries. User can choose to:
+
+- **Retry**: Start over with fresh retry attempts
+- **Skip**: Mark component for manual review
+- **Get Help**: Show AI's detailed manual migration instructions
+- **Accept Partial**: Use the last attempted migration (may need fixes)
+
+### Step 2: Wire Budget Approval Flow
+
+Modify MigrationWizard and MigratingStep to:
+
+- Store budget approval state
+- Show BudgetApprovalDialog when orchestrator pauses
+- Return approval decision to orchestrator
+- Resume or abort based on user choice
+
+### Step 3: Wire Decision Flow
+
+Modify MigrationWizard and MigratingStep to:
+
+- Store decision request state
+- Show DecisionDialog when retries exhausted
+- Handle user's choice (retry/skip/help/manual)
+- Display AI help text if requested
+
+### Step 4: Implement executeAIAssistedPhase()
+
+Replace the stub with real implementation:
+
+- Initialize AIMigrationOrchestrator with API key and budget
+- Loop through `needsReview` components
+- Read source code using filesystem
+- Call `orchestrator.migrateComponent()` with callbacks
+- Handle all possible result types (success/partial/failed/skipped)
+- Write successful migrations to target files
+- Update progress and logs accurately
+
+### Step 5: Handle Session Abort
+
+Ensure orchestrator stops cleanly if:
+
+- User cancels migration
+- Error occurs
+- Budget exhausted
+
+### Step 6: End-to-End Testing
+
+Test the complete flow with real API calls:
+
+- Small budget (e.g., $0.50) to test pause behavior
+- Component that should succeed
+- Component that might fail (to test retry/decision flow)
+- Verify budget tracking is accurate
+- Verify migrated code is written correctly
+
+## Testing Plan
+
+### Manual Testing Scenarios
+
+#### Scenario 1: Successful Migration
+
+- [ ] Configure API key and $2 budget
+- [ ] Scan project with 1-2 simple `needsReview` components
+- [ ] Click "Migrate with AI"
+- [ ] Verify Claude is called
+- [ ] Verify migrated code is written to target
+- [ ] Verify success log entries
+- [ ] Verify budget spending is tracked
+
+#### Scenario 2: Budget Pause
+
+- [ ] Configure API key with $2 budget and $0.50 pause increment
+- [ ] Scan project with 5+ components needing AI
+- [ ] Click "Migrate with AI"
+- [ ] Verify BudgetApprovalDialog appears after ~$0.50 spent
+- [ ] Click "Stop Here" and verify migration stops
+- [ ] Retry, click "Continue" and verify migration resumes
+
+#### Scenario 3: Failed Migration with Retry
+
+- [ ] Configure API key
+- [ ] Scan project with complex component likely to fail
+- [ ] Click "Migrate with AI"
+- [ ] Verify retry attempts are logged
+- [ ] Verify DecisionDialog appears after max retries
+- [ ] Test each decision option:
+  - "Retry" → migration starts over
+  - "Skip" → component marked for manual review
+  - "Get Help" → AI suggestions displayed
+  - "Accept Partial" → last attempt code is used
+
+#### Scenario 4: Abort During Migration
+
+- [ ] Start AI migration
+- [ ] Click cancel button mid-migration
+- [ ] Verify orchestrator stops cleanly
+- [ ] Verify partial results are saved
+- [ ] Verify budget tracking is correct
+
+#### Scenario 5: API Key Invalid
+
+- [ ] Configure invalid API key
+- [ ] Try to migrate
+- [ ] Verify clear error message
+- [ ] Verify session doesn't enter broken state
+
+### Integration Tests
+
+- [ ] Mock ClaudeClient and test orchestrator integration
+- [ ] Test budget controller callback flow
+- [ ] Test decision flow callback
+- [ ] Test file writing with mock filesystem
+
+## Success Criteria
+
+- [x] AIMigrationOrchestrator initializes with correct API key and budget
+- [x] Each `needsReview` component is sent to Claude API
+- [x] Budget approval dialog appears at spending thresholds
+- [x] User can approve/deny additional spending
+- [x] Decision dialog appears after failed retries
+- [x] All decision actions (retry/skip/help/manual) work
+- [x] Successful migrations are written to target files
+- [x] Migration log shows accurate results (not stub warnings)
+- [x] Budget spending is tracked accurately
+- [x] Orchestrator aborts cleanly on session cancel
+- [x] End-to-end test with real Claude API succeeds
+- [x] All TypeScript types are satisfied
+- [x] No console errors during migration
+
+## Risks & Mitigations
+
+| Risk                                        | Mitigation                                                     |
+| ------------------------------------------- | -------------------------------------------------------------- |
+| API costs during testing                    | Use small budgets ($0.50-$1.00), test with minimal projects    |
+| API rate limits                             | Implement exponential backoff in ClaudeClient (already exists) |
+| Invalid API key at runtime                  | Validate key before starting migration, clear error handling   |
+| Budget dialog blocks UI thread              | Use async callbacks, ensure dialogs are dismissible            |
+| Failed migrations corrupt files             | Write to target (copy) not source, verify before writing       |
+| Orchestrator memory leak on long migrations | Ensure orchestrator is disposed after migration                |
+
+## Rollback Plan
+
+If issues are discovered after wiring:
+
+1. **Immediate Rollback**:
+
+   ```typescript
+   // In executeAIAssistedPhase(), wrap in try-catch
+   try {
+     // New orchestrator code
+   } catch (error) {
+     // Fall back to stub behavior
+     this.addLogEntry({ level: 'error', message: error.message });
+   }
+   ```
+
+2. **File Restoration**: Target files are in a copy, source never modified
+3. **Re-disable AI**: Set `ai.enabled = false` in config if orchestrator fails
+4. **Revert Commits**: `git revert` the wiring changes
+
+## References
+
+- [TASK-004: Runtime Migration System](./TASK-004-runtime-migration-system/README.md) - Prerequisite task
+- [03-AI-MIGRATION.md](./TASK-004-runtime-migration-system/03-AI-MIGRATION.md) - Full AI architecture spec
+- [Anthropic API Documentation](https://docs.anthropic.com/claude/reference/getting-started-with-the-api)
+- [React 19 Migration Guide](https://react.dev/blog/2024/04/25/react-19-upgrade-guide)