doc-ears-validator（文档耳朵验证器）

doc-ears-validator

Validate EARS (Easy Approach to Requirements Syntax) documents against Layer 3 schema standards.

Activation

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

Validation Schema Reference

Schema: ai_dev_ssd_flow/03_EARS/EARS_MVP_SCHEMA.yaml Layer: 3 Artifact Type: EARS

Validation Checklist

0. Folder Structure Validation (BLOCKING)

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

Required Structure:

Validation:

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

Example Valid Structure:

docs/03_EARS/
├── EARS-01_f1_iam/
│   ├── EARS-01_f1_iam.md          ✓ Valid
│   ├── EARS-01.A_audit_report_v001.md
│   ├── EARS-01.R_review_report_v001.md  (legacy)
│   └── .drift_cache.json
├── EARS-02_f2_session/
│   └── EARS-02_f2_session.md      ✓ Valid

Invalid Structure:

docs/03_EARS/
├── EARS-01_f1_iam.md              ✗ NOT in nested folder

Error Codes:

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

1. Metadata Validation

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

Required tags:
  - ears (or ears-template)
  - layer-3-artifact

Forbidden tag patterns:
  - "^ears-requirements$"
  - "^ears-\\d{3}$"

2. Structure Validation

Required Sections (6-Section MVP Structure):

• Title (H1): # EARS-NN: Title
• Document Control (unnumbered) - Metadata with BDD-Ready Score
• Section 1: Purpose and Context - Business and technical objectives
• Section 2: EARS in Development Workflow - SDD position and EARS role
• Section 3: Requirements - Event-Driven, State-Driven, Unwanted Behavior, Ubiquitous
• Section 4: Quality Attributes - Performance, Security, Reliability
• Section 5: Traceability - Upstream sources, downstream artifacts, tags
• Section 6: References - Internal and external documentation

Document Control Required Fields:

• EARS ID
• Document Name
• Version
• Date Created
• Last Updated
• Author
• Status
• Source PRD

File Naming: Pattern: EARS-NNN_descriptive_name.md

3. Content Validation

EARS Requirement Patterns:

Requirement ID Format:

• Pattern: EARS.NN.EE.SS (3-segment format)
• Example: EARS.01.2401

BDD-Ready Score:

• Minimum threshold: 90%
• Components: Pattern compliance, requirement clarity, testability, traceability

4. Traceability Validation

Layer 3 Cumulative Tags:

• @brd: BRD.NN.01.SS (required)
• @prd: PRD.NN.07.SS (required)

Downstream Expected:

• BDD scenarios
• ADR documents
• SYS requirements

Same-Type References:

• @related-ears: EARS-NN
• @depends-ears: EARS-NN

Error Codes

Validation Commands

# Validate single EARS document
python ai_dev_ssd_flow/03_EARS/scripts/validate_ears.py docs/03_EARS/EARS-001_example.md

# Validate all EARS documents
python ai_dev_ssd_flow/03_EARS/scripts/validate_ears.py docs/03_EARS/

# Check with verbose output
python ai_dev_ssd_flow/03_EARS/scripts/validate_ears.py docs/03_EARS/ --verbose

Validation Workflow

1. Parse YAML frontmatter
2. Check required metadata fields
3. Validate tag taxonomy
4. Verify section structure (6-section MVP)
5. Validate Document Control table
6. Check EARS pattern compliance
7. Verify SHALL/SHOULD/MAY keywords
8. Validate upstream references
9. Calculate BDD-Ready Score
10. Verify file naming convention
11. Generate validation report

EARS Pattern Detection

patterns = {
    'ubiquitous': r'^The\s+\[?\w+\]?\s+SHALL\s+',
    'event_driven': r'^WHEN\s+.+\s+THE\s+\[?\w+\]?\s+SHALL\s+',
    'state_driven': r'^WHILE\s+.+\s+THE\s+\[?\w+\]?\s+SHALL\s+',
    'unwanted': r'^IF\s+.+\s+THEN\s+THE\s+\[?\w+\]?\s+SHALL\s+',
    'optional': r'^WHERE\s+.+\s+IS\s+SUPPORTED\s+THE\s+\[?\w+\]?\s+SHALL\s+'
}

Integration

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

Output Format

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

Pattern Compliance:
- Ubiquitous: N requirements
- Event-Driven: N requirements
- State-Driven: N requirements
- Unwanted: N requirements
- Optional: N requirements

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.