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

Validation Checklist

0. Folder Structure Validation (BLOCKING)

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

Required Structure:

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:

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):

# CTR-NN: Title

Optional Appendices:

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

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

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 companion YAML schema file exists
7. Validate YAML schema (OpenAPI 3.x or JSON Schema)
8. Check Error Handling section (Error Codes table)
9. Verify Provider/Consumer in Contract Definition
10. Check Examples section (success and failure)
11. Validate upstream references (7 required)
12. Verify file naming convention
13. 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

docs/08_CTR/CTR-NN_{slug}/