title: Frontmatter Validator Architecture — Config-Code Divergence and Resolution authors:

• name: Vadim Rudakov email: rudakow.wadim@gmail.com description: SVA-grounded analysis of three approaches to hub-level frontmatter validation. Identifies config-code divergence as root cause. Recommends config-driven module with CLI entry point (Approach C). tags:

• governance

• architecture date: 2026-03-25 options: type: analysis birth: 2026-03-25 version: 1.0.0 token_size: 2467 id: A-26015 status: active sources:

  • S-26014 produces: []

A-26015: Frontmatter Validator Architecture — Config-Code Divergence and Resolution¶

Problem Statement¶

The hub config (conf.json) defines a complete type system: 10 document types, block composition (identity, discovery, lifecycle), a field registry of 16 fields, and a tag vocabulary. No script enforces this type system at the hub level.

Two domain scripts — check_adr.py and check_evidence.py — independently implement partial frontmatter validation against their spoke configs. Six of ten types (tutorial, guide, policy, package_spec, script_instruction, service) have zero validation.

The gap between what the config declares and what the scripts enforce grows with every type added to the registry. This is a config-code divergence problem, not a code-sharing problem.

Duplication inventory¶

Both domain scripts independently implement:

• Config loading with parent_config resolution

• YAML frontmatter parsing from markdown

• Date format validation (YYYY-MM-DD regex from hub)

• Tag validation against parent config vocabulary

• Required field presence checking

The duplication exists because validation logic was written before the hub config existed. ADR-26042 and the JSON migration (ADR-26054) came later. The scripts never refactored to derive from the hub type system.

Approach Evaluation¶

Assumptions under test¶

SVA constraint audit (ADR-26037)¶

Calibration note on A/C5: Approach A does reuse hub config, but through domain-script interpretation rather than direct hub-driven validation. The violation is that the hub type system is not authoritative — each script decides independently which rules to enforce. This is a weaker violation than ignoring the hub entirely, but still means hub and scripts can diverge silently.

WRC assessment (Claude Opus 4.6 analysis)¶

Approach A — Library Module

WRC = (0.85 × 0.35) + (0.80 × 0.25) + (0.55 × 0.40) = 0.72 — PoC-only.

Approach B — Standalone Validator

WRC = (0.90 × 0.35) + (0.85 × 0.25) + (0.88 × 0.40) = 0.88 — Production-adaptable. Held back by medium migration effort and unresolved type discovery.

Approach C — Config-Driven Module with CLI Entry Point (generated)

Combines B’s config-driven architecture with incremental migration:

1. Importable module: validate_frontmatter(path, repo_root) → list[Error]

2. CLI entry point for pre-commit: python -m tools.scripts.check_frontmatter

3. Domain scripts import module, replacing frontmatter logic incrementally

4. CLI covers all types immediately, including 6 with no domain script

WRC = (0.90 × 0.35) + (0.85 × 0.25) + (0.92 × 0.40) = 0.90 — Production-ready.

Methodology comparison¶

Key Insights¶

Root cause: config-code divergence¶

The duplication between domain scripts is a symptom. The root cause is that validation logic predates the hub config. Approach A treats the symptom (shared functions). Approach C treats the cause (hub config becomes authoritative).

Type discovery via frontmatter¶

The validator parses frontmatter first (generic operation), reads options.type from the result, then applies type-specific rules. No directory mapping needed — files are self-describing. Missing or unrecognized options.type is itself a validation error, not a discovery problem.

Scope boundary: full frontmatter ownership (WRC 0.91)¶

A follow-up SVA analysis evaluated three scope options:

• Hub-only (WRC 0.67, PoC-only) — validate blocks and field registry only, spoke validation stays in domain scripts. C5/C6 violations: domain scripts still implement spoke frontmatter logic, new types need new scripts.

• Presence yes, values no (WRC 0.54, rejected) — check field existence from hub+spoke, but value validation (statuses, severity) stays in domain scripts. C4 violation: splits one concern across two scripts with non-obvious boundary.

• Full frontmatter (WRC 0.91, production-ready) — load spoke config via options.type, validate all frontmatter: presence, format, and allowed values. No SVA violations. Spoke configs already contain everything needed.

The scope boundary becomes:

Incremental migration eliminates the B risk¶

Approach B’s weakness is big-bang migration. Approach C derisks this: domain scripts delegate to the shared module one at a time. At any point, both old and new validation coexist. The CLI entry point provides immediate coverage for uncovered types regardless of migration progress.

vadocs extraction alignment¶

Approach C’s module boundary (validate_frontmatter() + resolve_type() + load_config_chain()) maps directly to vadocs.core in Phase 1.3. The CLI entry point becomes vadocs docs check-frontmatter. Domain scripts become thin wrappers calling vadocs.docs.check_adr(). The package boundary is designed from day one.

Pitfalls¶

1. Type discovery ambiguity — files outside recognized directories with no type field must have an explicit fallback (skip with warning, not silent).

2. Block inheritance — validator must enforce strict additive semantics: spokes can add fields to blocks, never remove.

3. Pre-commit overlap during migration — temporary double-validation between check-frontmatter and domain scripts must not produce conflicting errors.

4. conf.json as policy file — modifications to types or required change what passes validation; protect with review policy.

References¶

• ADR-26036: Config File Location and Naming Conventions

• ADR-26037: SVA Constraint Framework

• ADR-26042: Common Frontmatter Standard

• ADR-26054: JSON as Governance Config Format

• TD-005: check_frontmatter.py needed for hub-level validation

• devops_consultant.json system prompt (Claude Opus 4.6 analysis)