doc-adr-validator（文档地址验证器）

doc-adr-validator

Validate Architecture Decision Records (ADR) against Layer 5 schema standards.

Activation

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

Validation Schema Reference

Schema: ai_dev_ssd_flow/05_ADR/ADR_MVP_SCHEMA.yaml Layer: 5 Artifact Type: ADR

Validation Checklist

0. Folder Structure Validation (BLOCKING)

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

Required Structure:

Validation:

1. Check document is inside a nested folder: docs/05_ADR/ADR-NN_{slug}/
2. Verify folder name matches ADR ID pattern: ADR-NN_{slug}
3. Verify file name matches folder: ADR-NN_{slug}.md
4. Parent path must be: docs/05_ADR/

Example Valid Structure:

docs/05_ADR/
├── ADR-01_f1_iam/
│   ├── ADR-01_f1_iam.md           ✓ Valid
│   ├── ADR-01.A_audit_report_v001.md
│   ├── ADR-01.R_review_report_v001.md  (legacy)
│   └── .drift_cache.json
├── ADR-02_f2_session/
│   └── ADR-02_f2_session.md       ✓ Valid

Invalid Structure:

docs/05_ADR/
├── ADR-01_f1_iam.md               ✗ NOT in nested folder

Error Codes:

This check is BLOCKING - ADR must pass folder structure validation before other checks proceed.

1. Metadata Validation

Required custom_fields:
  - document_type: ["adr", "template"]
  - artifact_type: "ADR"
  - layer: 5
  - architecture_approaches: [array format]
  - priority: ["primary", "shared", "fallback"]
  - development_status: ["active", "draft", "deprecated", "reference"]

Required tags:
  - adr (or adr-template)
  - layer-5-artifact

Forbidden tag patterns:
  - "^architecture-decision$"
  - "^decision-record$"
  - "^adr-\\d{3}$"

2. Structure Validation

MVP Template Structure (11 Sections):

Title (H1): # ADR-NN: Title

Document Control Required Fields:

• Project Name
• Document Version
• Date
• Document Owner
• Prepared By
• Status

File Naming: Pattern: ADR-NNN_descriptive_name.md

3. Content Validation

Status Values:

• Proposed
• Accepted
• Deprecated
• Superseded

Context Subsections (Required):

• 4.1 Problem Statement
• 4.2 Background
• 4.3 Driving Forces
• 4.4 Constraints

Decision Subsections (Required):

• 5.1 Chosen Solution
• 5.2 Key Components
• 5.3 Implementation Approach

Consequences Subsections (Required):

• 7.1 Positive Outcomes
• 7.2 Negative Outcomes

Architecture Flow:

• Must contain Mermaid diagram
• Allowed types: flowchart, sequenceDiagram, stateDiagram-v2

ADR-Ready Score:

• Minimum threshold: 90%
• Components: Problem statement, context, decision clarity, consequences, architecture diagram, implementation assessment, traceability

4. Traceability Validation

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

Downstream Expected:

• SYS requirements
• REQ documents
• SPEC documents

Same-Type References:

• @related-adr: ADR-NN
• @supersedes: ADR-NN
• @depends-adr: ADR-NN

Error Codes

Validation Commands

# Validate single ADR document
python ai_dev_ssd_flow/05_ADR/scripts/validate_adr.py docs/05_ADR/ADR-001_example.md

# Validate all ADR documents
python ai_dev_ssd_flow/05_ADR/scripts/validate_adr.py docs/05_ADR/

# Check with verbose output
python ai_dev_ssd_flow/05_ADR/scripts/validate_adr.py docs/05_ADR/ --verbose

Validation Workflow

1. Parse YAML frontmatter
2. Check required metadata fields
3. Validate tag taxonomy
4. Verify 4-part structure
5. Validate required sections (1-10)
6. Check Context subsections
7. Check Decision subsections
8. Check Consequences subsections
9. Verify Mermaid diagram presence
10. Validate upstream references
11. Calculate SYS-Ready Score
12. Verify file naming convention
13. Generate validation report

Integration

• Invoked by: doc-flow, doc-adr (post-creation)
• Feeds into: trace-check (cross-document validation)
• Reports to: quality-advisor

Output Format

ADR Validation Report
=====================
Document: ADR-001_example.md
Status: PASS/FAIL

Structure:
- Context: Complete/Incomplete
- Decision: Complete/Incomplete
- Consequences: Complete/Incomplete
- Architecture Flow: 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.