Let the Agent Prove It's Done
An agent's most dangerous output isn't bad code. It's the word "done."
Bad code that fails a test is a non-event — you see it, you fix it, nobody ships it. Bad code that arrives wrapped in a confident "I've implemented the change and verified it works" is the thing that actually hurts you, because the agent that wrote it is also the agent grading it, and it grades generously. It wrote the code believing the code was correct. Asking it to check its own work is asking it to re-confirm the belief it started with. Of course it passes.
This is the last piece in a series on building repositories agents can maintain, and it's about the half of the problem the first three pieces were quietly setting up. Structure tells the agent where to work. Contracts bound what it can break. Gates replace prose rules with walls. All of that is in service of one final thing: making "done" a verdict the agent has to earn from the repository instead of a sentence it gets to write about itself.
There are four moves, and they stack.
Give It Something It Can Actually Prove
Start with the code itself, because some code is provable and some isn't, and the difference decides how much an agent can verify on its own.
A pure function — one that takes inputs and returns outputs with no filesystem, no network, no database, no clock, no randomness, no environment — can be checked completely, instantly, with nothing but a unit test. The agent can write the test, run it, watch it pass or fail, and know, in its own loop, without provisioning anything. That's the deterministic repair target: the place where an agent can iterate to correctness unsupervised, because the oracle is right there and costs nothing to consult.
Now take the same business rule and smear it across a React component that also fetches data and reads localStorage, or a controller that also opens a transaction and calls Stripe. To verify it, the agent needs a browser, a database, credentials, a network. It usually can't get all of that inside its loop, so it does the thing it can do — it reads the diff, decides it looks right, and declares done. The logic was never wrong; the architecture made it unverifiable, and unverifiable is where false completion lives.
This is the real reason the layering matters — pure core, orchestrating application, interface ports, side-effecting adapters, isolated generated. It's not aesthetics. Every rule you pull down into the pure core is a rule the agent can prove on its own. Every rule trapped in a side-effecting layer is a rule it can only assert. The hexagonal shape is, more than anything, a machine for maximizing the fraction of your system that an agent can actually verify without provisioning the world. Keep the truth pure, push the IO to the edges, and you've handed the agent the largest possible surface it can be trusted on.
Collapse Verification Into One Command
The second move is to make "is this done?" answerable in exactly one way.
If checking a change means knowing that this kind of edit needs the unit suite, but that kind needs the contract tests, and the visual regression only matters when CSS changed, and there's a separate lint config for the architecture rules — then verification is itself tribal knowledge, and we already know what happens to tribal knowledge in front of an agent. It gets skipped, half-run, or guessed at.
So you collapse it: one command, make verify or pnpm verify, that runs the whole gate set — types, lint, unit, contracts, integration, architecture checks, giant-file checks, security checks — and returns a single pass or fail. CI runs the identical command. Now "done" has a precise, boring definition: the command exits zero, or you document the exact blocker with the exact output. No judgment, no vibe, no "looks good to me." The agent doesn't get to define done, and neither do you. The command does.
The discipline that makes this hold is small but absolute: done is the exit code, not the feeling. An agent that says "I've verified the change" without pasting the output of the command that verified it has verified nothing. The claim and the evidence have to be the same artifact.
Don't Let the Author Grade the Exam
The third move addresses the grading-your-own-homework problem directly, because even a green verify can hide a gap the author didn't think to check.
The fix is to separate the context that writes the change from the context that judges it. The implementing agent is saturated with its own assumptions — it knows what it meant, so it tends to confirm what it meant. A fresh context, or a different judge, doesn't share those assumptions and will notice the file that didn't get re-run, the case that wasn't covered, the behavior that quietly regressed. Concretely this is CI on a clean checkout, or a verifier subagent with no memory of the implementation, or a review bot, or just running the gate in a clean worktree the author didn't set up. The mechanism varies; the principle is fixed: the author is the worst possible judge of whether the author is done.
I think this is the most underrated idea of the whole agentic era, and it generalizes past code. It's the same reason I don't let myself be the only reviewer of an agent's work — I keep a separate pass whose entire job is to be skeptical, because the generating mind and the verifying mind should not be the same mind. Who reviews the AI's code turns out to be the question that decides whether any of this scales. When the same agent both writes and approves, you don't have verification. You have a confident narrator.
Make the Proof Survive the Session
The last move is for work that doesn't fit in one sitting, which is most real work.
Agents lose their memory between sessions, and even within a long session the context compacts — the early reasoning gets summarized away to make room. If your evidence of what's done and what's verified lives only in that volatile context, it evaporates exactly when a multi-day migration or a big refactor needs it most. The next session, or the post-compaction continuation, starts half-blind and either redoes finished work or, worse, marks unfinished work as done because the failure scrolled off.
The fix is to write the proof into the repository, where it persists: a small set of ledgers the agent maintains as it goes. A progress file with the current checkpoint and what's next. An evidence file that holds command output — the actual passing runs, not a summary that says they passed. A decisions file for the architectural choices and their tradeoffs, so a future session doesn't relitigate them or quietly contradict them. The non-negotiable rule for the evidence ledger is that it contains proof, not plausibility: a pasted green run, a diff that's clean, a check that exited zero. "I believe this works" is not an entry. The whole point is to let a cold verification pass — human or agent — reconstruct done from the repo alone, without trusting anyone's memory of the conversation.
The Shape of the Whole Thing
Step back and the four moves are one move wearing different clothes: take the verdict away from the model.
A pure core gives the agent something it can prove instead of assert. One-command verify gives "done" a definition the agent can't reword. A separate verifier keeps the author from grading its own exam. An evidence ledger makes the proof outlive the context that produced it. Every one of them is a transfer of authority — from the confident narrator inside the model to a deterministic check outside it. That transfer is the entire game, because the model's confidence is uncorrelated with correctness and always will be, no matter how good the model gets.
And that's the through-line of the whole series. The repository is the interface the agent programs against. Contracts make its boundaries visible. Gates make its rules real. Verification makes its claims checkable. None of it is about making the agent smarter — the agent is rented, and it's getting smarter on its own, on a schedule you don't control. It's about building the substrate around the agent so that a fast, literal, amnesiac, slightly overconfident worker can operate at scale and have the system catch what it misses.
The agents will keep getting better at writing the code. Our job is to get better at building the thing that decides whether the code is right — and to make sure that thing is never the agent's own opinion of itself.
The final piece of four on agent-maintainable repositories: the repo as agent API, contracts over tribal knowledge, AGENTS.md is not a fence, and this. It rhymes with the model isn't the product, the harness is and code that evolves itself — a repo an agent can verify is a repo an agent can safely keep changing.