Merge pull request #134 from claude-bot-andresmgsl/build/133-drill-defaults-prose

docs(drill): the defaults are sane now, and that is exactly the danger

CHANGELOG.md

@@ -21,6 +21,7 @@ on the way to cutting its first release, and this file starts there.
 
 ### Fixed
 
+- The drill's docs no longer claim both installers default to `main` — box installs the `BOX_RELEASE` pin, rig the latest release, and its `--box-ref` example is now a tag (#133)
 - `kimi-bot-andresmgsl` is on the review panel — the roster predated it joining the bench (#120)
 
 ## 0.3.0 — 2026-07-21

drill/README.md

@@ -17,9 +17,12 @@ release (#105, and #107's debt).
 - **The pinned candidate refs, both of them.** `--rig-ref` and
   `--box-ref` are required; the harness refuses to run without them and
   refuses to continue if what installed disagrees with what was asked
-  (`INSTALLED_FROM`, both trees). Until heavy-duty/rig#103 lands, both
-  installers default to `main` when unpinned — which is exactly why the
-  drill will not let a ref go unstated.
+  (`INSTALLED_FROM`, both trees). Since heavy-duty/rig#103 landed, both
+  installers have sane defaults when unpinned — box installs the
+  `BOX_RELEASE` pin (currently `0.9.0`), rig's `install.sh` resolves the
+  latest release — and a sane default is exactly why the drill will not
+  let a ref go unstated: an unpinned run silently drills a shipping pair
+  that is not the candidate, and the record it leaves looks clean.
 - **A single-use, tagged tailscale pre-auth key** in `TS_AUTHKEY`
   (`tag:local` for the default `staging-server` role — bootstrap refuses
   `tag:server` outside the control-plane shapes).
@@ -45,11 +48,15 @@ in the checkout's `drills/`):
 
 ```sh
 TS_AUTHKEY=tskey-... bash drill/drill.sh \
-  --rig-ref release/0.4.0 --box-ref release/0.10.0 \
+  --rig-ref release/0.4.0 --box-ref 0.9.0 \
   --users ./drill-users --run-id drill-2026-07-24-a \
   --coolify-version 4.1.2 --runner-repo you/rig --yes
 ```
 
+`--box-ref` is a tag on purpose: since #103 the box that ships is the
+`BOX_RELEASE` tag, so a `release/…` branch is the wrong thing to pin for
+box — while a release branch stays exactly right for rig's own candidate.
+
 It runs unattended from there. Legs execute as 1, 4, 2, 3 — Coolify's
 installer is what puts Docker on the box and the db leg needs a daemon —
 and the record lists them as they ran. A failing check never aborts the

drill/drill.sh

@@ -8,10 +8,10 @@
 #     Never run it on a machine you care about.
 #
 #   TS_AUTHKEY=tskey-... bash drill/drill.sh \
-#     --rig-ref release/0.4.0 --box-ref release/0.10.0 \
+#     --rig-ref release/0.4.0 --box-ref 0.9.0 \
 #     --users ./drill-users --run-id drill-2026-07-24-a \
 #     --coolify-version 4.1.2 --runner-repo you/rig --yes
-#
+#   (--box-ref is a tag: since #103 the box that ships is the BOX_RELEASE tag.)
 # rig's drill asserts CONVERGENCE — a machine reaches its role, idempotently.
 # The legs (drills/README.md, issue #105):
 #
@@ -130,11 +130,12 @@ tree_of() {
 
 # assert_installed_from <what> <tree> <want> — ASSERT WHAT LANDED, never trust
 # that the install obeyed. An installer invoked with stale env vars silently
-# falls back to its defaults (rig#103: both BOX_REF and RIG_REF default to
-# main), and a drill that thinks it exercised release/X but actually got main
-# has proven nothing about the combination that ships — worse than one that
-# fails, because the record it leaves LOOKS like evidence. Refusal names both
-# refs, per #105's acceptance criteria.
+# falls back to its defaults — sane ones since rig#103 landed (box: the
+# BOX_RELEASE pin, rig: the latest release), which is what makes the fallback
+# invisible — and a drill that thinks it exercised release/X but actually got
+# whatever the defaults resolve to has proven nothing about the combination
+# that ships — worse than one that fails, because the record it leaves LOOKS
+# like evidence. Refusal names both refs, per #105's acceptance criteria.
 assert_installed_from() {
   local what="$1" tree="$2" want="$3" got
   got="$(cat "$tree/INSTALLED_FROM" 2>/dev/null || echo '<unreadable>')"
@@ -383,7 +384,8 @@ ok "installed tree confirms: $REPO@$REF (version $DRILL_VERSION)"
 phase "Leg 1 — convergence: rig bootstrap $ROLE"
 # =============================================================================
 # BOX_REPO/BOX_REF ride the environment into bootstrap's host=yes box install,
-# so the box that lands is the pinned candidate, not box's default (main).
+# so the box that lands is the pinned candidate, not what bootstrap falls back
+# to unexported (the BOX_RELEASE pin, since rig#103 landed).
 export BOX_REPO="$BOXREPO" BOX_REF="$BOXREF"
 
 t0=$SECONDS