doc-req-validator

Validate Atomic Requirements (REQ) documents against Layer 7 schema standards.

Activation

Invoke when user requests validation of REQ documents or after creating/modifying REQ artifacts.

Validation Schema Reference

Schema: ai_dev_flow/REQ/REQ_SCHEMA.yaml Layer: 7 Artifact Type: REQ

Validation Checklist

0. Folder Structure Validation (BLOCKING)

Nested Folder Rule: ALL REQ documents MUST be in nested folders regardless of size.

Required Structure:

Validation:

1. Check document is inside a nested folder: docs/07_REQ/REQ-NN_{slug}/
2. Verify folder name matches REQ ID pattern: REQ-NN_{slug}
3. Verify file name matches folder: REQ-NN_{slug}.md
4. Parent path must be: docs/07_REQ/

Example Valid Structure:

docs/07_REQ/
├── REQ-01_f1_iam/
│   ├── REQ-01_f1_iam.md           ✓ Valid
│   ├── REQ-01.R_review_report_v001.md
│   └── .drift_cache.json
├── REQ-02_f2_session/
│   └── REQ-02_f2_session.md       ✓ Valid

Invalid Structure:

docs/07_REQ/
├── REQ-01_f1_iam.md               ✗ NOT in nested folder

Error Codes:

This check is BLOCKING - REQ must pass folder structure validation before other checks proceed.

1. Metadata Validation

Required custom_fields:
  - document_type: ["req", "template"]
  - artifact_type: "REQ"
  - layer: 7
  - architecture_approaches: [array format]
  - priority: ["primary", "shared", "fallback"]
  - development_status: ["active", "draft", "deprecated", "reference"]

Required tags:
  - req (or req-template)
  - layer-7-artifact

Forbidden tag patterns:
  - "^req-document$"
  - "^requirements$"
  - "^atomic-requirements$"
  - "^req-\\d{3}$"

2. Structure Validation

Required Sections (12 sections):

• Title (H1): # REQ-NNN: Title
• Section 1: Document Control
• Section 2: Functional Requirements
• Section 3: Interface Specifications (Protocol/ABC, DTOs, REST API)
• Section 4: Data Schemas (JSON Schema, Pydantic, Database)
• Section 5: Error Handling Specifications (Exception Catalog, Error Response, State Machine)
• Section 6: Configuration Specifications (YAML schema, Environment Variables)
• Section 7: Quality Attributes (Performance, Reliability, Security, Scalability)
• Section 8: Implementation Guidance (Architecture Patterns, Concurrency, DI)
• Section 9: Acceptance Criteria (≥15 criteria across 5 categories)
• Section 10: Verification Methods
• Section 11: Traceability
• Section 12: Change History

Document Control Required Fields:

• Status
• Version
• Date Created
• Last Updated
• Author
• Priority
• Category
• Source Document
• Verification Method
• Assigned Team
• SPEC-Ready Score

File Naming: Pattern: REQ-NNN_descriptive_name.md

3. Content Validation

Requirement Keywords:

• SHALL: Mandatory requirement
• SHOULD: Recommended requirement
• MAY: Optional requirement

Acceptance Criteria Format:

• Pattern: AC-NNN
• Minimum count: 15 criteria
• Categories: Primary Functional (5), Error/Edge Case (5), Quality/Constraint (3), Data Validation (2), Integration (3)

Interface Specifications:

• Protocol/ABC definition with type hints
• DTO definitions (dataclass or Pydantic)
• REST endpoints (optional)

Data Schema Patterns:

• JSON Schema (draft-07)
• Pydantic BaseModel with validators
• Database schema (optional)

SPEC-Ready Score:

• Minimum threshold: 90%
• Components: Interface completeness, data schema, error handling, configuration, quality attributes, implementation guidance, acceptance criteria, traceability

4. Traceability Validation

Layer 7 Cumulative Tags:

• @brd: BRD.NN.EE.SS (required)
• @prd: PRD.NN.EE.SS (required)
• @ears: EARS.NN.EE.SS (required)
• @bdd: BDD.NN.EE.SS (required)
• @adr: ADR-NN (required)
• @sys: SYS.NN.EE.SS (required)

Downstream Expected:

• IMPL documents
• CTR documents
• SPEC documents
• TASKS documents

Same-Type References:

• @related-req: REQ-NN
• @depends-req: REQ-NN

Error Codes

Validation Commands

# Validate single REQ document
python ai_dev_flow/scripts/validate_req.py docs/07_REQ/REQ-001_example.md

# Validate all REQ documents
python ai_dev_flow/scripts/validate_req.py docs/07_REQ/

# Check with verbose output
python ai_dev_flow/scripts/validate_req.py docs/07_REQ/ --verbose

Validation Workflow

1. Parse YAML frontmatter
2. Check required metadata fields
3. Validate tag taxonomy
4. Verify section structure (1-12)
5. Validate Document Control table
6. Check Interface Specifications (Protocol/ABC)
7. Check Data Schemas (JSON/Pydantic)
8. Check Error Handling (Exception Catalog)
9. Verify Acceptance Criteria count (≥15)
10. Validate upstream references (6 required)
11. Calculate SPEC-Ready Score
12. Verify file naming convention
13. Generate validation report

Integration

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

Output Format

REQ Validation Report
=====================
Document: REQ-001_example.md
Status: PASS/FAIL

Interface Coverage:
- Protocol/ABC: Present/Missing
- DTOs: Present/Missing
- REST Endpoints: Present/Missing

Data Schema Coverage:
- JSON Schema: Present/Missing
- Pydantic Models: Present/Missing
- Database Schema: Present/Missing

Acceptance Criteria: N/15

Errors: N
Warnings: N
Info: N

[Details listed by severity]

Version History