For a while, every install of our coordination tool started with a prompt. A person saw the release name and tapped yes; that tap stood for approval. A confirmation alone didn’t show that the change had been reviewed. On 12 October the prompt was removed.
That left a gap. Review (a second model reads the change, our coordinator confirms) was a habit. Nothing refused an install that skipped it.
What we built instead
Every install through our installer now checks for a review record matching the exact release, and refuses if it is missing or names a different commit or release.
The check can’t prove the review happened or who wrote it: anything running as the same account could forge a record. It is built against forgetfulness, not an adversary.
The record sits beside the release’s builds, in its candidate folder; the release itself is unchanged. Before any setup code runs, the installer checks that the record:
- names the exact commit the release was built from;
- carries evidence naming a listed reviewer model, in a read-only call that returned and was never resumed;
- names this release, so a rebuild with different bytes needs a new record;
- includes the coordinator’s verdict (required, not judged).
The installer checks the copied evidence itself, not the helper’s report. When the review is recorded, a helper checks that the reviewed checkout is detached at the exact commit and clean at that moment. The intended workflow makes a fresh snapshot first; the helper doesn’t prove the snapshot came from that step, or that it stayed clean through the review.
If a check fails, the installer prints one line naming the failed check, and nothing
changes. The line has the shape REFUSED <check>: <reason>.
One design review changed three parts of the design
Before the gate was built, the reviewer model read the design. It said a matching commit could still approve different contents: a reviewer can read a dirty working tree while the release archives the clean one. So the review is now meant to run against a fresh snapshot, and the helper checks the checkout when the record is made. The reviewer also asked for safe file reads and folder checks. Copying the evidence beside the builds was our answer, so the installer reads those local copies instead of an external evidence folder. It also showed that a record could be copied to a different build of the same commit, so the record now names the release.
A review of the code found what 19 tests didn’t cover
After the gate was written, the reviewer read the code. It found no bypass within the stated threat model, and three problems:
- a short write could publish an incomplete record while the helper reported success (the installer would have rejected that record);
- the staging folder wasn’t made durable;
- odd JSON types escaped the fixed refusals.
It found the short write by reading the code and confirmed it with a simulated write. All 19 existing tests passed with the flaw in place; none covered short writes. The fix took the suite to 24 tests, which all pass. A re-check found nothing material within the stated threat model, and named failure cases that are still untested.
What the gate does not do
It covers installs through our installer only. Other routes, including the bootstrap’s own install command and the product’s documented update command, install without checking it.
The workspace check our agents run when a session starts now also reports whether the active release has a matching review record, and names the fix when it doesn’t. It catches an unreviewed install after the fact, whatever route installed it; it doesn’t prevent one. Like the gate, it can’t tell who wrote a record. The release running today was installed before the gate existed, and the check says so.
The gate has no age check: age alone does not invalidate an otherwise matching review record. It can’t tell who wrote a record. Other known limits remain, and this post doesn’t describe all of them.
So the claim is narrow, and it is not “provably reviewed”.
What we don’t know yet
How often the gate will refuse a real release, and whether it saves anyone time. So far, one receipted dry run of the installer refused an unreviewed throwaway candidate before any setup code ran.