Citing a fact, and proving it
Grounding is a two-step loop: a decision cites a fact, and validation resolves the citation. The grammar is deliberately small, the resolver is deliberately dumb — it trusts only the registry — and three gates turn the result into a badge you can see. Try it live in the corpus explorer.
The citation grammar
A citation is one token: a KB-NNNN id and the @edition it was read against.
The id is opaque — it means nothing until the registry gives it a document. The edition is any non-empty run after the @ (in practice, a date). The parser is exactly:
The @edition is optional in the grammar but expected in practice. A bare KB-0001 parses fine — it just isn't pinned, and the form gate warns: “cite it as KB-NNNN@edition so a later re-ingest can't silently change what this decision grounded against.” Pinning is what makes a citation point-in-time.
The resolver
Resolution is registry-authoritative: the resolver looks the id up in knowledge/index.md and nowhere else. It never trusts the citing document, and it never guesses.
From an opaque id it renders a human label — marketplace · plugin · slug — straight from the matched registry row, so a reader sees what was cited without the author writing it out:
Then it resolves the edition to one of three outcomes: the pin matches the registry's current edition (current); the pin matches a retained edition under superseded/ (superseded — still resolves); or nothing on disk matches (null — a dead reference). Those three outcomes are exactly the grounding states.
Grounding states
A <spec-decision> renders its grounding as a badge — the same treatment you can flip live in the kung-fu example. The grounding states, keyed off the resolver:
Cites a resolvable id pinned to the current edition. The claim points at committed text a reviewer can open.
all gates passResolves — but to a superseded edition. The fact moved on; re-ground, or keep the pin deliberately if the historical claim is intended.
corpus-staleness · warningNo corpus token at all. The fact rests on the model's memory. Advisory: grounding is a nudge here, never a hard gate — not every claim is a domain fact.
ungrounded domain claim · nudgeCites something that doesn't resolve — a typo'd id, a fabricated edition, a dead link. A hard error: it cannot pass validation.
corpus-provenance · errorThe distinction between the two amber states matters: assumed means no citation (a nudge — the corpus is optional, and product decisions shouldn't manufacture one), while stale means a citation that resolves to yesterday's edition. Only ungrounded — a citation that resolves to nothing — is an error.
The gates
spectastic validate runs the citations in every spec against the corpus. Three rules turn resolution into findings:
| Rule | Severity | Fires when |
|---|---|---|
corpus-provenance |
error | A cited KB-NNNN@edition resolves to no committed document — including a fabricated or typo'd pin. A dead reference blocks. |
corpus-staleness |
warning | A decision's pinned edition is not the current edition — it resolves to a retained superseded/ copy. Re-ground, or accept it deliberately. |
corpus-citation-form |
warning | A citation inside a <spec-decision> is bare (KB-NNNN with no @edition) or malformed. Grammar-only — needs no corpus to run. |
A fourth rule, corpus-license (warning), scans reference frontmatter for a non-permissive license — covered in Anatomy. Note the asymmetry: only corpus-provenance is an error. A dead citation is a broken contract; a stale or unpinned one is a flag you can act on without being blocked.
Grounding a domain claim is a nudge, never a gate — the corpus is optional, and, as the scope discipline puts it, a corpus asked to justify everything justifies nothing. What is enforced is integrity: if you cite, the citation must resolve.
Why a citation can't be faked
This is the property that makes the whole scheme worth the ceremony. A language model can hallucinate a fact. It cannot hallucinate a citation that resolves.
A fabricated KB-0009@2024-05-28 has no row in a registry the model didn't write, so it resolves to nothing, so corpus-provenance fires an error. The failure mode flips from “confidently wrong and unattributed” — the worst kind, because nothing marks it — to “unresolvable, and it says so.” Grounding doesn't make the model right; it makes ungroundedness visible.
The honest ceiling. Resolution proves a citation points at committed text — not that the text is true. That's the author's job at curation time: a reference is only as good as the source named in its origin. What the gate guarantees is narrower and still valuable — that a claim marked grounded is backed by something a human chose to commit, at a known edition, that anyone can open and check.
The fence
A corpus is third-party text a model reads. That makes it an injection surface — so spectastic treats corpus content as data, not instructions, the same principle it applies to every artifact it ingests.
Two defenses do the work. First, progressive disclosure: what enters a prompt is the compact registry index — ids, slugs, titles, editions — never the document bodies. A model sees the menu and pulls a specific document only when the work calls for it (051 FR-008; "the codebase is the index"). Second, the fence: whatever corpus text is shown is routed through the exact same sanitiser every other ingestion path uses, wrapped and labelled as data. The harness-owned grounding directive sits outside the fence, as an instruction; the corpus sits inside it, as something to read:
So a reference that tries to smuggle in “ignore your instructions” lands inside the fence, as data — read, not obeyed — and the model still had to reach for it through a citation that resolves.