Truth Machine / Kit

Governed Read

A copied, owned, offline reader script that compares the declared current projection with the working tree and exits match, mismatch, or unknown.

Read as Markdown

Tier: 1 · Normative weight: implements TM-OBS-001, TM-OBS-002, TM-OBS-003 Requires: Typed Current Projection

Problem it removes

The current projection and the human index are only as trustworthy as the last person who remembered to update both. Without a check, agreement is a habit; with one, disagreement is an exit code.

Mechanism

A single stdlib-only script — copy it, own it, never import it — that loads current.toml, verifies declared artifact digests against the working tree, and asserts the human index names every declared record. Every check carries an id, a source (where the observation came from), and a meaning (what a failure signifies), which is what makes the read’s provenance inspectable (TM-OBS-002). Output is deterministic (TM-OBS-001), available as prose or --json, and the script mutates nothing and repairs nothing (TM-OBS-003) — a detected mismatch routes back through ordinary review.

Exit codes are the contract: 0 match, 1 mismatch, 2 unknown. A check that could not run — unreadable file, failed subprocess — is unknown, never a pass. The read’s material uncertainty is part of its answer: unknown checks degrade the aggregate, so a partially observable tree never reads as fully verified. That rule reaches the declaration itself: a malformed projection entry becomes an unknown check naming the entry, never a silent skip. The --json form is published as read-result.schema.json.

The template is a genuinely minimal skeleton, generalized from four production readers. Real repositories grow it: live service checks, packet grammar validation, cross-repository ownership seams. Grow yours in place; that is what owning the copy means.

Cost

Authoring: an afternoon to adapt the template to what the projection declares. Per change: extend a check when the projection grows a new entry type. Per session: seconds — it becomes the first command of any operating session.

Do not adopt when

There is no typed projection to read, or the repository’s checks already live in an adequate test suite. Adopt the projection first; the reader is meaningless without it.

Evidence

Assessed in inference-ops, cloud-ops, and kinra-corpus — four independent readers, including this repository’s own, share the shape the template distills. The flow read path applies the same contract inside an application.

Template

templates/governed-read/state_reader.py

Declared Versus Observed extends the reader beyond the repository boundary to live systems.