Connect

Check rules

Each rule, what it catches, and how to fix it.

vinc graph-md check runs these nine rules. BLOCK means the file is broken and should be fixed before assistants read it; FIX means it still works but should be cleaned up. The messages are shown as the CLI prints them.

header-marker · BLOCK

None of the first four lines is the header line <!-- vinc-graph-md: N ... -->. Vinc uses it to tell a GRAPH.md from any other Markdown file.

first lines have no `<!-- vinc-graph-md: N ... -->` marker

Fix: Put <!-- vinc-graph-md: 1 --> right under the title. A rebuild fills in the date.

section-order · BLOCK

A required section is missing, or the known sections are out of order. Sections are recognised by their heading name in the file's language, so a renamed heading counts as missing. If fewer than two known headings are found at all, the result is a FIX instead: the file is probably in another language.

missing section: Node kinds
sections are out of order relative to the spec

Fix: Restore the heading name and move the section back to its place. The order is on Specification.

generated-block · BLOCK

The generated region needs exactly one start line and one end line, start first. Without that, Vinc cannot tell which part to replace, and a rebuild refuses to run.

generated markers are missing, duplicated, or out of order

Fix: Put back the two lines <!-- vinc:generated start --> and <!-- vinc:generated end --> around the Domains and Ratified vocabulary sections, then rebuild.

generated-drift · BLOCK

The generated region no longer matches the graph: a domain was added, or a person approved new vocabulary since the last rebuild. Runs only when the check can read the graph. Assistants are not affected, since vinc_conventions fills that region freshly when it reads; the stale copy is the stored one or your file.

Fix: Rebuild: Rebuild in the app, or vinc graph-md build --file GRAPH.md. Your prose is kept.

unknown-edge · BLOCK

In the Relations section, a list item of the form - name: ... names a relation that is neither one of the six built-in names nor approved in this graph. An assistant would copy that name into the graph.

## Relations [schema-fixed]
- relates_to: loose association. Undirected.
- replaces: A replaces B.

relation not in the wire contract or ratified vocabulary: replaces

Fix: Use one of relates_to, prerequisite_of, derives_from, inherits_from, connects_via, about. If the graph really needs the new relation, approve it first (in the app's GRAPH.md settings, local mode), then list it.

unknown-domain · FIX

The generated region lists a domain that the graph no longer has, usually after nodes were moved or deleted. Runs only when the check can read the graph.

domain not present in the store: vinc/web

Fix: Rebuild. Do not edit the region by hand; the next rebuild would overwrite it anyway.

stale-tool · FIX

The text names a vinc_ tool that does not exist, often one that was renamed. An assistant that follows the text would call a tool that is not there.

unknown tool name: vinc_find

Fix: Use the current name from the tool list.

length · FIX / BLOCK

The file is longer than 75 lines (FIX) or 100 lines (BLOCK). Blank lines count, because they take the reader's time too; blank lines at the very end do not.

76 lines (budget 75)
104 lines (hard limit 100)

Fix: Take a line out for each one you add. Writing it well has ideas.

forbidden-glyph · FIX

A line contains an em-dash. GRAPH.md text is shown in the app and on this site, where em-dashes are not used.

em-dash is not allowed in on-screen text (D38)

Fix: Use a colon, brackets or a new sentence. The finding gives the line number.

What no rule checks

Whether your examples are good, or your rules suit this graph. The check looks at shape only; meaning is for you and the assistant. See Writing it well.