The check I kept skipping, made into a thing I can’t skip.
The moment right before you ship is the one most likely to go wrong, and the one you’re most tired for. You meant to grep for a stray key. You meant to re-read the README and make sure every “it does X” is actually true. You meant to check that the thing you’re about to make public is the thing you think it is. I kept meaning to, and kept being the only check — so I built a second one that doesn’t get tired. You point it at a folder; it reads what’s really there and writes down what it saw.
What comes back is an Observation and a short list of Decisions — each one pass, needs-human, or block, and you can always see which sensor said it and why. A claim in your docs that points at real evidence passes. A line shaped like an API key blocks. A “this is signed off” that only a person could truthfully make is held at needs-human, every time. And the whole receipt is tied to the exact contents it measured, so if a single byte of what it saw changes afterward, the fingerprint stops matching.
What it looks at, and what it refuses to do.
The sensors — small readers, each for one kind of thing. file takes the fingerprints. git reads the repository’s real state. claim walks the assertions in your Markdown and asks each one whether it carries an evidence marker. secret-shape looks for text shaped like a credential. fixture checks that an example is actually complete. Each one only reports what it saw; none of them decide anything on their own.
The decision layer — the part that decides is kept deliberately separate, and it is a chain of guards, not a single grader. secret-guard turns a secret-shaped finding into a hard block. boundary-guard keeps it inside the boundary it was given. claim-guard passes a claim only when it points at evidence. And human-gate — the last one — takes everything that a person, and only a person, can rightly say, and holds it at needs-human. It never quietly promotes itself to “yes.”
Don’t take the receipt on my word. Watch it stop at the human line.
Two things to watch: a real scan that writes a real receipt, and the one move that makes it honest — it lays out the evidence and then refuses to sign the part only a person can sign.
# point it at a project; it reads files, git, and the claims in the docs $ python -m provenance_sensorium scan fixtures/sample_project # Provenance Sensorium Receipt Root: fixtures/sample_project Observations: 6 Decisions: 2 ## Decisions - pass via claim-guard on README.md:3 — claim includes an evidence marker - pass via claim-guard on README.md:4 — claim includes an evidence marker ## Human gate Human authorization, authorship, and attestation remain explicit gates. The receipt prepares evidence; it does not sign the human act. $ echo $? 0 # a clean scan exits 0; any block exits 1 — so CI fails closed
A claim that points at real evidence passes, and you can see the sensor that said so. The receipt ends where the machine’s reach ends: at the human gate, written down rather than waved through.
Run live against the committed fixtures/sample_project — exit 0. The CLI is sensorium scan (read a path, print a receipt), sensorium receipt —output FILE (write a JSON receipt that gives the same bytes every time for the same inputs), and sensorium explain (render a stored receipt back to Markdown). Stdlib-only, zero dependencies, github.com/HarperZ9/provenance-sensorium. Honest limit: the secret check is shape-based — a useful net, not a proof that nothing leaked. It catches what looks like a credential; it cannot promise there isn’t one in a shape it has never seen.
# a file containing a line shaped like an API key $ python -m provenance_sensorium scan ./project-with-a-key - block via secret-guard on config.txt:7 — value is shaped like a credential $ echo $? 1 # a block is fail-closed: the release stops here # the JSON receipt is deterministic — same inputs, same bytes, re-derivable $ python -m provenance_sensorium receipt ./project --output receipt.json $ python -m provenance_sensorium explain receipt.json | head -1 # Provenance Sensorium Receipt
A secret-shaped value is not a warning to scroll past — it is a block, and the exit code makes a pipeline stop. The written receipt gives the exact same bytes for the same inputs — like a music box that plays the very same tune, note for note, each time you turn it — so anyone who runs it on the same project gets the identical receipt.
The decision logic is the chain of guards — secret-guard, boundary-guard, claim-guard, human-gate — over the sensors’ observations; the Python API is build_receipt, receipt_to_json / receipt_from_json, explain_receipt, and human_gap_requests. Honest limit: everything here is local-only in v0.1.0 — it reads the project in front of it, nothing remote, and it is a deliberately small first release, a working first version rather than a hardened scanner.
What it is, and what it is not.
Provenance Sensorium is a small reader and a small stack of guards — plain Python, nothing extra to install, 31 tests, clean on main. It is the same three moves the rest of my work is built on, pointed at the moment before you ship: witness what’s there (fingerprint it, the way EMET does), gate the decision default-deny (the way proof-surface does), and hold the human part open.
Plainly: it does not sign off for you, and it can’t. That isn’t a feature I haven’t built yet — it’s the point. A tool that would happily stamp “a person reviewed this” when no person did would be exactly the kind of comfortable lie this is meant to refuse. So it prepares the evidence, marks the human part needs-human, and leaves the actual saying-yes to a real person, where it belongs.
It cannot promise nothing leaked. It can make “I looked” a thing you actually did, with a receipt to show for it.
The honest edges, named out loud: the secret check is shape-based, so it catches what looks like a credential, not everything that could be one. It reads only bounded local state — files, git, Markdown claims — and only locally, in this first version. And it is v0.1.0: a working first release I can stand behind for what it does, not a finished release-gate for someone else’s critical pipeline. Where that line sits, I’d rather tell you than paint over.