We kept hitting the same failure shape in file-based agent workflows: an
update says "done," and there's nothing behind it — no artifact, no check
that ran, nothing you could point to later. Not malicious, just a gap
between "acknowledged the request" and "proved the work."
So we pulled the smallest possible piece of our own internal tooling out
and published it: ack-is-not-done-guard,
a dependency-free validator for Claude Code's file-based workflows.
It defines four states — acknowledged, working, artifact_delivered,
proven_done — and only the last one may set completion_claim: true, and
only if there's at least one artifact and at least one non-empty check
recorded as passed with non-empty evidence. Validation is fail-closed: if
a record lists an artifact,
the path has to resolve to a real file, or it fails.
This is not a framework and it doesn't watch anything for you. If you
already run a larger agent-ops system, it's meant to slot in as the
completion-checking layer under it. If you don't, the template, the
response contract, the examples, and the tests are the whole surface —
your existing process still creates and updates the record; this rejects
completion records that do not meet the declared schema and file-existence
checks.
Honest limits: it's scoped to Claude Code's file-based workflows only —
Codex and Cursor aren't supported or verified against. It checks internal
consistency (paths exist, verification entries are recorded as passed with
non-empty evidence, and the schema is followed), not that the artifact is
correct or the check was the right one to run. It's MIT-licensed,
self-service, no setup support.
If you're running into the same "acknowledged vs. actually done" gap in
your own agent workflows, curious what you're using to catch it.
Top comments (0)