doc-spec-validator

Activation

Validation Schema Reference

ai_dev_flow/SPEC/SPEC_SCHEMA.yaml

Validation Checklist

0. Folder Structure Validation (BLOCKING)

docs/09_SPEC/SPEC-NN_{slug}/SPEC-NN_{slug}.yaml

1. Check document is inside a nested folder: docs/09_SPEC/SPEC-NN_{slug}/
2. Verify folder name matches SPEC ID pattern: SPEC-NN_{slug}
3. Verify file name matches folder: SPEC-NN_{slug}.yaml
4. Parent path must be: docs/09_SPEC/

docs/09_SPEC/
├── SPEC-01_f1_iam/
│   ├── SPEC-01_f1_iam.yaml        ✓ Valid
│   ├── SPEC-01.R_review_report_v001.md
│   └── .drift_cache.json
├── SPEC-02_f2_session/
│   └── SPEC-02_f2_session.yaml    ✓ Valid

docs/09_SPEC/
├── SPEC-01_f1_iam.yaml            ✗ NOT in nested folder

1. File Format Validation

File Format:
  - Extension: .yaml (NOT .md)
  - Naming pattern: SPEC-NNN_descriptive_name.yaml
  - Encoding: UTF-8
  - YAML version: 1.2

2. Required Top-Level Fields

Required fields:
  - id: Component identifier (snake_case)
  - summary: Single-sentence description (10-200 chars)
  - metadata: Document control and versioning
  - traceability: Upstream and downstream references
  - architecture: Component architecture and dependencies
  - interfaces: Interface definitions (classes, methods)
  - behavior: Behavioral specifications
  - performance: Performance targets
  - security: Security specifications
  - observability: Metrics, logging, health checks
  - verification: Test scenarios
  - implementation: Implementation specifics

Optional fields:
  - caching
  - rate_limiting
  - circuit_breaker
  - operations
  - changelog
  - maintenance
  - notes

3. Metadata Section Validation

• version: Semantic version (MAJOR.MINOR.PATCH)
• status: draft | review | approved | implemented | deprecated
• created_date: YYYY-MM-DD format
• last_updated: YYYY-MM-DD format
• authors: Array with at least one author (name required)

• task_ready_score
• reviewers
• owners

4. Interfaces Section Validation

• name: PascalCase format
• description: Required
• methods: At least one method required per class

• name: snake_case format
• description: Required
• input: Optional parameters object
• output: Optional return object
• errors: Optional error definitions

5. Performance Section Validation

• latency_targets:
  • p50_milliseconds
  • p95_milliseconds
  • p99_milliseconds
• throughput_targets:
  • sustained_requests_per_second
• resource_limits:
  • cpu_cores_allocated
  • memory_mb_allocated

• p95 must be greater than p50
• p99 must be greater than p95

6. Security Section Validation

• authentication.required: boolean
• authentication.methods: array
• authorization.enabled: boolean
• input_validation.strategy: string

7. Observability Section Validation

• metrics.standard_metrics: array (min 1 item)
• logging.level: DEBUG | INFO | WARN | ERROR
• logging.format: json | text | structured
• health_checks.enabled: boolean
• health_checks.endpoints: array

8. Traceability Validation

• @brd: BRD-NNN:XXX-NNN (required)
• @prd: PRD-NNN:XXX-NNN (required)
• @ears: EARS-NNN:NNN (required)
• @bdd: BDD-NNN:scenario-name (required)
• @adr: ADR-NN (required)
• @sys: SYS-NNN:XXX-NNN (required)
• @req: REQ-NNN:feature-name (required)
• @ctr: CTR-NNN (optional)

• TASKS documents
• Code (src/...)
• Tests (tests/...)

• related_spec: [SPEC-NN]
• depends_spec: [SPEC-NN]

Error Codes

Validation Commands

# Validate single SPEC document
python ai_dev_flow/scripts/validate_spec.py docs/09_SPEC/SPEC-001_example.yaml

# Validate all SPEC documents
python ai_dev_flow/scripts/validate_spec.py docs/09_SPEC/

# Check with verbose output
python ai_dev_flow/scripts/validate_spec.py docs/09_SPEC/ --verbose

Validation Workflow

1. Verify file is valid YAML
2. Check all required top-level fields present
3. Validate metadata section (version, status, dates, authors)
4. Check interfaces section (classes with methods)
5. Validate performance section (latency targets, p50 < p95 < p99)
6. Check security section (authentication, authorization)
7. Validate observability section (metrics, logging, health)
8. Check traceability cumulative tags (7 required)
9. Verify verification section (BDD scenarios)
10. Validate implementation section
11. Check file naming convention
12. Generate validation report

Integration

• Invoked by: doc-flow, doc-spec (post-creation)
• Feeds into: trace-check (cross-document validation)
• Reports to: quality-advisor

Output Format

SPEC Validation Report
======================
Document: SPEC-001_example.yaml
Status: PASS/FAIL

YAML Validity: Valid/Invalid

Required Sections:
- metadata: Present/Missing
- traceability: Present/Missing
- architecture: Present/Missing
- interfaces: Present/Missing
- behavior: Present/Missing
- performance: Present/Missing
- security: Present/Missing
- observability: Present/Missing
- verification: Present/Missing
- implementation: Present/Missing

Interface Summary:
- Classes defined: N
- Methods defined: N

Performance Targets:
- p50: Nms
- p95: Nms (> p50: Yes/No)
- p99: Nms (> p95: Yes/No)

Errors: N
Warnings: N
Info: N

[Details listed by severity]

Related Resources

• SPEC Skill:

  .claude/skills/doc-spec/SKILL.md

• Naming Standards:

  .claude/skills/doc-naming/SKILL.md

  (ID and naming conventions)
• SPEC Validation Rules:

  ai_dev_flow/09_SPEC/SPEC_VALIDATION_RULES.md

• SPEC Schema:

  ai_dev_flow/SPEC/SPEC_SCHEMA.yaml

Version History

docs/09_SPEC/SPEC-NN_{slug}/