Make Codex Prove It: A Three-File Design That Leaves Evidence on Disk

An AI agent telling you "done" is not evidence. When I started delegating work to Codex, I took those reports at face value — until I checked the code and found the change missing, the wrong file edited, or no commit at all. So I stopped trusting language and started making the shell write the facts to disk. Why this design works When you hand a task to Codex, it comes back with "Completed." At first that satisfied me. But when I actually checked the code, the critical change wasn't there, or a different file had been touched, or git commit had never run. The output "I did it" and the fact "it was actually done" are two different things. This is true of Claude Code too. Whether tool results were read correctly, whether errors were swallowed — even with code I wrote myself, running a self-audit right after declaring completion turns up something every single time. Delegating implementation to an AI amplifies that problem by one more notch. The fix is simple: make it write state to a file, not to language. Even if the AI says "completed," it isn't complete unless State: completed exists in the status file. If the handoff file doesn't contain the real output of git status --short , you don't know what changed. If the four sections you specified in the task file (Summary, Files Changed, Validation, Remaining Risks) aren't there, you can't verify it. Files don't lie. An AI under pressure will insist "I did it," but the output of cat status-file can't be forged. Pushing state management down into the filesystem is what makes it possible for a human to cross-check it in a shell . That's the essence of this design. The other important piece is separation of concerns . orchestrate-codex-worker.sh takes three arguments up front. bash scripts/orchestrate-codex-worker.sh <task-file> <handoff-file> <status-file> Each of these three files has a clear role. task-file : The work order for Codex. It contains only "what to do." handoff-file : The handoff note after Codex finishes. Wr