What software must do, and how to make it do it. Documents, SSOT, hierarchy, progress, handover, and four levels of enforcement.
§ 00 · What You Cannot Change, and What You Can Build
First, a frame. A definition in current use is Agent = Model + Harness. You cannot change the model; headquarters decides and supplies it. What you can change is the harness: the documents, rules, permissions, and surveillance surrounding the model.
Making AI work properly therefore means building a harness, not waiting for a better model. Software is the suspect. Let us separate the work it must do from the devices that make it do that work.
§ 01 · The Discipline Software Must Follow
The minimum discipline to impose on a machine. These are not requests; they are built into the harness.
No speculation: do not report database, API, build, or file state from fantasies. If not checked, say “not checked.” Label anything unmeasured as an estimate.
Write confessions. When a mistake emerges, the machine records it: what was wrong, how it was exposed, the root cause, and the rule preventing recurrence. Then it rereads the confession before working.
Without evidence, there is no completion. Originals, not summaries. A verdict and exit code, not “passed.” No completion before cross-verification passes. Ban evasive language: “probably fine,” “unconfirmed,” and “cannot determine” all ultimately mean “didn’t look.”
Human goodwill does not enforce this discipline. The documents and devices in the next section do.
§ 02 · How to Give Orders = Documents, the Body of the Harness
What moves a machine is not shouting in a chat window but the documents built around it. Why each document is needed is the core of this method. The following seven form the framework shared without exception by projects that run well.
① The canonical source (SSOT): one truth, present in one place only and referenced everywhere else. Put the same fact in two places and they will eventually diverge; the machine chooses the convenient one. So record commands for counting, not fixed counts and figures, in documents.
② A pyramid hierarchy: changes travel only downward. Planning (Why) → rules → specifications → code → history. Propagation is one-way. If code conflicts with the plan, fix the code. The plan is the answer.
③ Progress: what is true now. The machine guesses current state. Fix the project’s present progress in one document so it need not guess.
④ Handover: sessions lose memory. Each is a new part-timer. The next session must first read what the previous one did and which decisions were locked. This is a stack of confessions that makes it face failures again the next morning.
⑤ Locked decisions (ADR): prevent relitigation. Without a lock, the next session overturns and debates a decision again. Gather decisions in one place and lock them against reopening.
⑥ Synchronization rules: copies drift. When repositories share a document, compare their actual bytes. Use a diff, not a claim that they are identical.
⑦ Branch rules: humans hold what is hard to reverse. feature → develop → main, one way. Only humans deploy to main. No bypassing checks. One line runs through all seven: architectural principles matter because they prevent Context Rot, not for elegance. Keep it short, one thing in one place.
§ 03 · Surveillance Devices—Enforcement Has Levels
Documents state rules; devices enforce them. But declaration differs from enforcement. Writing that a sensor must run and having it actually run are entirely different matters. Understand enforcement in four levels, weakest to strongest.
The more important the rule, the further down it must move, to C or D. Leave it only in prose at A and the machine plausibly ignores it. Agents, skills, sensors, and hooks occupy the rungs. What counts as evidence? The verdict line, exit code, and raw stdout. Leave only a summary and a false PASS can hide.
A · Prose instructions (document rules) · Weakest—works only if the machine reads the document
B · An agent with restricted tools · Remove Edit/Write permissions from the verifier → structurally separates implementer and verifier, rather than merely instructing them
C · Deterministic sensors (scripts) · Run actual tsc checks, tests, and builds; PASS/FAIL by exit code—zero model judgment
D · Pre-action hooks (PreToolUse) · Block dangerous commands before execution—the only level that works even when the model’s reasoning fails
§ 04 · A Live Example—Why ADRs Are Always Forgotten
ADRs, architecture decision records, show why this ladder matters. Everyone knows to record architectural decisions. Yet when work is assigned through chat, code and documents change while the ADR is repeatedly omitted. Why?
Because an ADR has no failure signal. Omit code and compilation breaks; omit tests and a red light appears. Omit an ADR and nothing breaks. It hangs only on the prose instruction “Record it,” level A, and when busy, the machine plausibly skips it. The importance of the rule and its enforcement level do not match.
The repair is to move down the ladder: create a failure signal artificially. For a commit touching traces of a decision—dependencies, schemas, settings, architectural documents—block it unless the decision-record folder has an entry for the same date. That is level D. The change cannot get in without recording the decision, just as one cannot push without tests.
Rereading confessions has the same disease. Writing is enforced by a hook at D, but rereading before work is left to memory at A. When busy, it does not read. The fix is the same: make the confession come to you. One lesson: important rules must mean “you cannot pass,” not “remember.”
§ 05 · A Self-Harness Is Not Sufficient
So far, this is software’s own harness: issue orders through documents, enforce through four levels, confirm with evidence. Powerful by itself, but it cannot end here. The theory installment warned that surveillance built by its subject becomes theater. The machine also builds and maintains this harness itself. At some point, sensors stop running, gates become empty files, and the red team planted last is ignored.
Above it, an outside eye must check whether the harness actually bites. The conditions are demanding: outside the project; not reading the builder’s narrative, judging only by external contracts and universal rules; attacking from unexpected directions with different models, inputs nobody designed, and probes of the actual deployment; and standing at the deployment gate. Catch problems before release, and order rollback if already released.
This is not software’s self-harness but a second interrogator inspecting it. Even the first interrogator, the working Claude, is not trusted. The method therefore divides into two packages: one installed inside the project to interrogate during construction, and one outside guarding deployment.
CODA · Code Both Humans and Machines Can Read
An old saying about good code says anyone can write code computers understand; good programmers write code humans understand. In an age of building with machines, we can rewrite it: good users write code and documents that both AI and humans can understand.
Documents are not for people. They are for interrogating machines. Well-written documents can also be read by people.
Read this note at sass.studio.