# Validation Specification

> Generated by openlore on 2025-01-30
> Source files: src/core/validation/validator.ts, src/core/schemas/*.ts

## Purpose

Provides comprehensive validation of specs and changes using Zod schemas and custom semantic rules. Ensures all specifications follow RFC 2119 conventions and contain required elements.

## Entities

### ValidationReport

| Property | Type | Description |
|----------|------|-------------|
| isValid | boolean | Overall validation result |
| errors | ValidationMessage[] | Critical issues that must be fixed |
| warnings | ValidationMessage[] | Issues that should be addressed |
| info | ValidationMessage[] | Informational notes |

### ValidationMessage

| Property | Type | Description |
|----------|------|-------------|
| code | string | Error code (e.g., "MISSING_SHALL") |
| message | string | Human-readable description |
| location | string | File path or section reference |

## Requirements

### Requirement: SchemaValidation

The system SHALL validate specs and changes against Zod schemas before processing.

#### Scenario: ValidSpecStructure
- **GIVEN** a spec file with valid YAML frontmatter and markdown body
- **WHEN** validation is performed
- **THEN** the schema validation passes
- **AND** no structural errors are reported

#### Scenario: InvalidSpecStructure
- **GIVEN** a spec file missing required sections
- **WHEN** validation is performed
- **THEN** schema validation fails
- **AND** specific missing sections are identified in errors

### Requirement: RFC2119Keywords

The system SHALL require RFC 2119 keywords (SHALL, MUST, SHOULD, MAY) in all requirements.

#### Scenario: RequirementWithShall
- **GIVEN** a requirement containing "The system SHALL validate input"
- **WHEN** keyword validation is performed
- **THEN** validation passes for this requirement

#### Scenario: RequirementWithoutKeyword
- **GIVEN** a requirement stating "The system validates input" (no keyword)
- **WHEN** keyword validation is performed
- **THEN** validation fails with error code "MISSING_SHALL"
- **AND** the error message indicates the requirement needs RFC 2119 keyword

### Requirement: ScenarioPresence

The system SHALL require at least one scenario for each requirement.

#### Scenario: RequirementWithScenarios
- **GIVEN** a requirement with two scenarios defined
- **WHEN** scenario validation is performed
- **THEN** validation passes

#### Scenario: RequirementWithoutScenarios
- **GIVEN** a requirement with no scenarios
- **WHEN** scenario validation is performed
- **THEN** validation fails with error "MISSING_SCENARIOS"

### Requirement: ChangeWhyValidation

The system SHALL validate that change proposals include a "Why" section between 50-500 characters.

#### Scenario: ValidWhySection
- **GIVEN** a change with Why section of 150 characters
- **WHEN** change validation is performed
- **THEN** validation passes

#### Scenario: WhySectionTooShort
- **GIVEN** a change with Why section of 30 characters
- **WHEN** change validation is performed
- **THEN** validation fails with "WHY_TOO_SHORT" error

### Requirement: DeltaLimitEnforcement

The system SHALL enforce a maximum of 20 deltas per change to maintain focused changes.

#### Scenario: ChangeWithinLimit
- **GIVEN** a change with 15 delta operations
- **WHEN** delta count validation is performed
- **THEN** validation passes

#### Scenario: ChangeExceedsLimit
- **GIVEN** a change with 25 delta operations
- **WHEN** delta count validation is performed
- **THEN** validation fails with "TOO_MANY_DELTAS" error

## Technical Notes

- **Implementation**: `src/core/validation/validator.ts`, `src/core/schemas/`
- **Pattern**: Zod schemas + custom rule validators
- **Dependencies**: Zod library for schema validation