doc-sys-validator

Validate System Requirements (SYS) documents against Layer 6 schema standards.

Activation

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

Validation Schema Reference

Schema: ai_dev_ssd_flow/06_SYS/SYS_MVP_SCHEMA.yaml Layer: 6 Artifact Type: SYS

Validation Checklist

0. Folder Structure Validation (BLOCKING)

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

Required Structure:

Validation:

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

Example Valid Structure:

docs/06_SYS/
├── SYS-01_f1_iam/
│   ├── SYS-01_f1_iam.md           ✓ Valid
│   ├── SYS-01.R_review_report_v001.md
│   └── .drift_cache.json
├── SYS-02_f2_session/
│   └── SYS-02_f2_session.md       ✓ Valid

Invalid Structure:

docs/06_SYS/
├── SYS-01_f1_iam.md               ✗ NOT in nested folder

Error Codes:

This check is BLOCKING – SYS must pass folder structure validation before other checks proceed.

1. Metadata Validation

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

Required tags:
  - sys (or sys-template)
  - layer-6-artifact

Forbidden tag patterns:
  - "^system-requirements$"
  - "^sys-doc$"
  - "^sys-\\d{3}$"

2. Structure Validation

Required Sections (15 sections):

• Title (H1): # SYS-NNN: Title
• Section 1: Document Control
• Section 2: Executive Summary
• Section 3: Scope (Boundaries, Inclusions, Exclusions)
• Section 4: Functional Requirements (SYS.NN.01.SS format)
• Section 5: Quality Attributes (Performance, Reliability, Security)
• Section 6: Interface Specifications
• Section 7: Data Management
• Section 8: Testing Requirements
• Section 9: Deployment Requirements
• Section 10: Compliance Requirements
• Section 11: Acceptance Criteria
• Section 12: Risk Assessment
• Section 13: Traceability
• Section 14: Implementation Notes
• Section 15: Change History

Document Control Required Fields:

• SYS ID
• Document Name
• Version
• Date Created
• Last Updated
• Author
• Reviewer
• Status

File Naming: Pattern: SYS-NNN_descriptive_name.md

3. Content Validation

Functional Requirement Format:

• Pattern: SYS.NN.01.SS (unified 4-segment format)
• Table columns: SYS ID, Requirement, Priority, Source, Verification Method
• Element type code: 01 = Functional Requirement
• Priority values: Must Have, Should Have, Could Have, Won’t Have

Quality Attribute Format (4-segment):

• Pattern: SYS.NN.02.SS (02 = Quality Attribute type)
• Example: SYS.08.02.15
• Categories: Performance, Reliability, Scalability, Security, Observability, Maintainability

Quality Attribute Metrics:

REQ-Ready Score:

• Minimum threshold: 90%
• Components: Functional completeness, quality attributes, interfaces, data management, testing, acceptance criteria, traceability

4. Traceability Validation

Layer 6 Cumulative Tags:

• @brd: BRD.NN.01.SS (required)
• @prd: PRD.NN.07.SS (required)
• @ears: EARS.NN.24.SS (required)
• @bdd: BDD.NN.13.SS (required)
• @adr: ADR-NN (required)

Downstream Expected:

• REQ documents
• SPEC documents
• TASKS documents

Same-Type References:

• @related-sys: SYS-NN
• @depends-sys: SYS-NN

Error Codes

Validation Commands

# Validate single SYS document
python ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py docs/06_SYS/SYS-01_example/SYS-01_example.md

# Validate all SYS documents
python ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py docs/06_SYS/

# Check with verbose output
python ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py docs/06_SYS/ --verbose

Validation Workflow

1. Parse YAML frontmatter
2. Check required metadata fields
3. Validate tag taxonomy
4. Verify section structure (1-15)
5. Validate Document Control table
6. Check functional requirement format
7. Check quality attribute format
8. Verify quality categories coverage
9. Validate upstream references (5 required)
10. Calculate REQ-Ready Score
11. Verify file naming convention
12. Generate validation report

Integration

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

Output Format

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

Quality Attribute Coverage:
- Performance: Present/Missing
- Reliability: Present/Missing
- Security: Present/Missing
- Scalability: Present/Missing
- Observability: Present/Missing

Errors: N
Warnings: N
Info: N

[Details listed by severity]

Version History