Inside Aestheria

How we keep our own docs from drifting.

We sell context that agents read as fact. So a stale number in our docs is not a typo, it is a defect. Here is what we run against ourselves.

How it works

Every change that introduces a principle, a token, a pattern, or a rule updates three artifacts in the same commit: DESIGN.md for the principle, CLAUDE.md for the routing rule, and the relevant SKILL.md for the agent that owns it. If nothing needs updating, the delivery says so out loud.

The rule works because it is enforced at the moment of the change, not at review time. Documentation written a week later is written from memory, and memory is where drift starts.

The check that runs anyway

A rule people follow ninety percent of the time still drifts. So npm run check-drift reads the docs and the code and compares them: token values quoted in prose against the values in index.css, counted variants against the actual index, file paths against the tree, the agent roster against the folder.

It fails on stale numbers, renamed tokens, and broken paths. The counts on our own overview are derived from each pillar's canonical index rather than typed by hand, which removes the most common drift entirely: a number that was true when someone wrote it.

The deterministic pass

Spacing is the other place drift hides, because a padding value that lands on the scale by coincidence looks correct in review. npm run check-spacing flags surface padding and radius that match the scale but use a pixel literal, so the surface family stays tunable from one place.

Controls and hairlines are out of scope on purpose. A check that fires on everything gets muted, and a muted check is worse than no check.

What this does not replace

• Judgment. A check confirms a number matches; it cannot tell you the number was a bad idea.
• Review. The six agents still read the surface for hierarchy, states, and accessibility.
• Writing. Nothing here generates a sentence, and nothing should.