Contracts

A contract is your existing Markdown template plus hidden <!-- mdv: --> rules — a PR template that can fail CI.

Captain's Log, Stardate 47988. Every away mission ends with a report filed to Starfleet. The format never changes: who went, what happened, what they brought back. The form is the contract; the mission is the document.

A contract is a .mdv.md file: ordinary Markdown annotated with <!-- mdv: … --> directives. It describes the Markdown you expect; mediva checks a real document against it. Think of it as the standing orders — written once, applied to every mission report that comes in.

Anatomy

Here's the away-team report contract every starship uses before transmitting a release.md:

<!-- mdv: document -->

<!-- mdv: block required minWords=20 -->
## Summary
<!-- mdv: endblock -->

<!-- mdv: list required minItems=1 -->
## Changes
<!-- mdv: endlist -->

• <!-- mdv: <tag> <rules> --> opens a tag and attaches rules to it.
• <!-- mdv: end<tag> --> closes it.
• document and front are markers — they take no end tag.
• Plain Markdown between directives is the contract's own structure (the headings the document must match — ## Summary, ## Changes). By default their order isn't enforced; add the ordered (or strict) structure atom when sequence matters — see Strictness.

A contract reads like the LCARS template on the bridge: the slots are fixed, the crew fills them in, and nothing transmits until every slot is real. Hand it a document with a thin Summary and an empty Changes list and it says exactly what's wrong and where:

log.md:3  error  [too-few-words] The "Summary" section is too short (3 words).
log.md:7  error  [empty-section] The "Changes" section needs a list with at least one item.

Drop the ## Summary heading entirely and you get [missing-section] instead — the contract notices what isn't there, not just what's malformed.

That can be as small as turning a normal PR template heading into an enforceable slot:

<!-- mdv: block required minWords=20 noPlaceholder -->
## Summary
<!-- mdv: endblock -->

Where contracts live

Keep a contract beside what it checks — same shelf, same shuttle bay:

• README.mdv.md next to README.md
• .github/pull_request_template.md (mediva can validate PR bodies against it)
• docs/changelog.mdv.md for your CHANGELOG.md

One contract validates many documents — write the shape once, check every output. The Enterprise doesn't redesign the report form for every planet; it reuses one and lets the contents vary.

Validated against the generated document

mediva checks the rendered Markdown, not the contract. The contract's example rows and prose are the spec; the document under test is what must conform. That's the point: catch drift in generated or hand-edited Markdown before it ships — before the report reaches Starfleet Command and someone notices the Summary is blank.

Next: Tags & rules.