Doc Validator

doc-validator

Purpose

Validate relationships and consistency across documents in the SDD corpus: broken cross-references, orphaned artifacts, one-way links, cumulative-tag gaps, duplicate or malformed IDs, and traceability-matrix completeness across the 8 layers. This skill is the validator — the framework ships no runtime code; it applies declarative checks against ${CLAUDE_PLUGIN_ROOT}/framework/governance/ and the layer README.md files.

Layer: cross-cutting utility (reads all 8 layers; produces no artifacts).

When to Use

Use for project-wide checks: relationships between documents, cumulative tagging, orphan detection, bidirectional-link consistency, duplicate IDs, deep traceability (with optional link repair), prose/terminology review, and before major releases. It is the single corpus-level validator — it also covers the traceability depth + repair and the prose review that were previously separate skills.

Do NOT use for:

• single-document structure/metadata/content — use that layer's ../doc-<layer>-audit/SKILL.md;
• the definition of the ID-format rules — that authority is ../doc-naming/SKILL.md. (This skill enforces ID format and emits XDOC-E007; use it to check IDs — doc-naming is where the rules live.)

Inputs: docs_path (required), scope (cross-document default / traceability / prose / full), strictness (strict / permissive), auto_fix (repair broken links / regenerate counts where safe), report_format.

Behavior

Cross-document checks

SECTION / TERM / COUNT findings are typically auto-fixable (regenerate counts/sections, normalize terms); the rest are reported for manual fix.

Traceability depth + repair

Beyond the cross-document checks, run the full bidirectional traceability pass:

• Bidirectional symmetry — for each A→B link confirm B→A exists; score (matched pairs / total) × 100 (target ≥ 95%).
• Coverage + orphans — upstream is required for every artifact except BRD; downstream is optional; flag mid-chain artifacts with no downstream and unexpected orphans; report coverage by type.
• Repair (auto_fix) — when enabled, repair only safely-fixable issues: add a missing reciprocal link, regenerate section/COUNT metadata, normalize terminology. Write a timestamped backup first and print a rollback command; never invent placeholder IDs to satisfy a check. Structural/content gaps stay reported for the relevant -fixer.

Prose review (scope: prose)

Review a single file or a folder for prose quality independent of traceability, across four classes:

• DATA — stated counts / status / date logic vs. content (e.g. "5 features" but 4 listed; last_updated earlier than created).
• REF — inline link / anchor / tag-format resolution.
• TYPO — misspellings, doubled words, broken markdown.
• TERM — undefined acronyms, inconsistent or subjective terminology.

Severity follows strictness: under strict, any DATA/REF/TYPO/TERM finding is an error (blocks); under permissive, they are warnings. Honor the project glossary (.aidoc/profile.yaml; see Adaptation) to suppress domain-term TERM false positives. Use before publishing or committing documentation.

Cumulative-tag hierarchy

Authority: ${CLAUDE_PLUGIN_ROOT}/framework/registry/LAYER_REGISTRY.yaml (required_tags) and ${CLAUDE_PLUGIN_ROOT}/framework/governance/TRACEABILITY.md.

ID-format enforcement (IDS)

Require element IDs in the 4-segment form TYPE.NN.SS.xxxx (TYPE ∈ {BRD, PRD, EARS, BDD, ADR, TDD}) and document-level refs in the dash form SPEC-NN/ADR-NN/IPLAN-NN. Reject legacy 3-segment element IDs, the numeric type-code scheme, and any reference to retired 12-layer artifacts — flag each with XDOC-E007. See ../doc-naming/SKILL.md.

Quality gates

ERROR blocks (exit 2); WARNING blocks only under --strict (exit 1); INFO is advisory. Project-wide gates: zero cross-reference errors, zero orphans, 100% bidirectional and 100% cumulative-tag compliance, zero duplicate IDs. Output is a consolidated report (markdown/json/text) listing each finding, its code, and a fix hint.

Adaptation

Read the project adaptation profile (.aidoc/profile.yaml) before validating. Honor this skill's declared knobs:

• active_layers — when a skippable layer (BDD / ADR) is disabled, treat it as absent by design: apply the cascade (drop it from downstream required_tags / can_reference) so the cumulative-tag, orphan, and bidirectional checks do not flag the intentional gap as an error.
• glossary — use the project's preferred terms to normalize and suppress domain-term TERM findings in the prose pass (no false positives on accepted vocabulary).

Ignore unknown / out-of-surface keys; absent a profile, use framework defaults. Authority: ${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md.

Related Resources

• Governance: ${CLAUDE_PLUGIN_ROOT}/framework/governance/DOC_GOVERNANCE_CORE.md · ${CLAUDE_PLUGIN_ROOT}/framework/governance/TRACEABILITY.md · ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
• Layer registry: ${CLAUDE_PLUGIN_ROOT}/framework/registry/LAYER_REGISTRY.yaml
• Per-layer authority: ${CLAUDE_PLUGIN_ROOT}/framework/layers/NN_<X>/README.md
• ID-format authority: ../doc-naming/SKILL.md
• Single-document gates: ../doc-brd-audit/SKILL.md … ../doc-iplan-audit/SKILL.md
• Workflow routing: ../doc-flow/SKILL.md · Diagrams: ../charts-flow/SKILL.md