pdv — frontmatter validation for evidence-disciplined corpora

pdv validates the PD-1 frontmatter schema over a markdown corpus: an S1-passing field set (id, status, supersession links, governance fields, lang, aliases, links, class), staleness horizons, and a ban on authored summary/description fields on document-class files — a ban with a measurement behind it: used as a sole locator, a one-line summary layer routed agents to the right document on 52.0% of questions against plain search's 80.4% (doi:10.5281/zenodo.21960138).

It is read-only by construction: it reports, emits a demotion set for a consuming locator (see mentu-navigator), and registers promotions in a read-back meter — it never edits a corpus.

Install & use

npm install -g mentu-pdv

pdv check .                        # validate; exit 1 on actionable errors
pdv check . --json                 # machine-readable report
pdv demotions . > demotions.json   # the artifact a locator consumes
pdv promote docs/x.md --commitment=<id>   # register a promoted artifact in the read-back meter

Per-corpus conventions (status vocabulary, class globs, immutable paths, ignore globs) live in a config file kept outside the corpus — see pdv.config.example.yaml — and are passed with --config.

Design rules

• Fields present are validated; fields absent are counted (adoption is measured, not mandated).
• Staleness demotes ranking, never excludes.
• Findings inside declared immutable paths are report-only.
• Determinism: same tree + same --as-of ⇒ byte-identical output.
• A corpus is one repository; nested repos validate separately.

Evidence discipline

Every behavioral default in this tool traces to a registered study in a public evidence program: the summary ban to doi:10.5281/zenodo.21960138, the demote-never-exclude and read-back-meter semantics to the same program's memory-promotion result (files promoted to a durable memory directory were later read in 2 of 157 eligible cases). Claims not backed by a registered result are design stances, labeled as such in the spec.

License: Apache-2.0.