Adoption Guide
Adopt Truth Machine as a sequence of paid-for boundaries, not an installer.
1. Establish fit
Section titled “1. Establish fit”Identify concrete evidence that:
- durable claims from multiple sources matter;
- source authority differs or conflicts;
- changing the current account has consequences;
- current values require ancestry or correction history; and
- a coherent partial application could make the account false.
If those conditions are absent, stop. An ordinary record or deterministic application is simpler.
2. Inspect before changing
Section titled “2. Inspect before changing”Read the product’s current instructions, architecture, status, decisions, operations, schemas, and verification paths. Inventory:
- what currently counts as truth;
- every path that can modify it;
- evidence sources and original preservation;
- source and actor authority;
- the likely coherence boundary;
- current review and concurrency behavior;
- publications and outside contributions;
- degradation and recovery; and
- contradictions between documents and implementation.
Mark unknowns explicitly. Do not call the existing product a truth machine because its vocabulary sounds compatible.
3. Choose the first paid seam
Section titled “3. Choose the first paid seam”Begin where the product already experiences a cost. Examples:
- source files are overwritten during extraction;
- an import silently changes current data;
- a reviewer cannot see the exact delta;
- stale work overwrites a newer decision;
- current values cannot name their evidence;
- live status collapses unreachable into stopped;
- generated and sent artifacts are confused; or
- an AI Peer reconstructs product meaning on every session.
Implement one reversible boundary and verify it. Do not scaffold every record type because the reference repository has one.
4. Define the system contract
Section titled “4. Define the system contract”Record:
- coherence boundary;
- evidence types and retention;
- source authority scopes;
- current truth representation;
- proposed-change identity;
- reviewer and actor capabilities;
- expected-state and atomicity mechanism;
- ancestry grain;
- governed read contract;
- publication policy when applicable; and
- degraded behavior.
5. Make a bounded conformance report
Section titled “5. Make a bounded conformance report”Assess every applicable TM-* requirement against concrete mechanisms. A gap
is useful information. Do not weaken the requirement or hide a path to obtain
the label.
6. Add profiles only when useful
Section titled “6. Add profiles only when useful”Use the Git-native profile when a commit is the right atomic boundary. Use the AI-Peer profile when a durable office materially improves operation. Use the Facets pattern only after a recurring outside encounter earns a focused projection.
7. Return implementation evidence
Section titled “7. Return implementation evidence”When a mechanism survives real work, record:
- the tension and consequence that required it;
- the exact implementation revision inspected;
- what is mechanically enforced;
- what remains policy or unknown; and
- whether another domain reproduced or contradicted the lesson.
Portable architecture should follow implementation evidence, not precede it.