# Migration Phase Proposals Plan

## Objective

Create OpenSpec change proposals for all remaining migration phases (2-9), review each with Codex MCP, answer questions with best practices, and collect unanswered questions in questions.md.

## Phases Overview

| Phase | Change ID | Spec Dependencies | Parallelizable |
|-------|-----------|-------------------|----------------|
| 1 | migrate-database-schema | database-schema, sql-views-types, sql-business-logic | ✅ DONE |
| 2 | setup-solution-foundation | (infrastructure) | Yes |
| 3 | implement-domain-models | domain-models | Yes |
| 4 | implement-data-access | data-access | Yes |
| 5 | implement-data-sync | data-sync | Yes |
| 6 | implement-search-processing | search-processing | Yes |
| 7 | implement-excel-export | excel-export | Yes |
| 8 | implement-web-api | web-api-auth | Yes |
| 9 | implement-blazor-ui | web-ui | Yes |

## Execution Strategy

### Batch 1: Parallel Proposals (Phases 2-5)
Create 4 proposals in parallel - these are foundational phases.

**Phase 2: setup-solution-foundation**
- Scope: DI configuration, appsettings structure, project references, base infrastructure
- Key deliverables: Program.cs setup, configuration binding, service registration patterns
- No spec dependencies (infrastructure scaffolding)

**Phase 3: implement-domain-models**
- Scope: All domain entities from domain-models spec (52 requirements)
- Key deliverables: Models/, Enums/, Extensions/, validation
- Dependencies: Phase 2 (solution structure)

**Phase 4: implement-data-access**
- Scope: Repository interfaces and implementations (50+ requirements)
- Key deliverables: ILotFinderRepository, IJdeRepository, ICmsRepository, IDbConnectionFactory
- Dependencies: Phase 3 (domain models)

**Phase 5: implement-data-sync**
- Scope: BackgroundService for cache refresh (15+ requirements)
- Key deliverables: DataSyncService, IDataFetcher<T>, health checks
- Dependencies: Phase 4 (data access)

### Batch 2: Parallel Proposals (Phases 6-7)
Create 2 proposals in parallel - these are processing phases.

**Phase 6: implement-search-processing**
- Scope: SqlKata query building, search execution
- Key deliverables: ISearchQueryBuilder, SearchProcessor, filter handlers
- Dependencies: Phase 4 (data access)

**Phase 7: implement-excel-export**
- Scope: ClosedXML workbook generation
- Key deliverables: IExcelExportService, sheet generators, formatting
- Dependencies: Phase 6 (search results)

### Batch 3: Sequential Proposals (Phases 8-9)
Create 2 proposals - API then UI.

**Phase 8: implement-web-api**
- Scope: REST endpoints, SignalR hub, authentication
- Key deliverables: Controllers, StatusHub, IAuthService, LDAP integration
- Dependencies: Phases 5, 6, 7

**Phase 9: implement-blazor-ui**
- Scope: Blazor WASM pages and components
- Key deliverables: Pages/, Components/, SignalR client, Radzen integration
- Dependencies: Phase 8 (API endpoints)

## Proposal Template

Each proposal follows OpenSpec structure:
```
openspec/changes/<change-id>/
├── proposal.md     # Summary, scope, acceptance criteria
├── design.md       # Architecture decisions (when needed)
├── tasks.md        # Ordered work items with validation
└── specs/          # Spec deltas (ADDED/MODIFIED requirements)
    └── <spec-name>/
        └── spec.md
```

## Codex MCP Review Prompts

**For each proposal, run:**
```
Review openspec/changes/<change-id>/ against:
- openspec/specs/<related-spec>/spec.md
- OLD/<legacy-source-files>
- NEW/src/<target-directories>

Verify:
1. All requirements from spec are covered in tasks
2. Dependency order is correct
3. Acceptance criteria are measurable
4. Design decisions align with specs

Report gaps, errors, recommendations.
```

## Best Practice Decisions

Pre-answer common questions with best practices:

| Question | Decision | Rationale |
|----------|----------|-----------|
| Async vs sync methods | Async-first with CancellationToken | Modern .NET pattern |
| Exception handling | Custom typed exceptions per layer | Clear error propagation |
| Configuration | IOptions<T> pattern | Type-safe, testable |
| Logging | ILogger<T> with structured logging | Framework integration |
| Testing | xUnit + Shouldly + NSubstitute | Project constraints (no FluentAssertions) |
| DI lifetime | Scoped for DB, Singleton for config | Standard patterns |
| Nullable refs | Enable project-wide | Modern C# safety |

## Questions Collection

All unanswered questions go to: `openspec/changes/questions.md`

Format:
```markdown
## Phase N: <change-id>

### Question: <topic>
- Context: <why this matters>
- Options: <possible answers>
- Impact: <what depends on this decision>
```

## Execution Order

1. **Create questions.md** - Empty file for collecting questions
2. **Batch 1** - Launch 4 parallel agents for Phases 2-5
3. **Review Batch 1** - Codex MCP review all 4 proposals
4. **Batch 2** - Launch 2 parallel agents for Phases 6-7
5. **Review Batch 2** - Codex MCP review both proposals
6. **Batch 3** - Create Phase 8, then Phase 9 (sequential due to dependencies)
7. **Review Batch 3** - Codex MCP review both proposals
8. **Final validation** - `openspec validate --changes` for all proposals
9. **Summary** - Report all proposals created, questions collected

## Validation Checklist

For each proposal:
- [ ] `openspec validate <change-id> --strict` passes
- [ ] Codex MCP review completed
- [ ] All answerable questions resolved with best practice
- [ ] Unanswerable questions added to questions.md
- [ ] Dependencies on other phases documented

## Critical Files

```
openspec/
├── changes/
│   ├── questions.md                    # Collected unanswered questions
│   ├── migrate-database-schema/        # ✅ DONE
│   ├── setup-solution-foundation/      # Phase 2
│   ├── implement-domain-models/        # Phase 3
│   ├── implement-data-access/          # Phase 4
│   ├── implement-data-sync/            # Phase 5
│   ├── implement-search-processing/    # Phase 6
│   ├── implement-excel-export/         # Phase 7
│   ├── implement-web-api/              # Phase 8
│   └── implement-blazor-ui/            # Phase 9
└── specs/
    ├── database-schema/
    ├── domain-models/
    ├── data-access/
    ├── data-sync/
    ├── search-processing/
    ├── excel-export/
    ├── web-api-auth/
    ├── web-ui/
    ├── sql-business-logic/
    └── sql-views-types/
```

## Spec-to-Phase Mapping

| Spec | Primary Phase | Tasks |
|------|---------------|-------|
| database-schema | Phase 1 (DONE) | DbUp scripts |
| sql-views-types | Phase 1 (DONE) | Views, TVPs |
| sql-business-logic | Phase 1 (DONE) | Stored procedures |
| domain-models | Phase 3 | Entity classes |
| data-access | Phase 4 | Repository interfaces/implementations |
| data-sync | Phase 5 | BackgroundService |
| search-processing | Phase 6 | Query builder |
| excel-export | Phase 7 | ClosedXML service |
| web-api-auth | Phase 8 | Controllers, auth, SignalR |
| web-ui | Phase 9 | Blazor pages/components |