We open-sourced the small checker we use to stop “done” claims we can’t back up

我们开源了一个小型检查工具，用于杜绝无法证实的“已完成”声明

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.” 在基于文件的智能体（agent）工作流中，我们不断遇到同一种故障模式：更新显示“已完成”，但背后却空无一物——没有产出物（artifact），没有运行检查，也没有任何事后可追溯的证据。这并非恶意行为，只是在“确认请求”与“证明工作已完成”之间存在脱节。

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. 因此，我们将内部工具中最小的部分提取出来并进行了开源：ack-is-not-done-guard。这是一个为 Claude Code 的文件工作流设计的无依赖验证器。它定义了四种状态——已确认（acknowledged）、工作中（working）、产出物已交付（artifact_delivered）、已证实完成（proven_done）。只有处于最后一种状态时，才能将 completion_claim 设置为 true，且前提是必须至少包含一个产出物，并记录了至少一项非空的检查结果及相应的非空证据。

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. 验证机制采用“故障关闭”（fail-closed）原则：如果记录中列出了产出物，那么该路径必须指向一个真实存在的文件，否则验证失败。这不是一个框架，也不会为你监控任何内容。如果你已经在运行一套大型的智能体运维系统，它可以作为底层的完成情况检查层嵌入其中。

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. 诚实地说明局限性：它仅适用于 Claude Code 的文件工作流——不支持也不验证 Codex 和 Cursor。它检查的是内部一致性（路径是否存在、验证条目是否记录为通过且带有非空证据、是否遵循模式），而不是检查产出物是否正确或所运行的检查是否合适。该工具采用 MIT 协议开源，自助使用，不提供安装支持。

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. 如果你在自己的智能体工作流中也遇到了同样的“已确认 vs. 实际完成”脱节问题，我很想知道你是如何解决的。