# REQ-003: Markdown Schema Validation System

**Version**: 1.0
**Created**: 2025-10-25
**Status**: Active

## Purpose

Provide automated validation of specification document structure against defined schemas to enforce consistency, completeness, and compliance with organizational standards across all specification types (Jobs, Requirements, ADRs).

## Description

The markdown schema validation system shall validate specification documents against type-specific schemas defined using Pydantic models:

1. **Type Definition System**: Define specification types (Jobs, Requirements, ADRs) using Pydantic models that specify required sections, identifier formats, heading levels, and reference relationships

2. **Multi-Pass Validation**: Implement a 7-pass validation architecture that progressively validates AST construction, section structure, type assignment, structural compliance, content validation, reference extraction, and reference resolution

3. **File Type Matching**: Automatically match markdown files to their specification types based on filename patterns and directory location patterns

4. **Structural Validation**: Verify required sections exist at correct heading levels, identifiers match required patterns, and section hierarchy is correct

5. **Reference Validation**: Extract and validate typed references between specifications (e.g., Requirements must reference Jobs), verify cardinality constraints, and detect invalid or circular references

6. **Layer Enforcement**: Enforce the three-layer hierarchy where Jobs (top level) require no references, Requirements must reference at least one Job, and ADRs can reference Requirements

The system shall provide clear, actionable error messages identifying exactly what is missing or incorrect and how to fix it.

## Acceptance Criteria

### AC-01: Define Specification Types with Pydantic

**Given** a specification type definition in Python
**When** the type is defined as a SpecModule
**Then** it shall specify file_pattern as a regex for matching filenames
**And** it shall specify location_pattern as a regex for matching directory paths
**And** it shall define required and optional sections with heading levels
**And** it shall define identifier format and location (title, heading, metadata)
**And** it shall define allowed references to other specification types
**And** it shall validate the definition at load time using Pydantic

### AC-02: Match Files to Specification Types

**Given** a markdown file in the specification directory
**When** the validator determines the file's type
**Then** it shall check the filename against each type's file_pattern
**And** it shall check the file path against each type's location_pattern
**And** it shall assign the first matching specification type
**And** it shall report an error if no type matches the file

### AC-03: Validate Required Sections

**Given** a specification file with a determined type
**When** the validator checks structural compliance
**Then** it shall parse the markdown and build a section tree
**And** it shall verify each required section exists
**And** it shall verify each section has the correct heading level
**And** it shall report missing sections with suggested headings
**And** it shall report incorrect heading levels with corrections

### AC-04: Validate Identifier Formats

**Given** a specification type with an identifier pattern
**When** the validator checks identifier compliance
**Then** it shall extract the identifier from the specified location (title, heading, metadata)
**And** it shall verify the identifier matches the regex pattern
**And** it shall verify identifier uniqueness within the specified scope (global, module_instance, section)
**And** it shall report malformed identifiers with the expected pattern

### AC-05: Extract and Validate References

**Given** a specification with reference definitions
**When** the validator extracts references
**Then** it shall scan specified sections for reference patterns
**And** it shall extract link text and target identifiers
**And** it shall classify references by type (implements, addresses, depends_on, supersedes)
**And** it shall verify targets exist in the specification set
**And** it shall verify reference cardinality constraints (min/max allowed)
**And** it shall report missing targets and cardinality violations

### AC-06: Enforce Layer Hierarchy

**Given** specifications following the Jobs → Requirements → ADRs hierarchy
**When** the validator checks reference relationships
**Then** it shall verify Jobs have zero references (top level)
**And** it shall verify Requirements reference at least one Job via "addresses"
**And** it shall verify ADRs optionally reference Requirements via "implements"
**And** it shall report Requirements missing Job references as errors
**And** it shall prevent circular references where configured

### AC-07: Provide Clear Error Messages

**Given** validation errors in a specification
**When** the validator reports errors
**Then** it shall identify the file path and line number
**And** it shall describe what is wrong (missing section, invalid ID, broken reference)
**And** it shall suggest how to fix the issue
**And** it shall group errors by severity (error, warning, info)
**And** it shall include context snippets for content errors

### AC-08: Support Custom Type Definitions

**Given** a project with custom specification types
**When** the validator loads type definitions
**Then** it shall discover SpecModule instances from a Python package
**And** it shall support inheritance and composition of types
**And** it shall validate type definitions at load time
**And** it shall allow projects to define domain-specific types
**And** it shall fall back to built-in types (Job, Requirement, ADR) when no custom types are provided

## Jobs Addressed

This requirement addresses the following Jobs-to-be-Done:

- **JOB-003**: Enforce Consistent Specification Structure - This requirement implements automated structure validation with type-specific schemas, enforced standards, clear error messages, and flexible support for different document types, ensuring all specifications are consistent, complete, and machine-parseable.
