Three files in the worktree. The loop advances on what it can check, never on what a terminal said.
View raw Markdown · llms.txt · For agents
A worker's session is opaque: the harness cannot see its model calls, its tool calls or its reasoning. What it
can see is a worktree. So the contract between the two is three files, at .ak-loop/ in the worktree root.
| File | What it holds | Who reads it |
|---|---|---|
plan.md | The plan the worker actually followed, and where it departed from the approved one | A human, on the pull request |
verify.json | What it ran and what happened, outcome by outcome, with evidence | deliver, before the merge gate |
dod.json | The definition-of-done proofs, both lists | deliver, and the table it writes onto the PR |
{
"ranAt": "2026-09-20T18:04:11.000Z",
"command": "pnpm test packages/report",
"exitCode": 0,
"outcomes": [
{ "id": "o1", "status": "passed", "evidence": "42 passed | 0 failed" }
]
}Present, and valid
deliver reads the artifacts before the merge gate and requires verify.json (and plan.md where a plan was
approved). A file that is missing comes back as a fix round naming it — "which file?" is the only question
the worker needs answered. A file that exists but does not match its schema is called out as worse than
absent, because it looks like evidence.
One exception, and it is about honesty rather than leniency: a dispatch record with no worktree path is left out of the gate entirely. The harness has nowhere to look, and blaming a worker for a file nobody can open is how a loop invents work.
verify.json counts as evidence
An outcome the worker proved in verify.json but did not repeat in dod.json is still proven. It ran the check
once; asking it to transcribe the same result into a second file only invents a way to be inconsistent. Where
both exist, the explicit definition-of-done proof wins: it is the more specific statement.
Why files and not a terminal
The alternative is reading the worker's screen. That fails in three ways at once: the text is unstructured, it scrolls away, and a model that says "all tests pass" is indistinguishable from a model that ran them. Files can be parsed, hashed, committed, attached to the pull request and read again next week.
It is also what makes a handoff cheap. A new provider taking over an in-flight task reads git history and these three files; nothing about the previous session needs to survive.