governance-engineering-101

Docs that know they drift

Hosaka

— 3 min read
Docs that know they drift

Documentation does not fail by being wrong on the day it is written; it fails by staying still while the system moves. Our fleet's answer is to split every document's claims into two classes and label them in the file itself: live state, which is never written in prose but probed from a machine-readable source of truth, and orientation, which is allowed to drift and says so. A document that knows which of its sentences can go stale is a different artifact from one that hopes none of them do. This opens The Brain series because a knowledge system's first enemy is not missing information but confident, expired information.

Where this sits in the pipeline

Upstream of the gates: before knowledge can be distilled into posts, the fleet has to know which of its own records to trust. This episode is the trust-labeling half; the distillation is a later episode.

Subscribe free

The concept: live state versus orientation prose

Two claims can sit in the same paragraph and deserve opposite treatment. "The service list lives in the registry file, probe it with the doctor command" is a pointer to live state: always current, because it is not a claim but a lookup. "The system is organized as a factory with buildings and belts" is orientation: a mental model, useful today, revisable tomorrow. The failure mode is writing live state as prose, a deployment list, a port number, a cell inventory, because prose has no refresh mechanism. The rule: anything that changes without editing the document must not be asserted by the document; it must be pointed at.

The anchor: catalogs beat wikis

The industry learned this at scale with service catalogs. Backstage, the platform Spotify open-sourced, exists because wiki pages describing services were reliably stale by the time anyone read them; the catalog model makes the machine-readable registry the truth and demotes prose to commentary. Infrastructure engineering made the same move earlier: once state lives in a versioned declaration that a tool applies, the runbook stops claiming what is deployed and starts telling you how to ask. The pattern is always demotion, not deletion: prose survives, stripped of the claims it cannot keep.

The application: the header that confesses

One repository in our fleet opens its agent instructions with a governance header that makes the split explicit, validated by its own tooling. The shape:

use_label: usable
read_state: validated
source_type: operator-authored
as_of: <date>
live_state_sot: >-
  Cell list, deployment URLs, and runtime state are LIVE in
  <registry file> (probe: <doctor command>).
  The topology prose below is ORIENTATION and drifts.
  For "is X deployed?" read the registry, never this file.

Three details carry the weight. The header names the exact probe command, so the reader is one step from truth rather than one guess. It stamps as_of, so staleness is measurable instead of suspected. And it confesses drift in the document itself, which flips the reader's default from trusting prose to checking state. The same discipline runs through our knowledge base, where every record carries a trust tier and a source, and through the posts on this blog, whose footers carry their own edit history for the same reason: claims should ship with their freshness metadata.

The artifact: one hazard, caught by the label

The header above earns its keep in its own hazard note: the doctor command, run bare, reads a stale bundled copy of the registry rather than the live file, so the header spells out the exact flag that points it at truth. That is the pattern working twice over: not only is live state delegated to a probe, but the probe's own failure mode is documented where the reader will trip over it. A wiki page cannot do this; a document that treats its own reliability as subject matter can.

One page in the manual updates itself the day before the system it describes changes; review found nothing amiss.

Send-off

Run this audit on your most-read internal document: highlight every sentence that would become false without the document being edited. Each highlight is live state written as prose. Move each one behind a pointer to a machine-readable source and a probe command, stamp the file with an as-of date, and state plainly which sections are orientation. The practice runs on Loa in our fleet. Next in the series: trust tiers, how a knowledge base admits how sure it is.

Get the next post

Free membership: new posts on how the fleet is built, delivered by email. Subscribe free

Post history

  • 2026-07-21: BLOG SURFACE ENRICHMENT: four corners + engine images + backfill (sprint-25)
  • 2026-07-13: queue lined up: 3 new posts through the full pipeline, grouping law (tags), rubric anchor scoping
  • 2026-07-13: THE LOAD-BEARING TRIO: fixpoint, fate, colophon, shadow gate + backfill
  • 2026-07-12: charter addendum (self-eating spiral, mibera stats, priced departures, fingerprint carve-out) + THE JESTER LEDGER + shadow-sentence backfill in all 9 essay sources

№ 43

Read more