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

yaml
1Required custom_fields:
2  - document_type: ["sys", "template"]
3  - artifact_type: "SYS"
4  - layer: 6
5  - architecture_approaches: [array format]
6  - priority: ["primary", "shared", "fallback"]
7  - development_status: ["active", "draft", "deprecated", "reference"]
8
9Required tags:
10  - sys (or sys-template)
11  - layer-6-artifact
12
13Forbidden tag patterns:
14  - "^system-requirements$"
15  - "^sys-doc$"
16  - "^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

bash
1# Validate single SYS document
2python ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py docs/06_SYS/SYS-01_example/SYS-01_example.md
3
4# Validate all SYS documents
5python ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py docs/06_SYS/
6
7# Check with verbose output
8python 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

Implementation Plan Consistency (IPLAN-004)

• Treat plan-derived outputs as valid source mode and verify intent preservation from implementation plan scope/objectives.
• Validate upstream autopilot precedence assumption: --iplan > --ref > --prompt.
• Flag objective/scope conflicts between plan context and artifact output as blocking issues requiring clarification.
• Do not introduce legacy fallback paths such as docs-v2.0/00_REF.