Tags & rules

On the assembly deck, a droid is built from a small set of standard parts — chassis, sensor, manipulator — and each part gets QA stamps before it leaves the line. mediva works the same way: tags are the parts, rules are the stamps.

mediva has two building blocks: tags (the construct) and rules (the checks you attach). Snap a few parts together, stamp each one, and you've described exactly the document you'll accept.

Tags

A tag is the construct you attach rules to. Most tags wrap content — you open and close them — while document and front are structural markers that take no end tag. The full parts bin:

block · table · list · taskList · evidenceList · choice · code · media · prose · document · front

Use evidenceList when each bullet is proof, verification, or a source-backed claim rather than just another list item. Both taskList and choice are checkbox lists, split by intent: a taskList is a checklist whose boxes should all get ticked (allChecked), while a choice is a pick-from-options control (oneChecked for single-select, minChecked/maxChecked to bound a multi-select). block is the recursive container — a heading plus any nested tags — and is what most sections are; reach for prose only when you want to constrain a stretch of pure narrative text (minWords/maxWords/noPlaceholder) that must hold no list, table, or checkbox structure.

<!-- mdv: table -->
| System    | Status |
| --------- | ------ |
| Hyperdrive| ?      |
<!-- mdv: endtable -->

See every tag in the Reference.

Rules

A rule is a check on a tag — a QA stamp — written one of two ways:

• flag — required, noPlaceholder, allChecked
• option — minWords=20, cols=Area,Owner, lang=sh

Stack as many stamps as the part needs:

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

That block must exist, carry at least 20 real words, and contain no TODO/TBD placeholder — three stamps, one part. Each rule belongs to a family (presence, content, strictness, …) — the category you'll see in the reference's Props table.

Content rules

Beyond word counts, two stamps inspect what a section's body actually says. contains demands something be present; forbid demands something be absent. contains values can be a block-type name (table, code, image, …), a /regex/, or a "quoted literal"; forbid values are a /regex/, a "quoted literal", or bare comma-separated literal terms (no block types). Both accept a comma-separated list.

<!-- mdv: block required contains=table,/because/ forbid=/tbd|tba/i -->
## Decision

State the call, justify it with the word "because", and back it with a table.
<!-- mdv: endblock -->

contains=table,/because/ requires both a table and prose matching /because/ (a raw substring regex — add \b…\b if you need a whole-word match); contains=code,image would require both a code block and an image. forbid=/tbd|tba/i rejects the body if "TBD" or "TBA" appears in any case — regexes are case-sensitive unless you add the i flag. A typo'd block type (contains=heading — a heading is not a block) is caught as a compile error, not a silent pass.

Strictness

Some parts support a closure stamp that forbids anything undeclared — exactLabels (checklists), noExtraCols (tables), noExtraSections (sections). Add it to go from "must contain" to "exactly this, nothing smuggled aboard." See Strictness.

A rule's severity can also be retuned or silenced per directive with Severity overrides.

Why not regex?

mediva checks Markdown structure, so a checklist contract can say "exactly these labels, all checked" without rebuilding a parser in regex.

The regex version starts brittle fast:

/## Checklist\s+[-*] \[x\] Tests added or updated\s+[-*] \[x\] Docs updated(?!\s+[-*] \[[ x]\])/m

The mediva version says the thing directly:

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

A tag knows it's a table, a checklist, a code fence — so rules read the document's structure, not its bytes. If the checklist is missing, unchecked, renamed, or has an extra line, mediva points at the exact failing line on the bench instead of a cryptic byte offset. Regex sees a wall of characters; mediva sees the droid.

Next: tune the contract with Strictness, Overrides, Frontmatter, and Evidence lists. Keep the Reference nearby for the full prop catalog, and use the Glossary when the vocabulary gets dense.