jdescopingtool/PLANS/proposals.md

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, 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 pattern	Type-safe, testable
Logging	ILogger 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:

## 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