Contracts

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: your Markdown template plus hidden <!-- mdv: … --> rules.

AnatomyCopy Anchor Link

<!-- mdv: document -->

<!-- mdv: section required content.words.min=20 -->
## Summary

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

<!-- mdv: list required items.min=1 -->
- Added the retro-thruster diagnostic to the away-team kit.

• section: owns a heading, runs to the next heading of its level, nests.
• leaf (list, table, line, code, media): governs the next such construct inside a section.
• document and front are markers; closers like endsection are optional.
• Contract headings are required headings; ordered enforces their order (Strictness).

A thin Summary, an empty Changes list:

## Summary

A thin summary.

## Changes

log.md
  State: what the document claims; clear it by doing the work or saying it is not done
  3  warning  "Summary" has 3 words, needs at least 20                 too-few-words
              help: Add the missing specifics, not filler
  5  error    "Changes" is empty, needs a list with at least one item  empty-section
              help: Write the section's content, or "Not specified." if there is none

✖ 2 problems (1 error, 1 warning)
  mdv explain <rule-id> for details

Drop ## Summary and you get missing-section. An unclosed fence is a lint error, always, since nothing after it can be read; two headings for one section warn, and rules: { "duplicate-heading": "off" } in mediva.config.mjs turns that off.

Reuse: rule sets and includesCopy Anchor Link

define a rule set once, use= it anywhere; a prop beside the use wins.

<!-- mdv: define prose required content.words.min=20 content.none=@placeholders -->

<!-- mdv: section use=prose -->
## Summary

<!-- mdv: section use=prose content.words.min=40 -->
## Findings

include pulls a section in by path; extends replaces one (spec §5.4, §9.2).

<!-- mdv: include ../shared/release.mdv.md#definition-of-done -->

Where contracts liveCopy Anchor Link

Most specific wins: mirror, then sibling, then folder template. Anywhere else needs --schema.

Validated against the generated documentCopy Anchor Link

The rendered document must conform; the contract is the spec.

Next: Tags & rules.