Introduction

mediva enforces that filled-in Markdown templates and generated Markdown actually contain what they promise — it is not a prose style, grammar, or spelling linter.

HAL: "I'm sorry, Dave. I'm afraid I can't merge that. Your Summary section is only four words long."

Somewhere out past Jupiter, a very polite computer is refusing to let a sloppy report through the airlock. That is the whole idea of mediva: a calm, unblinking gatekeeper that checks your Markdown is actually finished before it ships.

mediva checks that a Markdown document matches a contract you write. A contract is plain Markdown with <!-- mdv: … --> rules; mediva validates any document against it and points at the exact rule that failed.

Use it wherever Markdown is produced and can't be fully trusted — LLM output, templates, PR bodies, READMEs, changelogs. Anywhere a machine (or a tired human at 2am) might hand you a document that looks done but isn't.

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

<!-- mdv: taskList required allChecked exactLabels -->
## Checklist
- [ ] Tests added or updated
- [ ] Docs updated
<!-- mdv: endtaskList -->

npx mediva check pr.md --schema pr.mdv.md

A passing document prints 0 errors, 0 warnings — the bay doors open. A failing one points at the file, line, diagnostic code, message, and a fix: hint, exactly like HAL would:

pr.md:1  error  [too-few-words] Too short
    The "Summary" section is too short (4 words).
    fix: Add more detail - aim for at least 20 words.

1 error, 0 warnings

No drama, no guessing. The contract asked for twenty words; the document had four; the door stays shut until that's fixed.

When to use it / when not

Use mediva when Markdown has an expected shape that a machine or template fills in:

• PR bodies and issue templates
• generated, agent, or LLM Markdown
• changelogs, release notes, and ADRs
• any Markdown where "looks done" is not good enough

Reach for something else when you need:

• prose style or grammar checks — use Vale
• spell-checking
• full semantic truth
• arbitrary JSON payload validation — use JSON Schema
• free-form docs with no expected shape

Two ways to run it

• CLI — gate docs and PR bodies in CI, the unsleeping sentry on the comms deck. See CLI.
• TypeScript API — validate programmatically — validateSyntax (shape) and validateState (content, attestation, external), Zod-shaped. See API.

On GitHub, Mediva CI wires this into your repo with one command (npx mediva init): a friendly, signal-not-verdict check on every pull request and issue.

LLMs may repair structure; humans still own state. A missing heading, wrong fence, or empty section can be repaired by autofix — and where there is genuinely nothing to say, it is told to write Not specified. rather than invent facts. But state an LLM cannot see — an unchecked Tests run box, an unresolved citation, a claim only a human can vouch for — is surfaced to a human, never faked.

Where to go next

• Quickstart — install and validate your first file in five minutes (we ship a Mars rover status report).
• Contracts and Tags & rules — the model.
• Glossary — contract vocabulary in one compact table.
• Recipes — complete, runnable tasks: validate LLM output, gate issue forms, enforce changelogs, lock a status table or ADR, and monorepo CI.
• Reference — every tag and the rules you can attach to it.