Cut the narration from TODO.md and the script and Dockerfile comments (closes #49)

Completed Steps entries keep what landed, the traps, every disclosure
and every record that a check ran; the argument and history go, with
bare issue numbers turned into full links. Comment blocks in script/,
Dockerfile and Dockerfile.lint keep the trap and drop the defence of
past decisions. TODO.md Workflow now branches from next, targets next,
and leaves merging next to main to the owner. Only comments and
Markdown change.

Model: opus-5-5

script/bootstrap

@@ -1,14 +1,9 @@
 #!/bin/sh
 # script/bootstrap: install all dependencies needed to build and develop
-# this repo. Idempotent: every install is guarded by a check so already
-# installed tools are skipped. Base tooling comes from nix, apt, brew,
-# or apk (detected in that order); assumes nothing is present (not git,
-# make, or go). Neither the linter nor the Markdown formatter is
-# installed: golangci-lint (script/lint) and prettier (script/fmt,
-# script/fmt-check) run via docker only, pinned by hash, so their only
-# prerequisite is a working docker — which is warned about, not
-# installed, because everything except linting, formatting and
-# make test-race works without it.
+# this repo. Idempotent; assumes nothing is present (not git, make, or
+# go). Base tooling comes from nix, apt, brew, or apk (detected in that
+# order). golangci-lint and prettier are never installed: they run via
+# docker only (script/lint, script/fmt, script/fmt-check).
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
@@ -63,22 +58,15 @@ missing() {
 main() {
     cd "$ROOT"
 
-    # System tooling, deliberately unpinned: these come from the host
-    # package manager and whatever version it ships is what the host
-    # gets, so a presence check is the right check. The repo pins no
-    # system toolchain versions — the Go language version is governed by
-    # go.mod, and builds that must be reproducible run in the Docker
-    # image, whose base images are pinned by digest.
+    # Deliberately unpinned, so presence is the whole check: go.mod
+    # governs the Go version, and reproducible builds run in the
+    # digest-pinned Docker images.
     if missing git; then pkg_install git git git git; fi
     if missing make; then pkg_install gnumake make make make; fi
     if missing go; then pkg_install go golang go go; fi
 
-    # Linting and Markdown formatting run via docker only, so docker is
-    # their prerequisite rather than something bootstrap installs. Warn,
-    # do not fail: everything except `make lint`, `make fmt`,
-    # `make fmt-check` and `make test-race` — and, through them,
-    # `make check`, `make docker` and the pre-commit hook — works
-    # without it.
+    # Warn, do not fail: only the targets named below, and the
+    # pre-commit hook, need docker.
     if missing docker; then
         echo "bootstrap: WARNING: docker not found; make lint, make fmt," >&2
         echo "bootstrap: make fmt-check, make check, make docker and" >&2

script/cibuild

@@ -1,30 +1,12 @@
 #!/bin/sh
 # script/cibuild: run the CI build. The Gitea workflow runs this on
-# push.
+# push. The Dockerfile runs every gate make check runs, as build steps,
+# so a successful build means the repo is green.
 #
-# The Dockerfile runs the gates individually as build steps, not the
-# make check aggregate: the lint stage runs the gofmt check,
-# script/verify-lint-image-pin, golangci-lint config verify and
-# golangci-lint run; the markdown stage runs the prettier check; the
-# build stage, dropped to an unprivileged user, runs make test. None of
-# make lint, make fmt-check or make check appears, because each runs
-# docker, and docker cannot run inside a docker build. Nothing is
-# skipped by that — the linter, gofmt and prettier are invoked directly
-# in their stages, and the build stage's COPY --from lines make those
-# stages prerequisites, so BuildKit must finish them first. Between the
-# three stages everything make check would run has run, which is why a
-# successful build here implies the repo is green.
-#
-# That implication holds only because of CHECK_EPOCH. A COPY layer is
-# invalidated only by changed content, and a rebuild of an unchanged
-# checkout sends the same content, so without a fresh value here Docker
-# serves the gate layers from cache and the build reports a green it
-# never earned. Passing the current epoch invalidates the gate
-# layers on every run while leaving the pinned base images and
-# go mod download cached; see the Dockerfile for the placement. The
-# process id goes in with the epoch so that two runs started in the
-# same second still get different values, the same form script/lint
-# uses.
+# Without a fresh CHECK_EPOCH, a rebuild of an unchanged checkout serves
+# the gate layers from cache and passes having run none of them. The
+# process id goes in with the epoch so two runs started in the same
+# second still differ.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"

script/docker

@@ -1,14 +1,9 @@
 #!/bin/sh
 # script/docker: build the Docker image tagged with the project name.
-# The tag comes from script/projectname.
-#
-# CHECK_EPOCH is passed for the same reason script/cibuild passes it:
-# without a fresh value Docker serves the gate layers from cache on an
-# unchanged tree and this exits 0 having run none of the lint stage's
-# gates, the markdown stage's prettier gate or the builder stage's test
-# gate. This is the set of gates a developer or reviewer runs by hand,
-# so a cached pass here is the most misleading result the repo can
-# produce. Dependency layers sit above the ARG and stay cached.
+# The tag comes from script/projectname. CHECK_EPOCH is passed for the
+# same reason script/cibuild passes it: without a fresh value an
+# unchanged tree is served from cache and this exits 0 having run no
+# gate.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"

script/lint

@@ -1,23 +1,17 @@
 #!/bin/sh
 # script/lint: run the linter. golangci-lint is never installed on a
-# host: it runs via docker only, one way, everywhere — this builds
-# Dockerfile.lint, which COPYs the repo into the digest-pinned
-# golangci-lint image and lints as a build step, so a successful build
-# is a clean lint. The only prerequisite is a working docker. The gate
-# steps make no network calls of their own, but Dockerfile.lint runs
-# `go mod download` above them, so a cold cache does reach the network
-# (as does pulling the pinned image); that layer stays cached, and once
-# it is warm this runs offline until go.mod or go.sum changes.
+# host: this builds Dockerfile.lint, which copies the repo into the
+# digest-pinned golangci-lint image and lints as a build step, so a
+# successful build is a clean lint. A cold cache needs the network to
+# pull the image and for `go mod download`; once warm this runs offline
+# until go.mod or go.sum changes.
 #
-# CHECK_EPOCH is what makes the result mean anything. Without it docker
-# serves the gate layers from cache on an unchanged tree and this exits
-# 0 in well under a second having run no linter. The PID is in the value
-# as well as the epoch because two lint runs land inside the same second
-# easily, and `date +%s` alone would cache the second one.
+# Without a fresh CHECK_EPOCH docker serves the gate layers from cache
+# on an unchanged tree and this exits 0 having run no linter. The PID is
+# in the value because two lint runs land inside the same second easily.
 #
-# The result is the build's exit status and the image is never used, so
-# --output=type=cacheonly writes none. Without it every run spends
-# seconds exporting an image and leaves it behind untagged.
+# The image is never used, so --output=type=cacheonly writes none;
+# without it every run leaves an untagged image behind.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"

script/verify-lint-image-pin

@@ -2,23 +2,16 @@
 # script/verify-lint-image-pin: fail unless the golangci-lint image
 # referenced by Dockerfile.lint and the one referenced by the main
 # Dockerfile's lint stage are the same image at the same digest. Our own
-# extension to scripts-to-rule-them-all, not one of its entrypoints.
+# extension to scripts-to-rule-them-all, not one of its entrypoints; run
+# as a gate in both files. Nothing else keeps the two pins in sync, and
+# a bump applied to one alone would lint the same tree against different
+# rulesets, both green.
 #
-# The linter version is pinned in two independent files. That is the
-# shape #42 turned into a build failure rather than tolerate: nothing
-# else keeps the two in sync, and a bump applied to one file alone would
-# leave `make lint` and the fail-fast lint stage of `make docker`
-# linting the same tree against different rulesets, both green. This is
-# the single guard that stops it, run as a gate in both files.
+# Do not hardcode the expected digest here: that is a third copy to keep
+# in sync.
 #
-# It deliberately restates neither pin. A hardcoded expected digest here
-# would be a third copy — one more thing to bump, and the same drift one
-# file further out. It compares the two files to each other and knows
-# nothing about which version is correct.
-#
-# A reference that cannot be read is a hard failure, not a skip: a
-# comparison of two empty strings succeeds, which would turn this guard
-# into exactly the unearned green it exists to prevent.
+# A reference that cannot be read is a hard failure, not a skip: two
+# empty strings compare equal.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"