doc-validator（文档验证器）

doc-validator

Cross-document validation for SDD framework compliance. For single-document validation, use the dedicated layer validators.

Purpose

Validates relationships and consistency ACROSS documents in the SDD framework.

Core Functions:

• Identifies broken cross-references between documents
• Detects orphaned artifacts (documents with no upstream references)
• Validates bidirectional link consistency
• Checks cumulative tagging hierarchy across layers
• Detects duplicate IDs across documents
• Validates traceability matrix completeness
• Monitors project-wide consistency

This Skill Does NOT:

• Validate single document structure (use {TYPE}_VALIDATION_RULES.md in each artifact directory)
• Validate single document metadata (use {TYPE}_VALIDATION_RULES.md in each artifact directory)
• Validate single document content (use {TYPE}_VALIDATION_RULES.md in each artifact directory)

Dedicated Layer Validators:

ID Format Validation: For unified ID format validation (3-segment element IDs), use doc-naming skill.

Reference: ID_NAMING_STANDARDS.md

Complexity: Medium (cross-reference analysis across multiple documents)

Resource Requirements:

• CPU: Moderate (file parsing, graph traversal)
• Memory: 200-500MB for 100-200 documents
• Disk: Minimal (read-only validation)
• Network: None (local file operations only)

Failure Modes:

• Broken cross-reference: Reports links to non-existent documents
• Missing bidirectional link: Reports one-way references
• Orphaned artifact: Reports documents with no upstream connections
• Duplicate ID: Reports ID conflicts across documents
• Traceability gap: Reports missing required upstream tags

When to Use This Skill

Use doc-validator when:

• Validating relationships BETWEEN documents
• Checking project-wide traceability
• Detecting orphaned artifacts
• Validating bidirectional link consistency
• Checking cumulative tagging across layers
• Detecting duplicate IDs across documents
• Before major releases (project-wide validation)

Do NOT use doc-validator when:

• Validating a single document's structure (use {TYPE}_VALIDATION_RULES.md)
• Validating a single document's metadata (use {TYPE}_VALIDATION_RULES.md)
• Validating a single document's content (use {TYPE}_VALIDATION_RULES.md)
• Validating ID format compliance (use doc-naming skill)
• For detailed traceability analysis (use trace-check skill)

Skill Inputs

Scopes:

• cross-document: Links, references, bidirectional consistency
• traceability: Cumulative tags, upstream/downstream validation
• full: All cross-document validations

Cross-Document Validators

[IMPLEMENTED] Validation Scripts

Auto-Fix Support: SECTION, TERM, COUNT validators support --auto-fix flag.

Reference: See VALIDATION_STANDARDS.md for complete error code registry.

[IMPLEMENTED] Support Scripts

Validation Workflow

graph TD
    A[Input: Documentation Directory] --> B[Collect All Documents]
    B --> C[Build Document Graph]
    C --> D{Cross-Reference Check}
    D -->|Broken| E[XDOC-E001: Broken Link]
    D -->|Valid| F{Bidirectional Check}
    F -->|Missing| G[XDOC-E003: One-Way Reference]
    F -->|Valid| H{Anchor Check}
    H -->|Missing| I[XDOC-E004: Anchor Not Found]
    H -->|Valid| J{Orphan Check}
    J -->|Orphaned| K[XDOC-E005: Orphaned Artifact]
    J -->|Connected| L{Cumulative Tags}
    L -->|Missing| M[XDOC-E002: Missing Tag]
    L -->|Complete| N{Duplicate IDs}
    N -->|Found| O[XDOC-E006: Duplicate ID]
    N -->|Unique| P[Validation PASS]

    E --> Q[Validation Report]
    G --> Q
    I --> Q
    K --> Q
    M --> Q
    O --> Q
    P --> Q

Error Codes Reference

Cross-Document Errors (XDOC)

Section Consistency Errors (SEC)

Diagram Consistency Errors (DIAG)

Terminology Errors (TERM)

Count Consistency Errors (COUNT)

Forward Reference Errors (FWDREF)

Cumulative Tag Validation

Each layer must include ALL upstream tags per the SDD hierarchy:

Validation Script: validate_tags_against_docs.py

Quality Gates

Severity Levels

Project-Wide Gates

Integration Points

With Layer Validators

• Single-document validation delegated to doc-{type}-validator skills
• Cross-document validation runs after layer validators pass
• Combined quality reports

With doc-flow

• Invoked after artifact generation for cross-document checks
• Blocks workflow on cross-reference errors
• Provides link fix suggestions

With trace-check

• Complementary validation (cross-refs vs. detailed traceability)
• Shared cumulative tag validation logic
• Combined traceability reports

With code-review

• Post-commit cross-document validation
• Quality gate enforcement

Usage Examples

Validate Cross-References

python ai_dev_flow/scripts/validate_cross_document.py docs/ --strict

Validate All Links

python ai_dev_flow/scripts/validate_links.py docs/

Validate Cumulative Tags

python ai_dev_flow/scripts/validate_tags_against_docs.py \
  --source docs/ \
  --validate-cumulative \
  --strict

Detect Duplicate IDs

python ai_dev_flow/scripts/validate_requirement_ids.py docs/ --check-duplicates

Full Cross-Document Validation

python ai_dev_flow/scripts/validate_all.py docs/ --scope cross-document

Validation Report Format

=== Cross-Document Validation Report ===

Scope: docs/
Status: FAILED

Cross-Reference Errors (3):
- [XDOC-E001] REQ-02_payments.md references non-existent SPEC-05_gateway.yaml
  → Create target document or fix reference

- [XDOC-E003] ADR-03_caching.md linked from SYS-01 but no reverse link
  → Add @sys reference to ADR-03

- [XDOC-E005] IMPL-04_batch.md has no upstream references
  → Add @req tag to connect to requirements

Cumulative Tag Warnings (2):
- [XDOC-E002] TASKS-02 missing required @adr tag
  → Add @adr: ADR-NN to traceability section

- [XDOC-E002] TASKS-01 missing required @spec tag
  → Add @spec: SPEC-NN to traceability section

Summary:
- Documents analyzed: 45
- Cross-reference errors: 3
- Orphaned artifacts: 1
- Bidirectional compliance: 94% (32/34)
- Cumulative tag compliance: 96% (43/45)

Script Reference

Cross-Document Validation Scripts (Location: ai_dev_flow/scripts/)

Version History