jdescopingtool/PLANS/legacy-spec-capture-plan.md

# Legacy Spec Capture Plan

## Overview

This plan captures all functionality and requirements from the OLD .NET Framework 4.8 application as OpenSpec specifications, adapted for the NEW .NET 10 architecture.

## Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| Spec organization | 7 functional areas | Natural implementation boundaries |
| Detail level | Behavior-focused | Captures intent without stale code copies |
| Chunking | One spec per session | Keeps context focused, ~15-30 files each |
| Architecture notes | Inline migration notes | Keeps context together per spec |
| Review process | Codex MCP validation | Ensures accuracy and completeness |

## Spec Organization

```
openspec/specs/
├── domain-models/      # WorkOrder, Lot, Item, Search, etc.
├── database-schema/    # SQL Server tables, indexes, constraints
├── data-access/        # JDE/CMS/SQL queries and repositories
├── data-sync/          # Cache refresh, scheduling
├── search-processing/  # Criteria, filters, query execution
├── excel-export/       # Result formatting, file generation
├── web-api-auth/       # Endpoints, SignalR, LDAP auth
├── sql-business-logic/ # Stored procedures and functions
├── sql-views-types/    # SQL views and table-valued parameter types
└── web-ui/             # UI pages, components, Blazor/Radzen mapping
```

## Execution Order

Sessions are ordered by dependency - foundational specs first.

| Session | Spec | Legacy Source | Dependencies |
|---------|------|---------------|--------------|
| 1 | domain-models | DataModel/Models/*.cs | None |
| 2 | database-schema | Database/*.sql | domain-models |
| 3 | data-access | DataModel/Process/*.cs | domain-models, database-schema |
| 4 | data-sync | WorkerService/Process/UpdateProcessor*.cs | data-access, database-schema |
| 5 | search-processing | WorkerService/Models/Reporting/*.cs, Templates/*.cs | domain-models, data-access |
| 6 | excel-export | WorkerService/Process/ExcelWriter.cs, Helpers/*.cs | domain-models, search-processing |
| 7 | web-api-auth | WebInterface/Controllers/*.cs, Hubs/*.cs, Helpers/LDAPHelper.cs | All above |
| 8 | sql-business-logic | Database/StoredProcedures/*.sql, Database/Functions/*.sql | database-schema, domain-models |
| 9 | sql-views-types | Database/Views/*.sql, Database/Types/*.sql | database-schema, domain-models |
| 10 | web-ui | WebInterface/Views/**/*.cshtml, Scripts/*.js | All above |

## OpenSpec Formatting Rules

Specs MUST follow OpenSpec format for CLI validation to pass:

### 1. Purpose Section
Use `## Purpose` (not `## Overview`):
```markdown
## Purpose
Brief description of this area's purpose and scope.
```

### 2. Requirements with SHALL/MUST Language
Requirements must use SHALL or MUST for validation:
```markdown
### Requirement: Search entity
The system SHALL store user search requests containing filter criteria.
```

### 3. Scenarios with WHEN/THEN Format
Use `#### Scenario:` headers with WHEN/THEN format (not Given/When/Then):
```markdown
#### Scenario: Submit new search
- **WHEN** a user creates a search with name and criteria
- **THEN** a new Search record is created with Status = New
```

### 4. Validation Commands
```bash
openspec validate --specs    # Validate all specs (must pass before commit)
openspec list --specs        # List specs with requirement counts
```

## Spec Template

Each spec follows this structure:

```markdown
# <Functional Area> Specification

## Purpose
Brief description of this area's purpose and scope.

## Source Reference
| Legacy Files | Purpose |
|--------------|---------|
| OLD/path/to/file.cs | What this file does |

## Requirements

### Requirement: <Name>
The system SHALL <behavior description - what it does, not how>.

#### Inputs
- Parameter/data inputs

#### Outputs
- What is returned/produced

#### Business Rules
- Validation rules
- Edge cases
- Error conditions

#### Scenario: <Happy path>
- **WHEN** <action or condition>
- **THEN** <expected result>

#### Scenario: <Edge case>
- **WHEN** <action or condition>
- **THEN** <expected result>

## Migration Notes
| Legacy Pattern | New Pattern | Rationale |
|----------------|-------------|-----------|
| Example legacy pattern | Example new pattern | Why the change |

## Open Questions
- Any ambiguities found during analysis
```

## Session Workflow

Each session follows this workflow:

### 1. SCOPE
- Identify legacy files in scope for this spec
- List files to analyze (~15-30 per session)

### 2. ANALYZE
- Read each legacy file
- Extract behaviors, inputs, outputs, business rules
- Note edge cases and error handling
- Identify patterns that need migration notes

### 3. DRAFT
- Write spec.md following the template
- Group related behaviors into requirements
- Write scenarios for key behaviors
- Add migration notes for architecture changes

### 4. REVIEW (Codex MCP + Format Validation)
**4a. Validate OpenSpec format:**
```bash
openspec validate --specs
```
- Fix any format errors before proceeding
- Ensure Purpose section exists, requirements use SHALL/MUST, scenarios use WHEN/THEN

**4b. Use `mcp__codex__codex` to validate content:**
- Cross-reference spec requirements against legacy source files
- Identify any missed behaviors or edge cases
- Verify business rules are accurately captured
- Flag any ambiguities or gaps

### 5. COMMIT
- Save spec.md to openspec/specs/<area>/
- Commit with message: "Add <area> specification"

### 6. HANDOFF
- Summarize what was captured
- Note any open questions for user
- Confirm ready for next session

## Session Checklist

### Session 1: domain-models ✅
- [x] Analyze OLD/DataModel/Models/*.cs (~30 files)
- [x] Document entity definitions, relationships, validation
- [x] Write openspec/specs/domain-models/spec.md
- [x] Validate format: `openspec validate --specs`
- [x] Codex MCP review
- [x] Commit

### Session 2: database-schema ✅
- [x] Analyze OLD/Database/*.sql
- [x] Document tables, columns, indexes, constraints
- [x] Cross-reference with domain-models spec
- [x] Write openspec/specs/database-schema/spec.md
- [x] Validate format: `openspec validate --specs`
- [x] Codex MCP review
- [x] Commit

### Session 3: data-access ✅
- [x] Analyze OLD/DataModel/Process/*.cs (~20 files)
- [x] Document JDE Oracle queries
- [x] Document CMS Sybase queries
- [x] Document SQL Server cache operations
- [x] Write openspec/specs/data-access/spec.md
- [x] Validate format: `openspec validate --specs`
- [x] Codex MCP review
- [x] Commit

### Session 4: data-sync ✅
- [x] Analyze OLD/WorkerService/Process/UpdateProcessor*.cs
- [x] Analyze OLD/WorkerService/dsconfig/*.json
- [x] Document sync schedules (mass/daily/hourly)
- [x] Document table management and incremental updates
- [x] Write openspec/specs/data-sync/spec.md
- [x] Validate format: `openspec validate --specs`
- [x] Codex MCP review
- [x] Commit

### Session 5: search-processing ✅
- [x] Analyze OLD/WorkerService/Models/Reporting/*.cs
- [x] Analyze OLD/WorkerService/Templates/*.cs
- [x] Analyze OLD/DataModel/Models/SearchCriteria.cs
- [x] Document search criteria model and filter types
- [x] Document query building logic
- [x] Write openspec/specs/search-processing/spec.md
- [x] Validate format: `openspec validate --specs`
- [x] Codex MCP review
- [x] Commit

### Session 6: excel-export ✅
- [x] Analyze OLD/WorkerService/Process/ExcelWriter.cs
- [x] Analyze OLD/WorkerService/Helpers/ExcelHelpers.cs
- [x] Document column definitions and formatting
- [x] Document multi-sheet output structure
- [x] Write openspec/specs/excel-export/spec.md
- [x] Validate format: `openspec validate --specs`
- [x] Codex MCP review
- [x] Commit

### Session 7: web-api-auth ✅
- [x] Analyze OLD/WebInterface/Controllers/*.cs
- [x] Analyze OLD/WebInterface/Hubs/StatusHub.cs
- [x] Analyze OLD/WebInterface/Helpers/LDAPHelper.cs
- [x] Document REST endpoints
- [x] Document SignalR hub methods
- [x] Document LDAP authentication flow
- [x] Write openspec/specs/web-api-auth/spec.md
- [x] Validate format: `openspec validate --specs`
- [x] Codex MCP review
- [x] Commit

### Session 8: sql-business-logic ✅
- [x] Analyze OLD/Database/StoredProcedures/*.sql (4 files)
- [x] Analyze OLD/Database/Functions/*.sql (1 file)
- [x] Document SubmitSearch, StartSearch, CompleteSearch, ResetPartialSearches
- [x] Document MatchMis function logic
- [x] Write openspec/specs/sql-business-logic/spec.md
- [x] Validate format: `openspec validate --specs`
- [x] Codex MCP review
- [ ] Commit

### Session 9: sql-views-types ✅
- [x] Analyze OLD/Database/Views/*.sql (7 files)
- [x] Analyze OLD/Database/Types/*.sql (7 files)
- [x] Document union views (WorkOrder, WorkOrderTime, etc.)
- [x] Document LastDataUpdates and WorkOrderTotalScrap views
- [x] Document table-valued parameter types
- [x] Write openspec/specs/sql-views-types/spec.md
- [x] Validate format: `openspec validate --specs`
- [x] Codex MCP review
- [ ] Commit

### Session 10: web-ui ✅
- [x] Analyze OLD/WebInterface/Views/**/*.cshtml
- [x] Analyze OLD/WebInterface/Scripts/*.js
- [x] Document Login, Search List, Search Create/Edit pages
- [x] Document Search Queue, Refresh Status pages
- [x] Map Kendo UI components to Radzen components
- [x] Include Blazor markup examples for each page
- [x] Write openspec/specs/web-ui/spec.md
- [x] Validate format: `openspec validate --specs`
- [x] Codex MCP review
- [ ] Commit

## How to Execute

To run a session, start a new conversation with:

```
Execute Session N from PLANS/legacy-spec-capture-plan.md
```

Each session is self-contained - no context from previous sessions required.