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: section required minWords=20 noPlaceholder -->
## Summary
<!-- mdv: endsection -->

<!-- mdv: section required -->
## Checklist

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

## Summary
Adds a retry with backoff to the uplink client so a dropped
packet past Jupiter no longer aborts the whole transmission.

## Checklist
- [x] Tests added or updated
- [x] Docs updated

The left tab is the contract; the right is a document that satisfies it. Run one against the other:

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

A clean document prints nothing at all — silence is the pass, and the bay doors open. One that falls short points at the file, line, diagnostic code, message, and a fix: hint, exactly like HAL would:

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

✖ 1 problem (0 errors, 1 warning)

No drama, no guessing. The contract asked for twenty words; the document had four. Substance floors like this one report as warnings by default — the run stays green while the gap is named. When your team wants it to gate, promote it in the contract (minWords=20 error=too-few-words) and the door stays shut until it's fixed; structural breaks (a missing section, a wrong label) are errors out of the box.

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.