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

Dockerfile

@@ -6,47 +6,36 @@ COPY go.mod go.sum ./
 RUN go mod download
 COPY . .
 
-# Cache-buster for the gate layers, and only for them. Docker
-# invalidates COPY only when the copied content changes, so on an
-# unchanged tree the gates below would be served from cache and the
-# build would exit 0 having run nothing. script/cibuild and
-# script/docker pass a fresh CHECK_EPOCH on every invocation. A build
-# that passes none, such as a bare `docker build .`, fails at the check
-# right after the ARG instead of quietly serving the gates from cache.
+# Cache-buster for the gate layers, and only for them: on an unchanged
+# tree Docker would serve the gates below from cache and the build would
+# exit 0 having run nothing. script/cibuild and script/docker pass a
+# fresh CHECK_EPOCH; a build without one, such as a bare
+# `docker build .`, fails at the check right after the ARG.
 #
-# Two properties this depends on. ARG is per-stage, so the markdown and
-# build stages below declare it again; one declaration here would leave
-# their gates cacheable. And each gate RUN must reference the value,
-# because BuildKit hashes the expanded command: a declared but
-# unreferenced ARG invalidates nothing.
-#
-# It sits below the dependency layers deliberately. Everything above it
-# (the pinned base image, go mod download) keeps its cache; only the
-# gates go cold.
+# ARG is per-stage, so the markdown and build stages declare it again.
+# Each gate RUN must reference the value: BuildKit hashes the expanded
+# command, so a declared but unreferenced ARG invalidates nothing. Keep
+# it below the dependency layers so they stay cached.
 ARG CHECK_EPOCH
 RUN if [ -z "${CHECK_EPOCH}" ]; then \
         echo "CHECK_EPOCH is unset; build via script/cibuild or script/docker" >&2; \
         exit 1; \
     fi
 
-# The linter is invoked directly here, not through `make lint`. That
-# target now runs `docker build -f Dockerfile.lint`, and a docker build
-# cannot run a docker build: routing the gate through make would mean
-# nesting docker inside this image. Same reason `make check` is gone
-# from the build stage below, and `make fmt-check` from both stages: it
-# runs prettier through docker too. Its gofmt half is the step below,
-# its Markdown half the markdown stage further down. gofmt's output is
-# assigned to a variable first so that its own exit status, as when it
-# cannot parse a file, still fails the step.
+# These gates call the tools directly, not through `make lint` or
+# `make fmt-check`: both run docker, which cannot run inside a docker
+# build. This step is the gofmt half of `make fmt-check`; the markdown
+# stage is its prettier half. gofmt's output is assigned to a variable
+# first so that its own exit status, as when it cannot parse a file,
+# still fails the step.
 RUN echo "gate gofmt, epoch ${CHECK_EPOCH}" && \
     files="$(gofmt -s -l .)" && \
     if [ -n "$files" ]; then \
         echo "gofmt: files not formatted:" >&2; echo "$files" >&2; exit 1; \
     fi
 
-# The FROM above and the one in Dockerfile.lint pin the same linter
-# twice, and nothing else keeps them in sync; this fails the build when
-# they disagree. See the script for why it restates neither pin.
+# Fails the build when the FROM above and the one in Dockerfile.lint pin
+# different linter images.
 RUN echo "gate lint-image-pin, epoch ${CHECK_EPOCH}" && \
     script/verify-lint-image-pin
 
@@ -93,16 +82,13 @@ FROM golang@sha256:56961d79ea8129efddcc0b8643fd8a5416b4e6228cfd477e3fd61deb2672c
 
 # We never build or run as root. Create an unprivileged user and point
 # HOME and the build cache at its home so go build and go test can write
-# it when we drop to it below. $GOPATH/bin is deliberately not on PATH:
-# script/bootstrap no longer `go install`s anything (the linter runs
-# from a pinned image, never from a host install), so nothing lands
-# there and adding it would only widen what this image resolves.
+# it when we drop to it below.
 #
-# The module cache is kept outside that home, at the base image's
-# default /go/pkg/mod, and belongs to root: script/bootstrap fills it as
-# root. Do not move it into the home and hand it over with `chown -R`:
-# that walks every file in it, which took from about 80 s to over ten
-# minutes on a shared host, depending on load.
+# The module cache stays at the base image's default /go/pkg/mod and
+# belongs to root: script/bootstrap fills it as root. Do not move it
+# into the home and hand it over with `chown -R`: that walks every file
+# in it, which took from about 80 s to over ten minutes on a shared
+# host, depending on load.
 RUN adduser -D -u 1000 builder
 ENV HOME=/home/builder
 ENV GOPATH=/home/builder/go
@@ -111,24 +97,16 @@ ENV GOCACHE=/home/builder/.cache/go-build
 
 WORKDIR /src
 
-# No-op file copies whose only purpose is the build-graph edge: they are
-# what make this stage depend on the lint and markdown stages, and so
-# what forces BuildKit to finish gofmt, the pin guard, lint and prettier
-# before compilation and tests start. Remove one and the fail-fast
-# design dies silently — the build stops gating on that stage and still
-# exits 0. The first replaces a copy of the linter binary itself, which
-# is no longer wanted here: nothing in this stage runs the linter,
-# because `make lint` is now a docker build and a docker build cannot
-# run inside one.
+# No-op file copies whose only purpose is the build-graph edge: they
+# make this stage depend on the lint and markdown stages, so BuildKit
+# finishes those gates before compilation and tests start. Remove one
+# and the build silently stops gating on that stage and still exits 0.
 COPY --from=lint /src/go.sum /dev/null
 COPY --from=markdown /src/go.sum /dev/null
 
-# Install development prerequisites the same way a developer does,
-# rather than duplicating the installs inline. Only script/ and the
-# dependency manifests are copied first, nothing else, so this layer
-# stays cached until the scripts or the dependencies change — bootstrap
-# ends in `go mod download`, which is why there is no separate
-# invocation of it here.
+# Install development prerequisites the same way a developer does. Only
+# script/ and the dependency manifests are copied first, so this layer
+# stays cached until they change. Bootstrap ends in `go mod download`.
 COPY script/ script/
 COPY go.mod go.sum ./
 RUN script/bootstrap
@@ -151,22 +129,17 @@ RUN chown builder:builder /src /go/pkg/mod/cache/download && \
 COPY --chown=builder:builder . .
 USER builder
 
-# Fail the build unless the branch is green. Runs as non-root so the
-# permission-denied test paths are exercised legitimately (root would
-# bypass the chmod(0) the tests rely on).
+# Fail the build unless the branch is green. Runs as non-root: root
+# would bypass the chmod(0) the permission-denied tests rely on.
 #
-# The gate is `make test`, not `make check`: that aggregate runs
-# `script/lint` and `script/fmt-check`, which both run docker, and
-# nothing inside an image build may shell out to docker. Lint and the
-# format checks are not skipped by this — they ran in the lint and
-# markdown stages above, which this stage's COPY --from lines make
-# prerequisites. `make`, not the script directly, because the Makefile's
+# The gate is `make test`, not `make check`, which runs docker; lint and
+# the format checks ran in the lint and markdown stages above. `make`,
+# not the script directly, because the Makefile's
 # `export CGO_ENABLED = 0` applies only to what it invokes.
 #
 # Third per-stage declaration of the gate cache-buster and its check;
-# see the lint stage above for why one is not enough. It is placed after
-# USER so the drop to the unprivileged user still happens before the
-# checks run.
+# see the lint stage above. It is placed after USER so the drop to the
+# unprivileged user still happens before the checks run.
 ARG CHECK_EPOCH
 RUN if [ -z "${CHECK_EPOCH}" ]; then \
         echo "CHECK_EPOCH is unset; build via script/cibuild or script/docker" >&2; \