Best Before
A green test from yesterday is not a green test.
Best Before is a command-line tool that runs your checklist and prints a certificate of completion with a best-before date. You list your checks in best-before.toml, each one a shell command that must exit 0; run executes them and keeps one line of evidence per check in .best-before/ledger.jsonl, and status prints a certificate only while every check has green evidence that is still fresh. It takes real input only: your own task file, your own commands, the clock, and the files in your folder or git tree. It needs Python 3.11 or newer and nothing else (no packages, no network).
[[check]] name = "tests" run = "bun test" [[check]] name = "lint" run = "bun run lint"
Commands
uv run python best_before.py # status: certificate or refusal, runs nothing uv run python best_before.py run [CHECK ...] # run the checks, record them, then status uv run python best_before.py lot # the lot of the current files (12 hex) uv run python best_before.py --help
-f FILE picks another task file. --at 2026-10-14T09:30 judges the evidence as of another time (status only). Exit codes: 0 certificate issued, 1 not issued, 2 usage or file error.
How evidence goes stale
A check goes stale when the files it was checked against change: the files named in its watch list, or, with no watch key inside a git work tree, every tracked and untracked file that git does not ignore. It also goes stale with age, and the age is earned from its own last ten runs by Laplace's rule of succession: a check that has never flipped earns up to 21 h 49 min of its 24 h cap, a new one earns 12 h, and a flaky one earns little. A check with watch = [], or outside git with no watch key, goes by the clock alone, and the certificate says so. A command that rewrites the files it is checked against can never look fresh. There is no flag, variable or key that issues a certificate by any other route.
The lot
Every certificate carries a lot: 12 hex characters of sha256 over each check's watch hash. lot recomputes it from the files as they are now; if the two match, the certificate describes this very tree.
This folder
The project certifies itself: uv run python best_before.py run here runs its own test suite, a compile check and --help. The tests alone: uv run python -m unittest discover -s tests.
Colophon
Set in whatever your terminal gives. No colour, 72 columns, one date printed in the format of a milk carton. Evidence is kept on this machine and is not committed. Certificates are issued only on presentation of evidence.
normal is dead
Files
- .gitignore
- README.md
- best-before.toml
- best_before.py
- out/check1-run1.err
- out/check1-run1.txt
- out/check1-run2.txt
- out/check1-status.txt
- out/check10-offline-run1.txt
- out/check10-offline-run2.txt
- out/check10-offline-status.txt
- out/demo-1-run.txt
- out/demo-2-after-save.txt
- out/demo-3-failed.txt
- out/help.txt
- out/tests.txt
- out/transcripts.html
- tests/test_best_before.py