heavy-duty/box
7
0
Fork 1
Code Issues 9 Pull requests Projects Releases 4 Packages Wiki Activity Actions

docs(readme): how to run the drill against the latest version

Browse source 
The drill section showed the commands but not the step that actually
bites: making sure the checkout you run is the code you mean to judge.
Two versions are in play — the drill script itself, and the (repo, ref)
the drill installs from GitHub and asserts before any verdict. Spell both
out, plus --repo/--ref for drilling a release or a PR branch.

Also catch drill.sh's REPO default up with the rename — it still said
heavy-duty/claudebox (GitHub redirects it, but the default should name
the repo that exists).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
claude-hdb 2026-07-15 00:28:15 +00:00
parent 4890c9a3d9
commit 342b533f4f
2 changed files with 21 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
README.md
View file

@ -249,13 +249,33 @@ pre-0.4.0 box through `migrate-host`, and removes what it minted —
currently **81 checks, 81 passing**. [drill/RUNS.md](drill/RUNS.md) is the full
history, including every trap that fooled a run into a wrong verdict.
### Run the drill yourself
The drill ships in the repo, not the installed tree — run it from a checkout.
Two versions are in play and both must be current: **the drill script you
run** (a stale checkout judges the past), and **the code under test** — the
drill does not test your working tree; it installs box from GitHub
(default: `heavy-duty/box@main`) and asserts the installed tree is exactly
the ref it asked for before issuing any verdict.
```sh
git clone https://github.com/heavy-duty/box && cd box # or refresh an existing
git log --oneline -1 # checkout — this commit is
# the drill that will judge
bash drill/doctor.sh # read-only: is this host healthy and the stack live?
bash drill/drill.sh # FULL end-to-end — mutates the host; use a machine you own
bash drill/wipe.sh # scorched earth: strip BOTH name generations, images and
# (--purge-storage) the pool, so a run starts from bare
```
To drill something other than latest `main` — a release ref, or a PR branch
on a fork:
```sh
bash drill/drill.sh --ref <branch-or-tag>
bash drill/drill.sh --repo <owner>/<repo> --ref <branch> # a PR under review
```
The doctor reads ground truth, not config claims — the kernel's `isolated on`
flag per bridge port, the process table, the resolver actually in use — and
diagnoses the host faults that have actually happened: a wedged Incus daemon,

2
drill/drill.sh
View file

@ -32,7 +32,7 @@
# false FAILs on the first live run. The pipeline verdict must be grep's alone.
set -u
REPO="${BOX_REPO:-heavy-duty/claudebox}"
REPO="${BOX_REPO:-heavy-duty/box}"
REF="${BOX_REF:-main}"
YES=0; KEEP=0
SELF="$(readlink -f "$0")"