Windows CRLF line endings cause misleading "Change must have a Why section" validation errors

[Coder-Pranav]

Problem

OpenSpec validation fails on Windows with the confusing error "Change must have a Why section" even when the ## Why section exists in the file. This is caused by Windows CRLF line endings (\r\n) breaking the Markdown parser.

Environment

• OS: Windows 11
• OpenSpec Version: v0.3.0
• Node.js: 20.19.0
• Editor: Cursor (any Windows editor that creates CRLF files)

Steps to Reproduce

1. Install OpenSpec on Windows: npm install -g @fission-ai/openspec@latest
2. Initialize project: openspec init (select Cursor)
3. Create proposal: /openspec-proposal Test proposal
4. Run validation: openspec validate test-proposal
5. Result: Error: "Change must have a Why section" (even though section exists)

Root Cause Analysis

Windows editors create files with CRLF line endings (0D 0A in hex), but OpenSpec's Node.js parser expects Unix LF line endings (0A only).

Evidence:

Format-Hex proposal.md | Select-Object -First 1
Shows: 23 23 20 57 68 79 0D 0A (## Why with CRLF)
Should be: 23 23 20 57 68 79 0A 0A (## Why with LF)

Current Workaround

For Windows Users:

Fix existing OpenSpec files

Get-ChildItem "openspec/" -Recurse -Filter "*.md" | ForEach-Object {
    $content = Get-Content $_.FullName -Raw
    if ($content -match "rn") {
        $content = $content -replace "rn", "`n"
        [System.IO.File]::WriteAllText($_.FullName, $content, [System.Text.UTF8Encoding]::new($false))
        Write-Host "Fixed: $($_.Name)"
    }
}

Configure editor for future files
Cursor: File → Preferences → VS Code Settings → "files.eol" → "\n"

[TabishB]

@Coder-Pranav Hey I'm on this! Adding a few e2e tests that run on CI in different environments to pick this up! Will be fixed in the next release 🙇
#78

[TabishB]

This has been fixed as of OpenSpec 0.4.0 🎉
https://github.com/Fission-AI/OpenSpec/releases/tag/v0.4.0

If you faced this issue before update to the latest version:

npm install -g @fission-ai/openspec@latest

then update your project that has OpenSpec initialised as well

npm install -g @fission-ai/openspec@latest