[BUG] Requirement Validation Fails When Metadata Fields Precede Description

[harikrishnan83]

The requirement SHALL/MUST validation incorrectly checks metadata fields instead of the requirement description, causing false validation failures on valid requirements.

Steps to Reproduce

• Create a spec file with a requirement that includes metadata fields immediately after the title:

  ### Requirement: File Serving
  **ID**: REQ-FILE-001
  **Priority**: P1
  
  The system MUST serve static files from the root directory.
  

• Run validation on the spec file
• Observe validation failure despite the requirement containing proper normative keywords (MUST)

Expected Behavior

The validator should:

• Skip metadata field lines (matching pattern /^\*\*[^*]+\*\*:/)
• Check the actual requirement description for SHALL/MUST keywords
• Pass validation since the description contains "MUST"

Actual Behavior

The validator:

• Extracts the first non-empty line after the requirement header
• Returns ID: REQ-FILE-001 as the "requirement text"
• Fails validation because this metadata field doesn't contain SHALL/MUST
• Ignores the actual requirement description

Root Cause

The extractRequirementText() method in src/core/validation/validator.ts collects all lines after the requirement header, joins them, and returns the first non-empty line. It doesn't skip metadata field lines before extracting the normative description.

Impact

• Severity: Medium-High
• Users cannot use metadata fields in requirements without triggering false validation failures
• Blocks adoption of structured requirement metadata
• Valid, well-formed requirements are incorrectly flagged as invalid
• No workaround exists other than removing metadata fields or placing them after the description

Environment

• Affected component: cli-validate spec
• File: src/core/validation/validator.ts
• Method: extractRequirementText()

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Possible Duplicates

• Bug: Archive validation fails despite requirement headers containing SHALL/MUST #159

Related Issues

• Parser incorrectly treats hash symbols inside code blocks as markdown headers #312
• Archive command fails when creating new spec file with REMOVED Requirements #403
• Line breaks in headers cause validation issues #361
• Error: Change 'my-task' has issues #164

👤 Suggested Assignees

• PeakMNA
• Brandon-Yang-Yu
• smileeunsong
• bcl1713
• grimurjonsson

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[harikrishnan83]

@bindoon is this what you are referring to in #356 ?

[harikrishnan83]

I am still testing this issue and will close it if it is not reproducible after upgrading.

[clay-good]

Closing as fixed by #1281 (shipped in v1.6.0). The unified requirement reader (src/core/parsers/requirement-text.ts) now skips **ID**: / **Priority**: style metadata lines before looking for SHALL/MUST, so structured requirements with metadata fields validate correctly.

Verified on current main: a requirement with metadata lines before "The system MUST..." passes, and the same spec without MUST still fails (the check itself is alive and well). Your metadata may now precede your description with a clear conscience.