What a completion receipt needs before it can catch a false claim

An agent that reports success and an agent that reports success without doing anything produce the same sentence. Two of the failures I have written about this month were only caught because something outside the agent recorded what the world looked like before and after. This is the shape of that record: what it has to contain, and which parts do the actual work.

Quick answer

A receipt that can catch a false completion claim needs four things recorded by the caller, not by the agent:

• the digest of the target before the operation
• the digest after
• whether a write was actually issued
• an independent read of the result from outside the system that performed it

The first two are the assertion. The third distinguishes a skipped no-op from a failed write. The fourth is what makes the receipt evidence rather than a second opinion from the same process.

Everything else on a receipt is convenience.

Steps: build the record around the write

1. Capture the before state as a digest, not a copy

A copy tells you what was there. A digest tells you whether it changed, in one comparison, and it stays small enough to keep forever.

before_content_sha256: 508108516b75cd9b14628e869e584723adbfcdd93133673c67a47e275b1ddafb

Take it from the same read path the write will use. A digest of a cached copy proves nothing about the thing you are about to modify.

2. Record whether a write was issued at all

This field is the one most receipts omit, and it is the one that answers the most common question later.

write_performed: false

before_content_sha256: 5ee35b84ac019fc6f2e4626abe3cd696b998c28bae2c0645ebc58bea46f2feee
after_content_sha256:  5ee35b84ac019fc6f2e4626abe3cd696b998c28bae2c0645ebc58bea46f2feee

That is a real entry from a template update. The digests match because nothing changed, and write_performed: false says why: the target already satisfied the plan, so the operation was skipped deliberately. Without that field, identical digests are ambiguous. They could mean a correct skip or a write that silently failed.

3. Capture the after state from a fresh read

Not from the response body of the write. A write endpoint returns what it believes it stored, which is the same source that would be wrong if something went wrong. Read the target again.

after_content_sha256: 01c7de9cff5e6783303ed7368a376e7ef9b6606d226af4e09424f0d553ad6ccd

replacements: 14

The count next to it is worth keeping. A changed digest says something happened; the count says how much, and a plan that expected 14 substitutions and recorded 2 is a finding rather than a success.

4. Verify from outside

The strongest field on a receipt is the one gathered by a different path than the one that made the change:

public_verification:

  name: latest_post
  url: https://readsikit.com/2026/08/17/qwen-38-default-thinking-effort/
  http_status: 200
  visible_byline: true

An authenticated API can report a change that the public surface does not serve, because of caching, a failed rebuild, or a permission difference. If the change is supposed to be visible to someone else, check it as someone else.

5. Bind the receipt to the plan it executed

plan_sha256: 8816ac518a7047585466d5cfa71f5b2ce4cddca88d36ff313c8610d1b79aeaf9

A receipt that does not name the exact plan it carried out cannot be audited against intent. With the digest, a later reader can confirm the plan file on disk today is the one that ran, and notice when it is not.

Caveats

A receipt is only as good as its read path. All four fields can be produced by an agent that reads through a layer that lies to it. That is why the external verification exists, and it is also why the external check should use the plainest possible client.

Digests only detect change, not correctness. A write that changes the digest to the wrong content produces a receipt that looks healthy. Pair the digest with an assertion about identity: title unchanged, slug unchanged, date unchanged, whatever the operation was not supposed to touch. In the batch behind this article those assertions ran on every item and were recorded per item.

Receipts cost storage and are worth it. The evidence directory behind this site holds 325 receipt files across 40 operations. That is a few megabytes to be able to answer "did that actually happen" about anything from the last two months without re-deriving it.

Do not let the agent write its own receipt. The point of the record is that it does not depend on the agent’s account of events. A receipt generated inside the same turn that made the claim inherits the claim.

Troubleshooting

The digests differ but the change looks absent. Something else wrote between your before-read and your after-read. Re-run the before-read and compare; if it has moved again, you have a concurrent writer and a receipt cannot settle the question on its own.

The digests match and write_performed is true. The write was issued and had no effect. Common causes are a payload the server accepted and ignored, a field name that does not exist on that endpoint, and a write to a stale identifier. All three return success.

The external check disagrees with the authenticated read. Usually caching. Re-check with a cache-busting parameter before concluding anything; a stale edge response reads exactly like a failed write, and I have mistaken one for the other.

You have no before-digest because the run already happened. Then you cannot answer the question, and the honest move is to say so rather than infer from the agent’s summary. Add the field and wait for the next run.

Limits and evidence

The receipt fields above are taken from an operating ledger of 325 files across 40 dated operations, and from the batch that ran while this article was being written. They are one working design, not a standard. Nothing here is specific to a particular agent or CMS beyond the field names.

I have not measured how often the fields catch something. What I can say is which ones caught the failures I have written up: write_performed distinguished a deliberate skip from a failure, and the external read is what showed a change had landed when a cached response suggested otherwise. The plan digest has never caught anything for me. I keep it because the failure it guards against is the one that would be hardest to reconstruct afterward.

Sources

The receipt structures quoted here are from this site’s own operating ledger and are reproduced verbatim above. No external documentation defines this format; it is a working design, and the fields are the argument.

The digest function is the one standardised choice in it.

• FIPS 180-4, Secure Hash Standard — NIST, the specification for SHA-256

Related articles

• Exit code 0 from an agent that did nothing
• My read-only agent wrote to disk, and the sandbox flag was set