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):

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

2. Requirements with SHALL/MUST Language

Requirements must use SHALL or MUST for validation:

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

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

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:

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

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//
• Commit with message: "Add specification"

6. HANDOFF

• Summarize what was captured
• Note any open questions for user
• Confirm ready for next session

Session Checklist

Session 1: domain-models ✅

• Analyze OLD/DataModel/Models/*.cs (~30 files)
• Document entity definitions, relationships, validation
• Write openspec/specs/domain-models/spec.md
• Validate format: openspec validate --specs
• Codex MCP review
• Commit

Session 2: database-schema ✅

• Analyze OLD/Database/*.sql
• Document tables, columns, indexes, constraints
• Cross-reference with domain-models spec
• Write openspec/specs/database-schema/spec.md
• Validate format: openspec validate --specs
• Codex MCP review
• Commit

Session 3: data-access ✅

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

Session 4: data-sync ✅

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

Session 5: search-processing ✅

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

Session 6: excel-export ✅

• Analyze OLD/WorkerService/Process/ExcelWriter.cs
• Analyze OLD/WorkerService/Helpers/ExcelHelpers.cs
• Document column definitions and formatting
• Document multi-sheet output structure
• Write openspec/specs/excel-export/spec.md
• Validate format: openspec validate --specs
• Codex MCP review
• Commit

Session 7: web-api-auth ✅

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

Session 8: sql-business-logic ✅

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

Session 9: sql-views-types ✅

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

Session 10: web-ui ✅

• Analyze OLD/WebInterface/Views/**/*.cshtml
• Analyze OLD/WebInterface/Scripts/*.js
• Document Login, Search List, Search Create/Edit pages
• Document Search Queue, Refresh Status pages
• Map Kendo UI components to Radzen components
• Include Blazor markup examples for each page
• Write openspec/specs/web-ui/spec.md
• Validate format: openspec validate --specs
• 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.