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:

SYS Type Required Location

Monolithic docs/06_SYS/SYS-NN_{slug}/SYS-NN_{slug}.md

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:

Code Severity Description

SYS-E020 ERROR SYS not in nested folder (BLOCKING)

SYS-E021 ERROR Folder name doesn't match SYS ID

SYS-E022 ERROR File name doesn't match folder name

VAL-H001 ERROR Drift cache missing hash for upstream document

VAL-H002 ERROR Invalid hash format (must be sha256:<64 hex chars>)

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:

Category Keywords Metrics

Performance latency, response time, throughput, p50/p95/p99 Response Time, Throughput, Latency

Reliability uptime, availability, MTBF, MTTR Availability, Error Rate

Scalability concurrent, horizontal, vertical Concurrent Users, Data Volume

Security auth, encrypt, RBAC, compliance Authentication, Authorization

Observability log, monitor, alert, trace Logging, Monitoring, Alerting

Maintainability coverage, deploy, CI/CD Code Coverage, Deploy Frequency

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

Code Severity Description

SYS-E001 error Missing required tag 'sys'

SYS-E002 error Missing required tag 'layer-6-artifact'

SYS-E003 error Invalid document_type

SYS-E004 error Invalid architecture_approaches format

SYS-E005 error Forbidden tag pattern detected

SYS-E006 error Missing required section

SYS-E007 error Multiple H1 headings detected

SYS-E008 error Section numbering not sequential (1-15)

SYS-E009 error Document Control missing required fields

SYS-E010 error Missing Functional Requirements (Section 4)

SYS-E011 error Missing Quality Attributes (Section 5)

SYS-E012 error Missing Traceability (Section 13)

SYS-E013 warning File name does not match format

SYS-W001 warning Functional requirements not using SYS.NN.01.SS

SYS-W002 warning Quality attributes not using 4-segment format

SYS-W003 warning Missing Performance category

SYS-W004 warning Missing Security category

SYS-W005 warning Missing upstream tags (require 5)

SYS-W006 warning REQ-Ready Score below 90%

SYS-W007 warning Testing Requirements missing coverage

SYS-I001 info Consider adding p50/p95/p99 latency

SYS-I002 info Consider adding MTBF/MTTR metrics

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

• Parse YAML frontmatter

• Check required metadata fields

• Validate tag taxonomy

• Verify section structure (1-15)

• Validate Document Control table

• Check functional requirement format

• Check quality attribute format

• Verify quality categories coverage

• Validate upstream references (5 required)

• Calculate REQ-Ready Score

• Verify file naming convention

• 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

Version Date Changes Author

1.2 2026-02-27 Migrated frontmatter to metadata ; aligned schema to SYS_MVP_SCHEMA.yaml ; normalized validation commands to ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py

System

1.1 2026-02-11 Nested Folder Rule: Added Section 0 Folder Structure Validation (BLOCKING); SYS must be in docs/06_SYS/SYS-NN_{slug}/ folders; Added error codes SYS-E020, SYS-E021, SYS-E022

1.0 2026-02-08 Initial validator skill definition with YAML frontmatter System

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 .