Diagnostics
Every code mdv prints, with its one-line fix.
SHIP'S COMPUTER: Fault
too-few-words, bay four. I would explain gently, but all I have is a code and a help line.
Every finding ends with its code, and each code links here. mdv explain <code> prints the entry. Advisory codes only warn. Lint codes (markdownlint, unclosed-fence, fenced-output) are always errors: no contract or config setting lowers them.
// mediva.config.mjs: repo-wide ("off" turns it off)
rules: { "too-few-words": "warn" }<!-- mdv: section required content.words.min=20 warn=too-few-words --> one contractSections
missing-section
Missing section · error · Add the section's heading where the contract places it · raised by required, na, requiredWhen
missing-recommended-section
Recommended section missing · warning · Add the section's heading if the section applies here · raised by recommended
empty-section
Empty section · error · Write the section's content, or "Not specified." if there is none · raised by required
needs-content-or-na
Needs content or marker · error · Write the answer, or the contract's empty-state marker if it doesn't apply · raised by na
unmatched-contract
Contract matched nothing · error · Add the contract's sections, or check against the right contract
out-of-order
Sections out of order · error · Move the section to its place in the contract's order · raised by ordered
unexpected-section
Unexpected section · error · Move the content into a declared section, or remove the section · raised by strict
too-few-repeats
Too few section occurrences · error · Add only instances the document really has · raised by occurs
too-many-occurrences
Too many section occurrences · error · Record which instances are true; never delete one just to fit the count · raised by occurs
missing-repeat-instance
No matching section occurrence · error · Add only instances the document really has
unmatched-instance-heading
Heading matches no declared shape · error · Rewrite the heading in the expected format, or remove it · raised by exhaustive
unmatched-construct
Extra construct binds to nothing · error · Merge it into the declared construct, or move it to its own section
exactly-one-group-unmet
Exactly one of a sibling group must be present · error · Decide which one is true here; never keep one just to pass · raised by exactlyOne
forbidden-section-present
Section forbidden under this condition · error · Record which is true, the section or the front matter, and correct the other · raised by forbiddenWhen
missing-conditional-section
Section required by what the document says · error · Write the section, or correct the claim that requires it if that claim is wrong · raised by requiredWhen
Headings
duplicate-heading
Duplicate heading · warning · Rename one of the headings so each section has its own
heading-format
Heading format · error · Rewrite the heading in the required format, keeping its subject · raised by heading., heading., heading.
heading-placeholder
Placeholder heading · error · Replace the placeholder with what the section covers · raised by heading.
heading-wrong-level
Heading at the wrong level · warning · Change the number of # to the required level
Content
placeholder-text
Placeholder left in · error · Write the real content, or "Not specified." if unknown · raised by content.
too-few-words
Too short · warning · Add the missing specifics, not filler · raised by content.
too-many-words
Too long · error · Shorten it without changing what it says · raised by content.
too-many-links
Too many links · error · Remove or merge links, keeping the ones that matter · raised by content.
forbidden-content
Forbidden content · error · Say what is true instead, or drop the claim · raised by content., content., content.
item-mismatch
Item format mismatch · error · Rewrite the item in the required format, keeping its words · raised by items.
pattern-mismatch
Pattern mismatch · error · Rewrite the text in the form the contract spells out · raised by content.
headings-mask-mismatch
Heading outside the collection's shape · error · Rewrite the heading in the collection's format, keeping what it names · raised by headings., headings.
headings-out-of-order
Headings out of order · warning · Move the heading to its sorted position · raised by headings.
first-line-mismatch
First line mismatch · error · Rewrite the first line in the required format, keeping its facts · raised by content.
label-line-mismatch
Labeled value mismatch · error · Write the same value after the label in the required format · raised by mask
missing-line
Missing labeled line · error · Add the labeled line the contract declares · raised by mask
unpaired-disposition
Entry without a disposition · warning · Record how the entry closed, or the honest open state the contract allows · raised by @markers/
sentence-all-missing
No sentence satisfies all patterns · warning · Write one sentence that says every required part, if one is true · raised by content.
sentence-gate-missing
Occurrence missing its in-sentence gate · warning · Add the gate only if it is true, or drop the claim · raised by content.
total-mismatch
Column does not add up to its Total · warning · Recompute the column and fix the wrong cell or the Total · raised by @tables/
column-equation-mismatch
Column equation does not hold · warning · Recompute the row and fix the wrong operand or target · raised by @tables/
return-chain-mismatch
Returns do not compound · warning · Recompute the cumulative return and fix the wrong figure · raised by @tables/
cell-percent-mismatch
Cell percent does not recompute · warning · Recompute count ÷ N × 100 and fix the count or the percent · raised by @tables/
timeline-mismatch
Timeline does not match its stated total · warning · Recompute the span from the timestamps and fix the wrong figure · raised by @lists/
interval-mismatch
Interval omits its estimate · warning · Fix the figure that breaks low ≤ estimate ≤ high · raised by @numbers/
percent-mismatch
Percentage does not recompute · warning · Recompute numerator ÷ denominator × 100 and fix the wrong figure · raised by @numbers/
sum-mismatch
Parts do not sum to the total · warning · Fix a part or the total so they add up · raised by @numbers/
required-set-missing
Required set member missing · warning · Add the missing member next to the others, if it is true · raised by @sets/
missing-block
Missing block · error · Add the block only with what is true, or say it is not done · raised by content.
missing-content
Missing content · error · Add the content the rule asks for, from real facts · raised by content.
sections-identical
Section repeats another section · error · Write what this section really covers, or say its work is not done · raised by content.
deprecated-term
Deprecated term · warning · Replace it with the canonical term from the glossary · raised by @glossary/
undefined-term
Term not in glossary · warning · Use the glossary's spelling, if it is the term meant · raised by @glossary/
invalid-glossary
Glossary source invalid · error · Fix the glossary file so it parses: one H2 per term, or a JSON array
stale
Verification is stale · error · Re-check the section against reality, then update its date · raised by content.
missing-media
No visual evidence · error · Add the real screenshot or video, or the empty-state marker if none exists · raised by na
lead-mismatch
Lead line mismatch · error · Rewrite the section's first line in the required format · raised by content.
thin-definition-item
Definition says too little · error · Say what the term is or does · raised by items.
value-not-allowed
Value not allowed · error · Write the allowed value that is true here · raised by content., content., content., mask, heading., heading., heading., items., col, content., headings., headings.
value-wrong-form
Value in another form · error · Write the same value in the form the contract spells · raised by content., content., mask, heading., heading., items., col, content., headings., headings.
value-not-given
No value given · error · Write the value that is true, or say the work is not done · raised by content., content., content., mask, heading., heading., heading., items., col, title., content., headings., headings.
truncated-output
Output looks truncated · advisory warning · Restore the missing ending from the full content · raised by content.
placement-guarded-far
Marker guards the target, but too far · warning · Move the marker right before or beside the target · raised by @markers/
placement-weak-guarded
Marker is only a link, not stated directly · warning · State the marker as text near the target, not only as a link · raised by @markers/
placement-unguarded
No marker precedes the target · warning · Move the marker before the target · raised by @markers/
placement-unguarded-region
Marker is buried in the trailing region · warning · Move the marker up, next to the target · raised by @markers/
placement-absent
No marker anywhere · warning · Add the marker before the target · raised by @markers/
agent-chatter
Assistant chatter left in · advisory warning · Remove the chatter · raised by content.
chat-preamble
Leading chat preamble · advisory warning · Remove the assistant lines before the document starts · raised by content.
chat-postamble
Trailing chat postamble · advisory warning · Remove the assistant sign-off after the document ends · raised by content.
exemplar-residue
Template exemplar left in · error · Replace the example value with the project's real one · raised by noExemplarResidue
Lists
too-few-items
Too few items · error · Add the real items that belong here, not restatements · raised by items.
list-not-ordered
List must be ordered · error · Use numbered markers (1., 2., 3.) instead of bullets · raised by numbered
list-item-too-short
List item too short · warning · Add the specifics the item records, not filler · raised by items.
malformed-definition-item
Malformed definition item · error · Write the item as Term — description · raised by items.
too-many-items
Too many items · error · Record which items are true; never delete one just to fit the count · raised by items.
Checklists
too-many-checked
Too many boxes checked · warning · Untick the boxes that aren't true · raised by checked.
need-exactly-one
Pick exactly one · error · Tick the one option that is true and untick the rest · raised by checked.
checkbox-missing
Item without a checkbox · error · Write the item with a checkbox: - [ ] <item> · raised by items.
unchecked-items
Unchecked boxes · warning · Tick a box once the task is done; mark it only if it does not apply · raised by items.
tick-without-evidence
Checked without evidence · error · Run what shows it now and record the result, or untick: (not done: reason) · raised by items., items.
weak-tick-evidence
Tick evidence too vague · advisory warning · Run what shows it now and record that result, or untick: (not done: reason) · raised by items., items.
open-item
Item neither done nor marked · error · Finish it now and record what shows it, or keep it open: (not done: reason) · raised by items.
not-done
Work not done · error · Finish the work and record it, or leave the item open with its reason · raised by mask, items.
contradictory-disposition
Tick contradicts its reason · error · Record the truth: done with evidence, or not done or not applicable with why · raised by items., items.
missing-checklist-item
Required item missing · error · Add the item as "- [ ] <label>", or rename the line that means it · raised by labels.
unexpected-checklist-item
Unexpected item · error · Rename it to the template's item, or move it out of the list · raised by labels.
too-few-checked
Too few boxes checked · warning · Do the remaining tasks, then tick only the ones that are true · raised by checked.
Tables
too-few-rows
Too few table rows · error · Add the real rows that belong in the table · raised by rows.
too-many-rows
Too many table rows · error · Record which rows are true; never delete one just to fit the count · raised by rows.
table-columns-mismatch
Table columns mismatch · error · Rename and reorder the header cells to the required columns · raised by columns.
table-extra-columns
Unexpected table column · error · Move the data into a declared column, or remove the column · raised by strict
table-cell-invalid
Invalid table cell · error · Rewrite the cell in the column's required format, keeping its facts · raised by col
table-cell-duplicate
Duplicate table cell · error · Give each row its own value in this column · raised by col
Code blocks
unclosed-fence
Unclosed code fence · error · Add the closing ``` where the code block ends
unclosed-comment
Unclosed HTML comment · error · Close the comment with --> where it ends
markdownlint
Markdown lint · error · Fix the Markdown as markdownlint describes
fenced-output
Whole document is fenced · error · Remove the outer ``` fence pair around the document
code-lang-not-allowed
Code language not allowed · error · Write the example in an allowed language; never relabel the fence to pass · raised by lang., lang.
Frontmatter
frontmatter-unreadable
Front matter cannot be read · error · Write the front matter as one --- block of key: value lines at the top
missing-frontmatter-key
Missing frontmatter key · error · Add the key to the --- block at the top
frontmatter-not-in-source
Frontmatter value not in source · error · Use the source's value exactly, if it is the one meant
frontmatter-placeholder
Placeholder frontmatter value · error · Write the real value, or "Not specified." if there is none
unexpected-frontmatter-key
Unexpected frontmatter key · error · Move what it says into the declared key it belongs to
Title
missing-title
Missing title · error · Pass the title with --title TEXT, or a --context file with one · raised by title, title., title., title.
title-placeholder
Placeholder title · error · Replace the placeholder with what the document is about · raised by title.
title-too-short
Title too short · warning · Write a title that truthfully says what this document is about · raised by title.
Citations
vague-evidence
Too vague to verify · advisory warning · Say what you ran or saw, e.g. "npm test: 312 passed" · raised by items.
missing-citation
Missing citation · error · Cite the real source, e.g. text, or add "(attested: <how>)" · raised by items.
unresolved-citation
Unresolved citation · error · Add the missing definition, or replace it with the real URL · raised by items., content.
unresolved-reference
Reference not found · error · Fix the URL or ID to the real target, or remove the reference · raised by content.
unknown-entity
Name not in source · error · Correct a misspelt name to the source's spelling; never swap in another name · raised by content., content., content., content., mask, heading., heading., heading., items., items., col, rows., content., headings., headings., content., content.
not-in-change-set
Not part of the recorded change · error · Change the named file, or say the work is not done; never swap in a changed path · raised by content., content.
ungrounded
Claim not in source · error · Copy the value exactly from the source · raised by content., content., content., content., content., content., content., content.
verbatim-drift
Text drifts from source · error · Restore the source's exact wording, or record why this text differs from it · raised by content.
quote-drift
Quote drifts from source · error · Quote the source exactly · raised by content.
Integrations
missing-issue-link
No linked issue · error · Link the issue this closes, if there is one · raised by issue.
unknown-issue
Issue not found · error · Fix a mistyped issue reference; never swap in another issue to pass · raised by issue.
issue-wrong-state
Issue in the wrong state · error · Finish the issue's work, or say it is not done; never claim a state it lacks · raised by issue.
missing-context
Issue data missing · error · Pass --context <file> with the linked issues' real states · raised by issue.
invalid-context-state
Invalid issue state in context · error · Set the issue's state in --context to open or closed · raised by issue.
source-unavailable
Source unavailable · error · Make the source available to the run, or mark its reference optional with ?
missing-context-value
Context value missing · error · Pass --context <file> with a values.<key> entry · raised by context., items., items.
context-value-missing
Context value not mentioned · error · State the value from --context in this section, if it is true here · raised by context.
uncovered-area
Changed area not mentioned · warning · Add an item for what changed there, if it is true · raised by items., items.
Contract errors
unknown-block-type
Unknown block type · error · Use a supported block kind: image, table, code or list
unknown-rule
Unknown rule · error · Use a rule name mediva ships (see SYNTAX.md or mdv explain <rule>)
reserved-rule
Reserved rule has no effect · error · Replace the reserved rule with an implemented one from mdv explain
allow-empty-without-required
allowEmpty has no effect · error · Add required beside it, or remove allowEmpty
empty-schema
Schema has no rules · error · Point mediva at the .mdv.md contract that holds the mdv: directives
invalid-extends
Invalid extends · error · Fix the extends= path (relative to this file), or break the cycle
invalid-regex
Invalid pattern · error · Write a valid JavaScript regular expression, e.g. \s for whitespace
regex-input-limit
Regex validation incomplete · error · Shorten the text the pattern reads; it is over 100000 characters
risky-pattern
Risky pattern · error · Rewrite the regex with bounded repetition and simpler alternatives
invalid-mask
Invalid mask · error · Use a documented mask token (see SYNTAX.md, Mask tokens)
heading-mask-includes-marker
Mask includes the heading marker · error · Remove the leading # from the mask; the template heading's own # sets the depth
selector-exemplar-mismatch
Selector matches none of its own exemplars · error · Fix heading.mask= to match the example heading, or fix the example
invalid-number
Invalid number · error · Use a whole number, e.g. content.words.min=20
invalid-option
Invalid option · error · Use one of the values the rule accepts
no-contract
No contract · warning · Add a contract beside the document to check its shape and state
undeclared-code
Rule reported an undeclared code · error · Add the code to the rule's declared diagnostics, in the gate it belongs to
rule-wrong-kind
Rule does not apply here · error · Move the rule to a field it applies to, or change the field's tag
directive-unterminated
Directive not closed on its line · error · Close the directive with --> on the same line
directive-unterminated-quote
Directive quote not closed · error · Close the quote before the next rule
fragment-shadowed
Fragment shadows another definition · warning · Rename the fragment if the overlap is accidental
fragment-unused
Fragment declared but never used · warning · Use the fragment as <name> in a mask, or delete it
unexpected-comma
Stray comma between rules · warning · Separate rules with spaces; use commas only inside [a, b] lists
unlevelable-override
Override names a code with no level · error · Remove the override: lint, contract and input codes have no level
unknown-override-target
Override targets nothing · error · Change warn=, error= or off= to name a rule or code this directive emits
inert-directive
Directive binds to nothing · error · Add the heading or construct the directive should wrap
unknown-requiredwhen-label
Required checkbox label not found · warning · Use the exact label of a checklist item or a choice option
unclosed-tag
Unclosed tag · error · Add the matching <!-- mdv: end<tag> --> where the region ends
must-wrap
Directive must wrap its section · error · Put the opener before the heading and the closer after the section
mismatched-tag
Mismatched closing tag · error · Close the most recently opened tag first
unexpected-closer
Closer without an open tag · warning · Add the matching opener above, or remove the closer
section-without-heading
Section without its heading · error · Put the heading on the next line, or close the section with endsection
ambiguous-closer
Ambiguous closer · warning · Add the outer section's own <!-- mdv: endsection -->, or move the content
invalid-rule-set
Invalid rule set · error · Write <!-- mdv: define prose <atoms…> --> with block atoms only
unknown-rule-set
Unknown rule set · error · Add its define, include the file that defines it, or fix the name
duplicate-rule-set
Duplicate rule set · error · Rename one definition, or delete the duplicate
rule-set-name-reserved
Reserved rule-set name · error · Choose another name, e.g. prose or long-prose
rule-set-conflict
Rule sets disagree · error · Write the value on the directive itself, or drop one of the sets
rule-set-cycle
Rule set uses itself · error · Remove one use in the chain
rule-set-unused
Unused rule set · warning · Use the rule set on a directive, or delete the define
include-not-found
Included contract not found · error · Fix the path, create the file, or move it into the project
include-cycle
Include cycle · error · Remove one include in the chain
include-anchor-missing
Include anchor matches no section · error · Match a section's heading slug, or drop the #anchor
include-anchor-ambiguous
Include anchor matches two sections · error · Rename one heading so the anchor picks one section
include-level-mismatch
Included section does not fit here · error · Move the include to where a section of its heading level fits
include-duplicate-section
Included section duplicates a sibling · error · Remove the duplicate, include a different section, or use extends
include-conflict
Included contracts disagree · error · Declare the empty state on this contract's document directive
repeat-selector-no-anchor
Selector has no anchor heading · error · Add the heading the selector's mask should match inside the section
repeat-selector-nested-level
Nested selector at or above its enclosing scope's level · error · Use a deeper heading level, e.g. ### under a ## section
repeat-selector-sibling-overlap
Two sibling selectors at the same level · error · Merge the two selectors, or move one to another heading level
repeat-selector-unsupported-rule
Rule unsupported inside an occurrence scope · error · Remove content.unlike= from the selector, or move it outside
block-before-anchor
Child section opened before its parent's anchor · error · Put the section's heading right after its opening directive
ambiguous-leaf-binding
Ambiguous same-family leaf layout · error · Make the earlier leaf required, or give each its own section
exactly-one-selector-member
exactlyOne on an occurrence selector · error · Move exactlyOne= to literal sibling sections
table-unknown-column
Constraint targets unknown column · warning · Match rows.<name> to the table's header text · raised by col
rows-header-mismatch
rows.in header binding failed · error · Add the missing header, or rename one so no two headers collide · raised by rows.
local-diagnostic-invalid
Invalid contract-local diagnostic · error · Fix the code=, message= or suggestion= atom as the message says
wrong-shape-option
Option written with the wrong shape · error · Drop the =value from a flag, or add the value an option expects
plugin-api-mismatch
Plugin API version mismatch · error · Upgrade the plugin or mediva so their plugin API versions match
plugin-conflict
Plugin conflict · error · Remove the duplicate, or set override: true if replacing is intended
plugin-invalid
Invalid plugin · error · Correct the definePlugin() rule or entry that the message names
invalid-exemplars-manifest
Invalid exemplars manifest · error · Fix the exemplars JSON: "version": 1 and a non-empty "values" array
flag-on-title-lead
Structure flag on the title's lead · warning · Move it to the document directive: <!-- mdv: document strict -->
unknown-vocabulary
Unknown vocabulary · error · Use a /regex/, or quote the text to match it literally
invalid-id
Invalid id · error · Write a kebab-case id that starts with a letter, e.g. id=summary
duplicate-id
Duplicate id · error · Give each block its own id, or include the file once
override-required
Override required · error · Add override to replace the base block, or rename this one
override-without-extends
Override without extends · error · Remove override, or add extends= to the document directive
implicit-override-key
Override matched by heading · warning · Target the base block by its id=
override-target-missing
Override target missing · error · Target a block the base defines, by its id= or its heading
override-target-ambiguous
Override target ambiguous · error · Add id= to the base block you mean, and target it by that id
duplicate-atom
Duplicate atom · error · Keep one value, or list both in one [...] where the atom takes a list