The Docs Were Lying: How We Keep an AI System Honest About Itself

We build AI systems that are made to prove their work. But there is a second kind of trust most teams never build — trust that the system still is what its documentation says it is. Because the documentation drifts. What is in the repository, what is actually running, the working notes, and the official docs are four pictures of the same system, and they wander apart the moment nobody is watching. So we pointed the same discipline inward, and made the system honest about itself.

One source of truth, and contracts inside it

We promoted one representation to authoritative: the knowledge base. It states what the system is supposed to be, and everything else is measured against it. Each worker has a knowledge-base article — and inside that article sits a machine-readable contract that states, in plain data, what the worker must be: its address, its schedule, its permissions, its shape. The contract lives in the same file as the explanation, so the prose and the specification cannot drift from each other. The document stopped being a description and became a constraint the worker has to satisfy.

Workers that watch for drift

Then we built the boring, load-bearing part: workers whose only job is to notice drift. A reconciler reads what is actually live, what the contracts say should be live, and what the operator-facing overview claims — and flags every disagreement: a live worker with no contract, a contract with nothing behind it, a live worker missing from the overview. It is read-only on purpose. A silent auto-correction just papers over a real problem and trains you to trust a green light you never earned. It surfaces the gap and hands the decision to a person.

Fifteen minutes, a text, and a backlog

A separate monitor runs every fifteen minutes and checks a real freshness signal for each critical job — not "did the schedule fire" but "did the output actually show up." When something goes stale, or the daily reconcile finds drift, it does two things: it hits a small notify endpoint — one API call — that sends a text message, rate-limited, and it writes the finding into the task backlog so it cannot be thumbed away. Drift and ordinary work land in the same governed list — what broke and what is left to build, in the open, each with an owner.

Why it matters

Detection without a backlog is noise, and documentation nobody checks is a wish. Governance, done honestly, is just this loop running on a timer: the knowledge base states what should be true, the contracts make it checkable, the reconciler checks it, the monitor watches the clock, and the gap gets a text message and an owner. That is the standard we hold our own house to — the same one we build into everything else.

The full engineering write-up lives on jessemyers.ai.