doc-ctr-validator

Validate Data Contracts (CTR) documents against Layer 8 schema standards.

Activation

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

Validation Schema Reference

Schema: ai_dev_ssd_flow/08_CTR/CTR_SCHEMA.yaml

Layer: 8 Artifact Type: CTR

Validation Checklist

0. Folder Structure Validation (BLOCKING)

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

Required Structure:

CTR Type Required Location

Dual-File docs/08_CTR/CTR-NN_{slug}/CTR-NN_{slug}.md

• CTR-NN_{slug}.yaml

Validation:

1. Check document is inside a nested folder: docs/08_CTR/CTR-NN_{slug}/
2. Verify folder name matches CTR ID pattern: CTR-NN_{slug}
3. Verify both .md and .yaml files exist with matching names
4. Parent path must be: docs/08_CTR/

Example Valid Structure:

docs/08_CTR/ ├── CTR-01_f1_iam_api/ │ ├── CTR-01_f1_iam_api.md ✓ Valid │ ├── CTR-01_f1_iam_api.yaml ✓ Valid (companion schema) │ ├── CTR-01.R_review_report_v001.md │ └── .drift_cache.json ├── CTR-02_f2_session_api/ │ ├── CTR-02_f2_session_api.md ✓ Valid │ └── CTR-02_f2_session_api.yaml ✓ Valid

Invalid Structure:

docs/08_CTR/ ├── CTR-01_f1_iam_api.md ✗ NOT in nested folder ├── CTR-01_f1_iam_api.yaml ✗ NOT in nested folder

Error Codes:

Code Severity Description

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

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

CTR-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 - CTR must pass folder structure validation before other checks proceed.

1. Metadata Validation

Required custom_fields:

• document_type: ["ctr", "template"]
• artifact_type: "CTR"
• layer: 8
• architecture_approaches: [array format]
• priority: ["primary", "shared", "fallback"]
• development_status: ["active", "draft", "deprecated", "reference"]

Required tags:

• ctr (or ctr-template)
• layer-8-artifact

Forbidden tag patterns:

• "^ctr-document$"
• "^contract$"
• "^api-contract$"
• "^ctr-\d{3}$"

2. Structure Validation (Dual-File Format)

File Format:

• Documentation: .md file

• Schema: .yaml file

• Pattern: CTR-NNN_descriptive_name.md

• CTR-NNN_descriptive_name.yaml

Required Sections (12 Sections + 2 Optional Appendices):

Section Title Required

Title

CTR-NN: Title

(H1) MANDATORY

1 Document Control MANDATORY

2 Context MANDATORY

3 Contract Definition MANDATORY

4 Requirements Satisfied MANDATORY

5 Interface Definition MANDATORY

6 Error Handling MANDATORY

7 Quality Attributes MANDATORY

8 Versioning Strategy MANDATORY

9 Examples MANDATORY

10 Verification MANDATORY

11 Traceability MANDATORY

12 References MANDATORY

Optional Appendices:

Section Title Required

Appendix A Alternatives Considered OPTIONAL

Appendix B Implementation Notes OPTIONAL

Document Control Required Fields:

• Project Name

• Document Version

• Date

• Document Owner

• Prepared By

• Status

3. Content Validation

Status Values:

• Draft

• In Review

• Approved

• Active

• Deprecated

Communication Patterns:

• Synchronous: REST, gRPC, GraphQL

• Asynchronous: Event-driven, Message Queue, Pub/Sub

Error Code Format:

• Pattern: ^[A-Z_]+$

• Examples: INVALID_INPUT, INSUFFICIENT_DATA, RATE_LIMITED, SERVICE_UNAVAILABLE, INTERNAL_ERROR

Versioning:

• Format: MAJOR.MINOR.PATCH (Semantic versioning)

YAML Schema Requirements:

• OpenAPI 3.x or JSON Schema format

• Required: info (title, version, description), paths, components/schemas

• All endpoints must have request and response schemas

4. Traceability Validation

Layer 8 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)

• @req: REQ.NN.EE.SS (required)

Downstream Expected:

• SPEC documents

• TASKS documents

• Code (src/...)

Same-Type References:

• @related-ctr: CTR-NN

• @depends-ctr: CTR-NN

Error Codes

Code Severity Description

CTR-E001 error Missing required tag 'ctr'

CTR-E002 error Missing required tag 'layer-8-artifact'

CTR-E003 error Invalid document_type

CTR-E004 error Invalid architecture_approaches format

CTR-E005 error Forbidden tag pattern detected

CTR-E006 error Missing required section

CTR-E007 error Multiple H1 headings detected

CTR-E008 error Section numbering not sequential (1-12)

CTR-E009 error Document Control missing required fields

CTR-E010 error Missing companion YAML schema file

CTR-E011 error YAML schema is not valid OpenAPI 3.x or JSON Schema

CTR-E012 error Missing request/response schemas for endpoints

CTR-E013 error Missing Error Handling section

CTR-E014 warning File name does not match format

CTR-E015 error Contract Definition missing Provider/Consumer

CTR-E016 error Error Codes table missing

CTR-W001 warning Missing Context Problem Statement

CTR-W002 warning Missing success/failure examples

CTR-W003 warning Missing upstream tags (require 7)

CTR-W004 warning Missing Versioning Strategy Version Policy

CTR-W005 warning Error responses not defined in YAML schema

CTR-W006 warning Missing contract testing requirements

CTR-I001 info Consider adding performance metrics

CTR-I002 info Consider documenting migration strategy

CTR-I003 info Consider adding alternative approaches

Validation Commands

Validate single CTR document (validates both .md and .yaml)

python ai_dev_flow/scripts/validate_ctr.py docs/08_CTR/CTR-001_example.md

Validate all CTR documents

python ai_dev_flow/scripts/validate_ctr.py docs/08_CTR/

Check with verbose output

python ai_dev_flow/scripts/validate_ctr.py docs/08_CTR/ --verbose

Validation Workflow

• Parse YAML frontmatter

• Check required metadata fields

• Validate tag taxonomy

• Verify section structure (1-12)

• Validate Document Control table

• Check companion YAML schema file exists

• Validate YAML schema (OpenAPI 3.x or JSON Schema)

• Check Error Handling section (Error Codes table)

• Verify Provider/Consumer in Contract Definition

• Check Examples section (success and failure)

• Validate upstream references (7 required)

• Verify file naming convention

• Generate validation report

Integration

• Invoked by: doc-flow, doc-ctr (post-creation)

• Feeds into: trace-check (cross-document validation)

• Reports to: quality-advisor

Output Format

CTR Validation Report

Document: CTR-001_example.md Status: PASS/FAIL

Dual-File Check:

• Markdown file: Present
• YAML schema file: Present/Missing
• Schema valid: Yes/No

Contract Structure:

• Provider defined: Yes/No
• Consumer defined: Yes/No
• Error codes table: Present/Missing

Schema Coverage:

• OpenAPI/JSON Schema: Valid/Invalid
• Request schemas: Complete/Incomplete
• Response schemas: Complete/Incomplete
• Error responses: Defined/Missing

Errors: N Warnings: N Info: N

[Details listed by severity]

Related Resources

• CTR Skill: .claude/skills/doc-ctr/SKILL.md

• Naming Standards: .claude/skills/doc-naming/SKILL.md (ID and naming conventions)

• CTR Validation Rules: ai_dev_ssd_flow/08_CTR/CTR_MVP_VALIDATION_RULES.md

• CTR Schema: ai_dev_ssd_flow/08_CTR/CTR_SCHEMA.yaml

Version History

Version Date Changes Author

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

1.1.0 2026-02-08 Updated layer assignment from 9 to 8 per LAYER_REGISTRY v1.6; removed @impl from cumulative tags System

1.0.0 2025-01-15 Initial validator skill definition 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 .