assurance

Did the job cover everything it was supposed to cover?

An agent, a script or a person tells you the work is done. This decides whether that is true — from declared expectations and observed evidence, by code, with no model anywhere in the answer.

The one rule everything here follows: a denominator we cannot establish is refused, never invented. A tool that answers "0 of 36" for a folder it did not understand is worse than one that says it does not know, because you cannot argue with a number that was made up.

Thirty seconds

pip install assurance-cli
assurance check ~/reports

No config, no corpus file, no setup. It works out the cadence, the span and what is absent from the filenames alone. A folder with no regular cadence is told so rather than handed a ratio.

What is in here

Each ships to PyPI independently and versions on its own — a release tag names its package (cli-v0.5.1), because a bare version number is ambiguous between three.

Which one do you want?

• You have a folder and a question. assurance-cli. Nothing else needed.
• You have an agent that should check its own work. assurance-mcp, or the report-coverage skill.
• You are building the check into your own system. assurance-core. It is deliberately dependency-free so it can sit inside anything.
• You are worried an agent becomes a way to read things people cannot read. That is a separate project built on this one: assurance-authority.

The two commands people adopt first

assurance pin --check      # fail the build when an MCP server changes a tool definition
                           # after you approved it (CVE-2025-54136)
assurance drift runs.jsonl # did the failure rate actually shift, or was the week noise?

drift reports no labels, no judge and no benchmark — it says whether a change is distinguishable from noise, and it refuses when there is not enough history to say. Its README leads with the false-alarm rates of the textbook methods it rejected, because that is the part worth checking.

Layout

packages/core/     assurance-core   — generated; see below
packages/cli/      assurance-cli
packages/mcp/      assurance-mcp
skills/            agent skills that use the tools above

packages/core/ is generated and must not be hand-edited. It is scrubbed out of a private upstream by a publisher that rewrites the whole tree, so an edit made here is destroyed on the next run and never reaches anyone. Everything else in this repo is ordinary hand-written code, and pull requests are welcome against it.

Honest limits

• check opens .csv, .tsv and .xlsx only. Anything else in the folder is counted and named, not silently skipped.
• The span is inferred from the earliest and latest filenames unless you pass --from / --to, which means a report missing from either end of the range cannot be detected. Pass the range when you know it.
• expected is never inferred in the MCP tools. A denominator nobody can argue with is not an answer.
• No cross-document inference. It produced 21 false positives on a real corpus, so it is refused.

Licence

Apache-2.0.