# Truth Machine Kit

> Copyable, ownable patterns and templates for standing up a Truth Machine without reading five repositories.

The Kit is the layer between the normative specification and the
implementation evidence: the reusable pieces named as pieces, each with its
cost, prerequisites, and a copyable starting file where one helps.

It is a catalog, not a framework. A repository adopts a pattern by copying
and owning it; nothing here is imported, versioned against, or depended on
after adoption. Every page states its **normative weight** explicitly:
either it implements identified `TM-*` requirements, or it is ergonomics —
conventions that make the requirements cheap to live with. Roughly half the
catalog is ergonomics, and a project can skip those without guilt.

## Composition rules

Tiers group the patterns by what they cost and what must already exist.
They are à la carte with stated prerequisites, not a strict ladder — running
Tier 1 without Tier 2 is a valid configuration, and one evidenced
implementation does exactly that.

**Git already governs source code.** Tier 3 packet machinery exists for
truth Git does not already version and review — deployments, organizational
facts, financial records, outside coordination. In an ordinary software
repository, evidence and change packets duplicate what commits and PR review
already do. What Git does *not* govern there is what is actually deployed,
what was decided and why, and whether a document is still current — Tiers
0–2.

## The tiers

| # | Pattern | Tier | Normative weight |
| --- | --- | --- | --- |
| 1 | [Front Door](/docs/truth-machine/kit/front-door/) | 0 | ergonomics, supports `TM-DEC-006` |
| 2 | [Status Lines](/docs/truth-machine/kit/status-lines/) | 0 | ergonomics |
| 3 | [Status Document](/docs/truth-machine/kit/status-document/) | 0 | ergonomics |
| 4 | [Authority Boundary](/docs/truth-machine/kit/authority-boundary/) | 0 | implements `TM-MOD-005`, supports `TM-CUR-008`, `TM-CUR-009` |
| 5 | [Evidence Hygiene](/docs/truth-machine/kit/evidence-hygiene/) | 0 | implements `TM-EVD-008` |
| 6 | [Frozen Archive](/docs/truth-machine/kit/frozen-archive/) | 0 | supports `TM-CUR-006` |
| 7 | [Decision Records](/docs/truth-machine/kit/decision-records/) | 0 | ergonomics |
| 8 | [Typed Current Projection](/docs/truth-machine/kit/current-projection/) | 1 | implements `TM-CUR-001`, supports `TM-MOD-004` |
| 9 | [Human Index](/docs/truth-machine/kit/human-index/) | 1 | supports `TM-OBS-004` |
| 10 | [Governed Read](/docs/truth-machine/kit/governed-read/) | 1 | implements `TM-OBS-001`–`TM-OBS-003` |
| 11 | [Sealed Baseline](/docs/truth-machine/kit/sealed-baseline/) | 1 | supports `TM-CUR-006`, `TM-CUR-009` |
| 12 | [Declared Versus Observed](/docs/truth-machine/kit/declared-versus-observed/) | 2 | implements `TM-OBS-005`–`TM-OBS-009` |
| 13 | [Untrusted Intake](/docs/truth-machine/kit/untrusted-intake/) | 3 | implements `TM-EVD-001`, supports `TM-PUB-006` |
| 14 | [Evidence Packet](/docs/truth-machine/kit/evidence-packet/) | 3 | implements `TM-EVD-002`, `TM-EVD-003`, `TM-EVD-007` |
| 15 | [Change Packet](/docs/truth-machine/kit/change-packet/) | 3 | implements `TM-REC-004`–`TM-REC-008`, `TM-CHG-009` |
| 16 | [Atomic Transition](/docs/truth-machine/kit/atomic-transition/) | 3 | implements `TM-CHG-003`–`TM-CHG-008` |
| 17 | [Exact Review](/docs/truth-machine/kit/exact-review/) | 3 | implements `TM-CHG-001` |
| 18 | [Publication Freeze](/docs/truth-machine/kit/publication-freeze/) | 4 | implements `TM-PUB-001`–`TM-PUB-004` |
| 19 | [Generated Artifacts](/docs/truth-machine/kit/generated-artifacts/) | 4 | supports `TM-PUB-002`, `TM-OBS-003` |

At the Tier 4 boundary, [Facets](/docs/truth-machine/patterns/facets/) is
the established pattern for projections that meet a person outside the
operating boundary; it predates the Kit and keeps its own page.

## Reading a pattern page

Every page uses the same shape. **Normative weight** is the load-bearing
field: it reads either `ergonomics` or `implements` followed by identified
requirements, meaning the pattern is one concrete way to implement them —
the verb is *implements*, never *satisfies*,
because a catalog page cannot grant conformance to anyone
(`TM-CON-003` reserves `satisfied` for evidence-backed dispositions inside
an assessment). **Evidence** comes in two classes: *assessed* links an
exact-revision [implementation report](/docs/truth-machine/implementations/);
*observed* names a repository the maintainer operates without a pin and
carries no conformance claim.

## Declaring adoption

A repository can record which patterns it adopted in a machine-readable
declaration:
[`truth-machine.toml`](/docs/truth-machine/templates/declaration/truth-machine.toml),
validated by
[`declaration.schema.json`](/docs/truth-machine/schemas/declaration.schema.json).
Declining a pattern requires a stated reason — deliberate omission stays
cheap; silent omission becomes impossible.

The companion
[`check_adoption.py`](/docs/truth-machine/templates/declaration/check_adoption.py)
verifies the declaration against the working tree: every adopted pattern
names paths that exist, every declined pattern states its reason. A finished
migration or bootstrap is then an exit code, not a judgment; its `--json`
output shares the governed read's
[`read-result.schema.json`](/docs/truth-machine/schemas/read-result.schema.json)
contract.

## Alignment with open conventions

The Front Door pattern aligns with
[`AGENTS.md`](https://agents.md/), the open agent-guidance format launched
in August 2025 and donated to the Linux Foundation's Agentic AI Foundation
in December 2025. The Kit extends that industry convention; it does not
invent a rival one.