reference.dunn.dev

dunn.dev

Reference

Reference is the dunn.dev estate's rules, run as code. Each standard is prose plus a check.sh that CI runs against every project. The design tokens and page chrome are a package every project site imports.

People read these pages; agents read the same pages as markdown.

just check

---- design-system ----
PASS design-system/grep:package.json: /"@dunn\.dev/reference"/ found in 2 file(s) matching package.json
SUMMARY design-system: 2 passed, 0 failed
---- package-publishing ----
FAIL package-publishing/file-contains:.gitlab-ci.yml: .gitlab-ci.yml does not match /^[^#]*gitlab\.com/dunn\.dev/pipeline/slsa-attest@[0-9]+(\.[0-9]+){0,2}([^0-9A-Za-z.-]|$)/
SUMMARY package-publishing: 1 passed, 1 failed
---- repository ----
PASS repository/file-exists:hero.svg: hero.svg exists
PASS repository/file-contains:README.md: README.md matches /^!\[hero\]\(hero\.svg\)/
SUMMARY repository: 8 passed, 0 failed, 1 unreadable (probe could not run — not a policy verdict)

TOTAL: 5 contract(s) passed, 3 failed
WHY · ONE SET OF RULES, READ BY PEOPLE AND AGENTS, ENFORCED IN EVERY PROJECT'S CI ACTORS OUTSIDE REFERENCE · THE ESTATE'S RULES AS CODE 1 2 3 3 4 5 6 write render read read runs checks gates merge import chrome standards, chrome into pages as HTML as markdown every check.sh a FAIL blocks it tokens, site.css maintainers agents site contracts design package project CI project repos project sites people coding harnesses HTML for people markdown for agents routes task to page one per standard tokens, site.css, chrome on every MR declared gaps read WAIVED own words, shared frame /llms.txt CONTRACT.md · check.sh @dunn.dev/reference reference-check WHY · ONE SET OF RULES, READ BY PEOPLE AND AGENTS, ENFORCED IN EVERY PROJECT'S CI ACTORS OUTSIDE REFERENCE 1 2 3 3 4 5 6 write render read read runs checks gates merge import chrome standards, chrome into pages as HTML as markdown every check.sh a FAIL blocks it tokens, site.css maintainers agents site contracts design package project CI project sites project repos people coding harnesses HTML for people · markdown for agents /llms.txt routes task to page one per standard tokens, site.css, chrome on every MR own words, shared frame declared gaps read WAIVED CONTRACT.md · check.sh @dunn.dev/reference reference-check

Maintainers write the rules once. People and agents read the same pages, every project's CI enforces them, and project sites import the chrome.

How it works

01 · write

A standard is a directory

CONTRACT.md states what must hold, check.sh asserts it with a closed set of primitives, and templates let a project satisfy it without writing from scratch.

02 · check

CI gates the merge

The reference-check component runs every check.sh in a project's pipeline. A FAIL blocks the merge; a gap the project declares in its register reads WAIVED.

03 · import

The chrome is a package

Tokens, site.css and the Astro page chrome ship as @dunn.dev/reference. A project site imports them instead of keeping its own copy.

For agentsmarkdown alongside the HTML

Every page on this site is also served as Markdown an agent can fetch directly, one leaf at a time. /llms.txt is the routing spine, task to page.

Conformance runs two ways: locally via just -f ~/gitlab.com/dunn.dev/reference/justfile check, and in CI via the reference-check catalog component. 

/<path>/index.md                       markdown body
/standards/<name>/check.sh             executable assertions
/standards/<name>/templates/<file>     liftable templates
/llms.txt                              task to page

Where next

Standards

What every project in the estate must look like: prose, executable assertions and liftable templates, one directory each.

Design

The design language every site shares: tokens, type, mark, diagrams and the page chrome.

Principles

Why the standards take the shapes they do: four agent-correctness primitives and the operational discipline behind the CI catalog.

Deviations

How a project declares a standard it cannot satisfy, with its reason, and retires the entry once the reason changes.