--- id: vladm3105/aidoc-flow-framework/doc-validator version: "d513373b" license: MIT install: manual updated: 2026-07-27 --- # doc-validator — doc-validator enforces consistency rules across your entire SDD documentation corpus—catching broken links, orphaned artifacts, cumulative-tag gaps, duplicate IDs, and traceability gaps across all 8 layers. It runs declarative checks against your corpus structure and can optionally repair safely-fixable issues like missing reciprocal links or stale metadata. Use it before releases or after batch generation to ensure your documentation chain stays machine-verifiable and traceable. Publisher: vladm3105 · Stars: 16 · Updated: 2026-07-27 Install (manual): `git clone https://github.com/vladm3105/aidoc-flow-framework` ## SKILL.md # 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--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 | Category | Check | Error codes | |----------|-------|-------------| | LINKS | Every markdown/document link and anchor resolves | XDOC-E001, XDOC-E004 | | CROSS-REF | Each cited document/element ID exists in the corpus | XDOC-E001, XDOC-E003 | | ORPHAN | No artifact lacks an upstream connection | XDOC-E005 | | TAGS | Cumulative upstream tags complete per the 8-layer hierarchy | XDOC-E002 | | IDS | Element IDs `TYPE.NN.SS.xxxx`; doc refs `SPEC-NN`/`ADR-NN`/`IPLAN-NN`; no duplicates; no legacy/3-segment/retired forms | XDOC-E006, XDOC-E007 | | MATRIX | Traceability-matrix completeness across 8 layers | XDOC-W001 | | SECTION | Section file count matches metadata | SEC-E001…E003, SEC-W001 | | DIAGRAM | Mermaid entities match prose | DIAG-E001/E002, DIAG-W001/W002 | | TERM | Terminology/acronym consistency | TERM-E001/E002, TERM-W001/W002 | | COUNT | Stated counts match itemized totals | COUNT-E001, COUNT-W001 | | FWDREF | No upstream→downstream references; no cycles | FWDREF-E001/E002, FWDREF-W001 | 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 | Layer | Artifact | Required upstream tags | |-------|----------|------------------------| | 1 | BRD | none | | 2 | PRD | @brd | | 3 | EARS | @brd, @prd | | 4 | BDD | @brd, @prd, @ears | | 5 | ADR | @brd, @prd, @ears, @bdd | | 6 | SPEC | + @adr (5) | | 7 | TDD | + @spec (6) | | 8 | IPLAN | + @tdd (7) | 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_/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` [View on SkillFed](https://skillfed.io/vladm3105/aidoc-flow-framework/doc-validator) · [View on GitHub](https://github.com/vladm3105/aidoc-flow-framework)