Skip to content

Instantly share code, notes, and snippets.

@sshlg

sshlg/proof-of-done.md

Last active August 27, 2026 03:52
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save sshlg/5aa710ee253cb109ea82bb482a699b8f to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save sshlg/5aa710ee253cb109ea82bb482a699b8f to your computer and use it in GitHub Desktop.
Download ZIP
A copy-paste completion protocol for AI coding agents.
Raw
proof-of-done.md

Proof of Done: a completion protocol for AI coding agents

The standard for building software with AI agents.

This is the compact, operational version of The Proof of Done Manifesto. It is designed to be pasted into AGENTS.md, CLAUDE.md, or the context of a coding agent.

It does not replace tests, review, CI, or product validation. It defines what an agent must show before it may claim that software work is done.

The problem

I started formalizing this after a real agent run in which the task inventory was empty while a monitor process was still alive and polling.

Both observations were accurate. They were observations of different things, and the completion signal was looking at the wrong one (the recorded case).

An AI agent can produce code, tests, documentation, and a convincing final report from the same misunderstanding. Agreement between those artifacts is useful, but it is not independent verification.

The agent's final message is an interface, not a source of truth.

Done cannot mean that the agent stopped working or that a task list became empty. It must mean that the current state supports a bounded completion claim that another actor can check.

The completion contract

Every final report must contain four fields:

DONE
  What became true.

PROOF
  What was executed or observed, and where the result lives.

SCOPE
  The commit, environment, requirements, and surfaces covered.

NOT VERIFIED
  What was not checked, could not be checked, or remains uncertain.

NOT VERIFIED: none within the stated scope is a valid answer. Silence is not.

Evidence rules

  1. Every completion claim must point to a supporting record at an address another actor can resolve. A command, exit code, test name, CI run, diff, log, screenshot, deployed URL, or recorded observation can be evidence.

  2. Evidence is bound to scope. A green result on commit A does not prove commit B. A staging check does not prove production. A document that was correct before a migration does not remain correct by inertia.

  3. The agent's own report is not independent proof. Two agents count as independent only when they followed genuinely independent evidence paths.

  4. A passing check is useful only if the check can fail. New gates should be tested against a planted defect, known failing fixture, mutation, or recorded historical failure.

  5. Missing evidence does not become failure or success. It becomes NOT VERIFIED, with the reason stated.

  6. Internal consistency is not truth. Several generated files can agree because they inherited the same wrong assumption.

  7. Completion is proportional to the requested scope. Do not run a production audit for a one-line typo, and do not use a narrow unit test to close a production deployment.

Status vocabulary

Do not collapse these states into done:

State Meaning
generated An artifact exists
executed Code or a check ran
passed A successful result was observed
verified An appropriate check ran and can discriminate failure from success
validated The result addresses the intended user or system outcome
accepted Required coverage is closed and every remaining limit is explicit

The common failure is a jump from generated to done.

Minimum workflow

Before implementation:

  1. Restate the requested outcome as something observable.
  2. Identify the requirements, constraints, affected surfaces, and acceptance boundary.
  3. Decide what evidence would support each important completion claim.

During implementation:

  1. Keep the requested outcome connected to the tasks that implement it.
  2. Record commands, results, changed artifacts, and unresolved limits.
  3. Stop for authority when an action is irreversible, external, or outside the granted scope.

Before reporting completion:

  1. Run the relevant checks against the final state.
  2. Walk the seams between requirements, code, tests, documentation, configuration, and the deployed surface.
  3. Check for residue: background processes, temporary state, uncommitted changes, skipped checks, stale generated files, or a deployment that has not settled.
  4. Produce the four-field completion contract.

Add-on for LLM-maintained wikis

An agent-maintained wiki is derived state.

Raw sources can remain immutable while the agent owns summaries, entity pages, cross-references, and synthesis. That architecture compounds knowledge, but it also creates a specific failure mode: one stale or incorrect source can spread into many mutually consistent pages.

For each material claim, keep enough information to answer:

  • Which source supports it?
  • Which source version was used?
  • When was it last checked?
  • What scope does it cover?
  • Does another source contradict it?
  • Was the claim observed, inferred, or copied from another generated page?

For every ingest or maintenance run, report:

DONE
  Sources ingested, pages created or changed, and contradictions recorded.

PROOF
  Source identifiers, changed-file diff, lint result, and resolvable claim links.

SCOPE
  Source set, wiki revision, schema version, and checks performed.

NOT VERIFIED
  Unread attachments, unresolved contradictions, stale claims, and missing sources.

Cross-links prove that pages are connected. They do not prove that the connected claims are current or correct.

Copy-paste instruction for an agent

Operate under Proof of Done.

Never claim completion from confidence, memory, tool success alone, or an empty task list.

Before changing anything, translate the requested outcome into observable acceptance conditions and identify the evidence needed to support them.

Bind every proof to its actual scope: commit, environment, requirement, surface, and observation time where relevant.

Treat your own summary as an interface, not as evidence. Do not silently convert missing verification into success.

Before the final response, verify the final state, walk the seams between requirements and artifacts, inspect residue, and confirm any requested deployed surface independently.

End every work report with:

DONE: what became true.
PROOF: what was executed or observed, with resolvable locations.
SCOPE: what the evidence covers.
NOT VERIFIED: everything not checked or still uncertain.

If proof is unavailable, say so and stop at the strongest supported state.

Generated, executed, passed, verified, validated, and accepted are different states.

The limit

Proof of Done does not make a model infallible and does not mathematically prove software correct.

It makes the completion claim inspectable, scoped, and easier to challenge without reconstructing the whole conversation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment