Validate Command

ADDED Requirements

Requirement: Validation SHALL provide actionable remediation steps

Validation output SHALL include specific guidance to fix each error, including expected structure, example headers, and suggested commands to verify fixes.

Scenario: No deltas found in change

WHEN validating a change with zero parsed deltas
THEN show error "No deltas found" with guidance:
- Ensure openspec/changes/{id}/specs/ exists with .md files
- Use delta headers: ## ADDED Requirements, ## MODIFIED Requirements, ## REMOVED Requirements, ## RENAMED Requirements
- Each requirement must include at least one #### Scenario: block
- Try: openspec change show {id} --json --deltas-only to inspect what was parsed

Scenario: Missing required sections

WHEN a required section is missing
THEN the validator SHALL include expected header names and a minimal skeleton:
- For Spec: ## Purpose, ## Requirements
- For Change: ## Why, ## What Changes
- Show an example snippet of the missing section

Requirement: Validator SHALL detect likely misformatted scenarios and warn with a fix

The validator SHALL recognize bulleted lines that look like scenarios (e.g., lines beginning with WHEN/THEN/AND) and emit a targeted warning with a conversion example to #### Scenario:.

Scenario: Bulleted WHEN/THEN under a Requirement

WHEN bullets that start with WHEN/THEN/AND are found under a requirement without any #### Scenario: headers
THEN emit warning: "Scenarios must use '#### Scenario:' headers", and show a conversion template:

#### Scenario: Short name
- **WHEN** ...
- **THEN** ...
- **AND** ...

Requirement: All issues SHALL include file paths and structured locations

Error, warning, and info messages SHALL include:

Source file path (openspec/changes/{id}/proposal.md, .../specs/{cap}/spec.md)
Structured path (e.g., deltas[0].requirements[0].scenarios)

Scenario: Zod validation error

WHEN a schema validation fails
THEN the message SHALL include file, path, and a remediation hint if applicable

Requirement: Invalid results SHALL include a Next steps footer in human-readable output

The CLI SHALL append a Next steps footer when the item is invalid and not using --json, including:

Summary line with counts
Top-3 guidance bullets (contextual to the most frequent or blocking errors)
A suggestion to re-run with --json and/or the debug command

Scenario: Change invalid summary

WHEN a change validation fails
THEN print "Next steps" with 2-3 targeted bullets and suggest openspec change show <id> --json --deltas-only

2.6 KiB Raw Permalink Blame History