Problem
Karpathy's pattern relies on [[wikilinks]] inside markdown prose to make cross-references machine-discoverable in stream — an LLM (or human) reading a paragraph hits a wikilink and can resolve it forward. Rivet's typed link graph is strictly more semantic, but it lives in the links: array, separate from the description: block. So when a rivet description says "This decision satisfies REQ-028", the typed link to REQ-028 might or might not exist in links:. Today: no warning either way.
Proposal
rivet validate learns to scan description and fields.* text for substrings matching the pattern [A-Z]+-[0-9]+, look each one up in the artifact corpus, and warn (not error) when the prose mentions an ID that has no corresponding typed link on the same artifact.
Severity: WARN (not ERROR). Authors sometimes name an ID in prose for clarity without intending a typed link (e.g. "this is similar to the approach in DD-001"). The warning gives them a discipline nudge; they decide.
rivet validate --strict could escalate the warning to an error for projects that want hard enforcement.
Why this matters
For LLM-driven authoring, the warning is the in-stream signal that lets an LLM author keep prose and links coherent without needing a separate reasoning pass. It is the discipline analogue of Karpathy's [[wikilinks]] for the typed-graph world. See the companion blog post.
Implementation sketch
- Extend
rivet-core/src/validate.rs with a new diagnostic kind MissingTypedLink { mentioned_id, artifact_id }.
- Pre-compile a regex
\b[A-Z][A-Z0-9]*-[0-9]+\b (cached statically). Apply to description + every value in fields that is a string.
- For each match: skip if it is the artifact's own id; check if
Store::get(mentioned_id) resolves; if yes and the artifact has no typed link to it, emit the warning.
- Tests: positive case (warning fires); negative case (typed link present, no warning); same-artifact-ID match suppressed.
Out of scope
- Auto-fix. The author may have meant the prose mention casually; auto-adding a typed link would be wrong without choosing a
link_type.
[[wikilink]] syntax inside prose. Stick with the bare PREFIX-NNN form; that's what authors already write.
Problem
Karpathy's pattern relies on
[[wikilinks]]inside markdown prose to make cross-references machine-discoverable in stream — an LLM (or human) reading a paragraph hits a wikilink and can resolve it forward. Rivet's typed link graph is strictly more semantic, but it lives in thelinks:array, separate from thedescription:block. So when a rivet description says "This decision satisfies REQ-028", the typed link to REQ-028 might or might not exist inlinks:. Today: no warning either way.Proposal
rivet validatelearns to scandescriptionandfields.*text for substrings matching the pattern[A-Z]+-[0-9]+, look each one up in the artifact corpus, and warn (not error) when the prose mentions an ID that has no corresponding typed link on the same artifact.Severity: WARN (not ERROR). Authors sometimes name an ID in prose for clarity without intending a typed link (e.g. "this is similar to the approach in DD-001"). The warning gives them a discipline nudge; they decide.
rivet validate --strictcould escalate the warning to an error for projects that want hard enforcement.Why this matters
For LLM-driven authoring, the warning is the in-stream signal that lets an LLM author keep prose and links coherent without needing a separate reasoning pass. It is the discipline analogue of Karpathy's
[[wikilinks]]for the typed-graph world. See the companion blog post.Implementation sketch
rivet-core/src/validate.rswith a new diagnostic kindMissingTypedLink { mentioned_id, artifact_id }.\b[A-Z][A-Z0-9]*-[0-9]+\b(cached statically). Apply todescription+ every value infieldsthat is a string.Store::get(mentioned_id)resolves; if yes and the artifact has no typed link to it, emit the warning.Out of scope
link_type.[[wikilink]]syntax inside prose. Stick with the barePREFIX-NNNform; that's what authors already write.