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

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

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.