.dockerignore

@@ -1,9 +1,75 @@
-# .git is sent, without its config: the builder stage derives the version it
+# .dockerignore does NOT use .gitignore semantics. Docker matches with
-# stamps into the binary from it, and `git describe` does not need the config,
+# moby/patternmatcher: filepath.Match plus `**`, so `*` does not cross
-# which can hold a credential (a password in the remote URL, a CI token). No
+# `/` and an unprefixed pattern is anchored at the context root. Every
-# tracked file may be listed here: git in the build would see it as deleted
+# depth-independent pattern therefore needs `**/`, or `config/.env` and
-# and mark the version -dirty, and an excluded .md would silently drop out of
+# `certs/server.key` still ship while this file reads as solved. Only
-# the prettier check in Dockerfile.fmt.
+# genuinely root-anchored entries go unprefixed. Never transplant these
-.git/config
+# into .gitignore, where `**/` is wrong.
-bin/
+#
-node_modules/
+# Matching is case-sensitive, so secrets use character ranges rather
+# than an ALL-CAPS twin, which would still miss `Server.Key`.
+#
+# Extend with this repo's own host-built artifacts, written anchored:
+# `/myapp`, never `**/myapp`, which also matches `cmd/myapp/` and
+# deletes the package directory from the context.
+
+# .git is sent without its config. Without a VERSION build argument the
+# stage that compiles runs `git describe --tags --always` on .git, which
+# does not need .git/config; that file can hold a credential, such as a
+# password in a remote URL or the token the CI checkout step stores there.
+# Each submodule keeps a config with the same exposure in its git directory
+# under .git/modules/, nested again for a submodule's own submodules, or in
+# its own .git directory when it keeps one.
+# KNOWN GAP: a submodule whose name has a `config` segment (`config`,
+# `deploy/config`, `config/lib`) loses its whole git directory, because
+# `**/.git/modules/**/config` also matches that segment's directory
+# under .git/modules/. Go's version stamping then fails the build;
+# nothing leaks. Name such a submodule without that segment:
+# `git submodule add --name`.
+**/.git/config
+**/.git/modules/**/config
+
+# Agent scratch: one full checkout of the repo per in-flight agent.
+# Anchored because it occurs once where agents run at the repo root.
+# KNOWN GAP: a repo running agents in subdirectories still ships
+# `services/api/.claude/` and must add its own anchored entry.
+.claude
+
+# Environment files. `*.env` covers bare `.env` and the `prod.env`
+# convention. Re-include a committed template with a negation if the
+# build needs one: `!docs/example.env`.
+**/*.[eE][nN][vV]
+**/.[eE][nN][vV].*
+**/.[eE][nN][vV][rR][cC]
+
+# Private keys and the bundles carrying them. Public certificates
+# (*.crt, *.cer) are deliberately absent: they are legitimate inputs.
+**/*.[pP][eE][mM]
+**/*.[kK][eE][yY]
+**/*.[pP]12
+**/*.[pP][fF][xX]
+**/[iI][dD]_[rR][sS][aA]
+**/[iI][dD]_[dD][sS][aA]
+**/[iI][dD]_[eE][cC][dD][sS][aA]
+**/[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK]
+**/[iI][dD]_[eE][dD]25519
+**/[iI][dD]_[eE][dD]25519_[sS][kK]
+
+# Dependencies: restored inside the image, never copied in.
+**/node_modules
+
+# OS metadata.
+**/.DS_Store
+**/Thumbs.db
+
+# Editor state: never a build input, and it churns COPY.
+**/*.swp
+**/*.swo
+**/*~
+**/*.bak
+**/.idea
+**/.vscode
+**/*.sublime-*
+
+# This repository's host-built artifacts: `make build` writes bin/.
+/bin

.editorconfig

@@ -10,3 +10,6 @@ insert_final_newline = true
 
 [Makefile]
 indent_style = tab
+
+[*.go]
+indent_style = tab

.gitea/workflows/check.yml

@@ -9,7 +9,7 @@ jobs:
     check:
         runs-on: ubuntu-latest
         steps:
-            # actions/checkout v4.2.2, 2026-02-28
+            # actions/checkout v4.2.2, 2026-02-22
             - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
               # script/cibuild needs no token, so none is left in .git/config.
               with:

.gitignore

@@ -1,7 +1,57 @@
-bin/
+# OS
+.DS_Store
+Thumbs.db
+
+# Editors
+*.swp
+*.swo
+*~
+*.bak
+.idea/
+.vscode/
+*.sublime-*
+
+# Agent scratch (worktrees of this repo, created and destroyed by
+# in-flight tooling). Unanchored: .gitignore patterns already match at
+# every depth, so no prefix is wanted here. This is not a .dockerignore
+# entry and must not be given a `**/` prefix on the way into one.
+.claude/
+
+# Node
 node_modules/
+
+# Secrets. Unanchored like every entry above, so each matches at every
+# depth. Matching is case-sensitive on Linux, so names use character
+# ranges rather than a lowercase form that misses `Server.Key`.
+
+# Environment files. `*.env` covers bare `.env` and the `prod.env`
+# convention. Only the templates `example.env` and `sample.env` are
+# re-included below. A repository that commits any other template adds
+# its own negation after these lines, for example `!.env.example`.
+*.[eE][nN][vV]
+.[eE][nN][vV].*
+.[eE][nN][vV][rR][cC]
+!example.env
+!sample.env
+
+# Private keys and the bundles carrying them.
+*.[pP][eE][mM]
+*.[kK][eE][yY]
+*.[pP]12
+*.[pP][fF][xX]
+[iI][dD]_[rR][sS][aA]
+[iI][dD]_[dD][sS][aA]
+[iI][dD]_[eE][cC][dD][sS][aA]
+[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK]
+[iI][dD]_[eE][dD]25519
+[iI][dD]_[eE][dD]25519_[sS][kK]
+
+# This repository's own entries, kept after the canonical content above.
+*.log
+*.out
+*.test
+bin/
 vendor/
 data/
-.env
 *.exe
 /dnswatcher

.golangci.yml

@@ -17,6 +17,7 @@ linters:
   disable:
     # Genuinely incompatible with project patterns
     - exhaustruct      # Requires all struct fields
+    - exhaustruct_v5   # Requires all struct fields (successor to exhaustruct)
     - godot            # Requires comments to end with periods
     - wrapcheck        # Too verbose for internal packages
     - varnamelen       # Short names like db, id are idiomatic Go

.prettierignore

@@ -1,5 +1,2 @@
-bin/
-data/
 node_modules/
-.claude/
+yarn.lock
-static/css/tailwind.min.css

Dockerfile

@@ -1,68 +1,102 @@
-# Lint stage - fast feedback on lint issues, before the build starts.
+# Lint phase, built alone by script/lint. The linter is invoked directly
-# The linter is invoked directly rather than through `make lint`: that
+# rather than through `make lint`, which is itself a docker build and
-# target shells out to `docker build -f Dockerfile.lint`, and there is
+# would recurse into a daemon that does not exist in a build step.
-# no docker daemon inside a docker build. For the same reason this stage
+# golangci/golangci-lint:v2.14.0 (Debian-based), 2026-10-06
-# runs only the Go half of `make fmt-check`; script/cibuild runs the
+FROM golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f AS lint
-# markdown half after this build.
-# script/cibuild and script/docker name this stage in --no-cache-filter.
-# golangci/golangci-lint:v2.12.2 (Debian-based), 2026-08-10
-FROM golangci/golangci-lint:v2.12.2@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240 AS lint
-
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
-
 COPY . .
-
-RUN script/fmt-check-go
 RUN golangci-lint run --config .golangci.yml ./...
 
-# Build stage
+# Test phase, built alone by script/test. -race needs cgo and so a C
-# script/cibuild and script/docker name this stage in --no-cache-filter.
+# compiler, which the Debian Go image ships and the alpine one does not.
-# golang 1.25-alpine, 2026-02-28
+# The tests query live DNS (TESTING.md), so this step needs the network.
-FROM golang@sha256:f6751d823c26342f9506c03797d2527668d095b0a15f1862cddb4d927a7a4ced AS builder
+# -count=1 keeps Go's test result cache out of both runs, as TESTING.md
-
+# requires. -timeout 90s is a backstop above the 60-second cap on the
-RUN apk add --no-cache git make gcc musl-dev binutils-gold
+# suite. The rerun with -v only shows details: the build fails however
-
+# it ends, because the first run already failed.
-# A build context sent as a tar archive keeps its files' owners, and git
+# golang 1.25.7-trixie, 2026-10-06
-# refuses to read a checkout owned by another user. Trust this one
+FROM golang@sha256:2b174ffcf56c7ad0c47d30d2630693265639ddf2a5141149c2da34db921791b4 AS test
-# whoever owns it.
+# The file permission tests skip themselves as root, so the tests run as
-RUN git config --system --add safe.directory /src
+# an ordinary user, whose home directory holds Go's build cache.
-
+RUN useradd --create-home tester
-# Force BuildKit to run the lint stage before proceeding
+USER tester
-COPY --from=lint /src/go.sum /dev/null
-
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
+COPY . .
+RUN go test -count=1 -race -timeout 90s -cover ./... || \
+    { echo "--- Rerunning with -v for details ---"; \
+      go test -count=1 -race -timeout 90s -v ./...; exit 1; }
 
+# Markdown formatting with prettier, at the version package.json and
+# yarn.lock pin, so it is never installed on the host. script/fmt-check
+# builds the fmt-check stage and script/fmt the fmt-out stage; the image
+# does not depend on any of these stages, so a plain `docker build .`
+# skips them.
+# node:22-bookworm-slim, 2026-09-05
+FROM node@sha256:83f487e0a63425e5b4d146fb5e5be574bcbe1b7b843d3ebafdd95eaf7767a7e5 AS nodedeps
+# prettier lives outside /src, so the COPY of the repo cannot overwrite
+# it and node_modules is not in the tree prettier walks.
+WORKDIR /tools
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile --non-interactive --no-progress
+ENV PATH="/tools/node_modules/.bin:${PATH}"
+WORKDIR /src
+
+# --config rather than discovery: a missing .prettierrc is then an error
+# instead of prettier's defaults, under which every wrap passes.
+# --no-editorconfig so .prettierrc alone sets the style.
+FROM nodedeps AS fmt-check
+COPY . .
+RUN prettier --config .prettierrc --no-editorconfig --check "**/*.md"
+
+# Only the markdown is copied out, with its paths, so the export cannot
+# put anything else back over the working tree.
+FROM nodedeps AS fmt
+COPY . .
+RUN prettier --config .prettierrc --no-editorconfig --write "**/*.md" && \
+    mkdir -p /out && \
+    find . -name '*.md' -type f -exec cp --parents '{}' /out/ ';'
+
+FROM scratch AS fmt-out
+COPY --from=fmt /out/ /
+
+# Build stage. Nothing is wanted from the lint and test phases; the
+# copies are what make BuildKit build them first, so this stage cannot
+# run unless lint and test passed.
+# golang 1.25-alpine, 2026-02-28
+FROM golang@sha256:f6751d823c26342f9506c03797d2527668d095b0a15f1862cddb4d927a7a4ced AS builder
+COPY --from=lint /src/go.sum /dev/null
+COPY --from=test /src/go.sum /dev/null
+RUN apk add --no-cache git
+# A tar-stream context keeps the sender's file owners, which git refuses.
+RUN git config --system --add safe.directory /src
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
 COPY . .
 
-# Run the tests - build fails if any test fails
+# The VERSION build arg when one is given (script/docker and
-RUN make test
+# script/cibuild pass one), otherwise `git describe --tags --always` on
-
+# the .git in the build context. With .git present, a version that is
-# Version stamped into the binary: the VERSION build arg when one is
+# still empty, dev or unknown fails the build: git is missing or could
-# given and not empty (script/docker passes one), otherwise what
+# not read the checkout.
-# `git describe` says of the .git in the build context, so a plain
-# `docker build .` of a clone stamps its tag or short commit. The build
-# arg reaches make through the environment.
 ARG VERSION
-
+RUN VERSION="${VERSION:-$(git describe --tags --always)}"; \
-# A context that carries .git, as a directory or as a file, must yield a
-# real version: one that is empty, `dev` or `unknown` cannot be traced
-# back to a commit.
-RUN version="$(make version)"; \
     if [ -e .git ]; then \
-        case "$version" in \
+        case "$VERSION" in ""|dev|unknown) \
-            "" | dev | unknown) \
+            echo "version is '$VERSION' although .git is present" >&2; \
-                echo "version is \"$version\" although the build context carries .git" >&2; \
+            exit 1 ;; \
-                exit 1 ;; \
         esac; \
-    fi
+    fi; \
+    CGO_ENABLED=0 go build -trimpath \
+        -ldflags="-s -w -X main.Version=${VERSION}" \
+        -o /src/bin/dnswatcher ./cmd/dnswatcher/
 
-RUN make build
+# Runtime stage, and the last one: a plain `docker build .` builds this
-
+# stage's chain and nothing else.
-# Runtime stage
 # alpine 3.21, 2026-02-28
 FROM alpine@sha256:c3f8e73fdb79deaebaa2037150150191b9dcbfba68b4a46d70103204c53f4709
 

Dockerfile.fmt

@@ -1,54 +0,0 @@
-# prettier over the markdown, in a container, so it is never installed
-# on the host. script/fmt-check-markdown builds the fmt-check stage;
-# script/fmt builds fmt-out and takes the formatted files back.
-
-# node:22-bookworm-slim, 2026-09-05
-FROM node:22-bookworm-slim@sha256:83f487e0a63425e5b4d146fb5e5be574bcbe1b7b843d3ebafdd95eaf7767a7e5 AS nodedeps
-
-# prettier lives outside /src so that a `COPY . .` of the repo cannot
-# overwrite it, and so that node_modules never appears in the tree
-# prettier is about to walk.
-WORKDIR /tools
-
-# package.json pins the version and yarn.lock pins the bytes:
-# --frozen-lockfile installs exactly the lockfile's resolution and fails
-# if package.json disagrees with it, so the tool cannot float between
-# runs. yarn is the one in the image above.
-COPY package.json yarn.lock ./
-RUN yarn install --frozen-lockfile --non-interactive --no-progress
-
-ENV PATH="/tools/node_modules/.bin:${PATH}"
-
-WORKDIR /src
-
-# Read-only markdown check. Must match $stage in
-# script/fmt-check-markdown.
-FROM nodedeps AS fmt-check
-
-COPY . .
-
-# --config, not discovery: a .prettierrc that failed to arrive would
-# otherwise leave prettier on its defaults, where proseWrap is "preserve"
-# and every wrap this check exists to enforce passes. Missing the file is
-# a hard error instead. --no-editorconfig so that .prettierrc alone sets
-# the style.
-RUN prettier --config .prettierrc --no-editorconfig --check "**/*.md"
-
-# Write path. Not a check: script/fmt builds this and takes the files.
-FROM nodedeps AS fmt
-
-COPY . .
-
-RUN prettier --config .prettierrc --no-editorconfig --write "**/*.md"
-
-# Only the markdown leaves, with its paths intact, so that the export
-# below cannot put anything else back over the caller's working tree.
-RUN mkdir -p /out && cd /src && \
-    find . -name '*.md' -type f -exec cp --parents '{}' /out/ ';'
-
-# Export target: `docker build --target fmt-out --output type=local`
-# writes /out's tree into a directory on the client, which is how
-# script/fmt gets formatted markdown back without a bind mount.
-# Must match $stage in script/fmt.
-FROM scratch AS fmt-out
-COPY --from=fmt /out/ /

Dockerfile.lint

@@ -1,29 +0,0 @@
-# Lint-only image: used by script/lint. golangci-lint is never run on
-# the host — the repo is COPYed into the build context and the linter
-# runs as a build step, so a successful build IS a clean lint. This
-# also works where the docker daemon is remote and bind mounts are
-# impossible.
-#
-# `golangci-lint config verify` is deliberately NOT run here: it
-# fetches its JSON schema over a live, unpinned HTTPS call, which would
-# make linting network-dependent and defeat hash-pinning. The cost of
-# that: unknown top-level keys in .golangci.yml are silently ignored,
-# so a mistyped or wrong-schema key lints clean while applying nothing.
-#
-# golangci/golangci-lint:v2.12.2 (Debian-based), 2026-08-10
-FROM golangci/golangci-lint:v2.12.2@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240 AS deps
-
-WORKDIR /src
-
-# Dependencies first, so this stage stays cached across lint runs.
-COPY go.mod go.sum ./
-RUN go mod download
-
-# Everything below is invalidated on every run by the
-# --no-cache-filter=lint that script/lint passes: caching is explicitly
-# waived for linting, and a cached build lints nothing.
-FROM deps AS lint
-
-COPY . .
-
-RUN golangci-lint run --config .golangci.yml ./...

Makefile

@@ -2,9 +2,9 @@
 
 BINARY := dnswatcher
 # VERSION given on the command line (`make build VERSION=...`) or in the
-# environment, which is how the Dockerfile's VERSION build arg arrives,
+# environment wins over what `git describe` says of this checkout. An
-# wins over what `git describe` says of this checkout. An empty one counts
+# empty one counts as not given; `override` is what replaces an empty
-# as not given; `override` is what replaces an empty command-line value.
+# command-line value.
 ifeq ($(VERSION),)
 override VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
 endif
@@ -25,7 +25,7 @@ setup:
 build:
 	go build -ldflags "$(LDFLAGS)" -o bin/$(BINARY) ./cmd/dnswatcher
 
-# Prints the version `make build` stamps; the Dockerfile checks it.
+# Prints the version `make build` stamps.
 version:
 	@echo "$(VERSION)"
 

README.md

@@ -656,48 +656,42 @@ provide:
 - `script/setup` — make a fresh clone ready for development: bootstrap plus the
   git pre-commit hook
 - `script/projectname` — print the project name (used for the Docker image tag)
-- `script/test` — run the test suite (race detector, coverage). Caching is
+- `script/test` — run the test suite (race detector, coverage) by building the
-  waived for testing, exactly as it is for linting: `-count=1` forces every
+  `Dockerfile`'s test phase, which queries live DNS. `-count=1` keeps Go's test
-  invocation to execute, because the suite queries live DNS and a cached pass
+  result cache out. Failures are rerun with `-v` automatically, and the build
-  queries nothing. Failures are rerun with `-v` automatically, and the build
   fails even if that rerun passes.
-- `script/lint` — run golangci-lint, always inside Docker: it builds
+- `script/lint` — run golangci-lint by building the `Dockerfile`'s lint phase,
-  `Dockerfile.lint`, which COPYs the repo into the digest-pinned `golangci-lint`
+  on the digest-pinned `golangci-lint` image, so a successful build is a clean
-  image and lints as a build step, so a successful build is a clean lint. The
+  lint. The linter is never installed or run on the host, and Docker is the only
-  linter is never installed or run on the host, and Docker is the only
+  prerequisite.
-  prerequisite. Caching is waived for linting: the lint stage is forced to
-  execute on every run with `--no-cache-filter`, because a cached build lints
-  nothing.
 - `script/fmt` — format all code (gofmt -s, goimports) and all Markdown
   (prettier). goimports runs with `go run` at a pinned commit, never from your
-  `PATH`. prettier runs inside Docker, built from `Dockerfile.fmt` on a
+  `PATH`. prettier runs inside Docker, in a stage of the `Dockerfile` on a
   digest-pinned node image, at the version pinned by `package.json` and
   `yarn.lock`; it is never installed on the host.
 - `script/fmt-check` — check formatting (read-only) with the same tools, failing
-  on any file `script/fmt` would change. It runs the two scripts below.
+  on any file `script/fmt` would change: gofmt and goimports on the host,
-- `script/fmt-check-go` — the gofmt and goimports half, on the host. The
+  prettier inside Docker
-  `Dockerfile` lint stage runs it.
-- `script/fmt-check-markdown` — the prettier half, inside Docker, forced to
-  execute on every run with `--no-cache-filter`
 - `script/check` — run test, lint, and fmt-check
 - `script/docker` — build the Docker image tagged via `script/projectname`, with
-  `--no-cache-filter=lint,builder` so the lint stage and the builder stage,
+  the version from `git describe` passed as `--build-arg VERSION`
-  which runs the tests, run on every invocation, and with the version from
+- `script/cibuild` — CI entrypoint: `script/bootstrap`, then `script/check`,
-  `git describe` passed as `--build-arg VERSION`
+  then the image build `script/docker` does, which runs the lint and test phases
-- `script/cibuild` — CI entrypoint: `docker build` with
+  again
-  `--no-cache-filter=lint,builder`, so the lint stage and the builder stage,
-  which runs the tests, run on every invocation, because a cached build lints
-  nothing and queries no DNS; then `script/fmt-check-markdown`
 - `script/precommit` — run by the git pre-commit hook; `go mod tidy` guard, then
   `script/check`
 - `script/install-precommit` — install the git pre-commit hook
 
+Linting and testing are phases of the `Dockerfile`, and the image is built only
+when both pass. Every `docker build` in `script/` passes `--no-cache`, because a
+cached build lints nothing and queries no DNS.
+
 ## Building
 
 ```sh
 make build      # Build binary to bin/dnswatcher
 make version    # Print the version make build stamps
-make test       # Run tests with race detector
+make test       # Run tests with race detector in Docker (requires docker)
 make lint       # Run golangci-lint in Docker (requires docker)
 make fmt        # Format code and Markdown (requires docker)
 make check      # Run all checks (test, lint, fmt-check)
@@ -712,21 +706,20 @@ the environment, otherwise from `git describe --tags --always --dirty`, and
 `dev` without git metadata. An empty `VERSION` counts as not given. The version
 appears in the startup log and in the health check response.
 
-The image takes it the same way, from the `.git` the build context carries, so a
+The image takes it from `git describe --tags --always` on the `.git` the build
-plain `docker build .` of a clone stamps the commit it was built from; a clone
+context carries, so a plain `docker build .` of a clone stamps the commit it was
-without tags stamps the short commit. A clone made with `--depth 1` carries at
+built from; a clone without tags stamps the short commit. A clone made with
-most a tag on its own commit, so such a clone of an untagged commit stamps the
+`--depth 1` carries at most a tag on its own commit, so such a clone of an
-short commit. In a build from a directory, `.dockerignore` keeps out
+untagged commit stamps the short commit. In a build from a directory,
-`.git/config`, which `git describe` does not need and which can hold a
+`.dockerignore` keeps out `.git/config` and every submodule's git config, which
-credential. Docker does not apply `.dockerignore` to a context sent as a tar
+`git describe` does not need and which can hold a credential. Docker does not
-archive, as upaas sends it, so that context carries `.git/config` into the
+apply `.dockerignore` to a context sent as a tar archive, as upaas sends it, so
-build. It also keeps its files' owners, so git in the build trusts the checkout
+that context carries `.git/config` into the build. It also keeps its files'
-whoever owns it. A non-empty `--build-arg VERSION=...` takes precedence;
+owners, so git in the build trusts the checkout whoever owns it. A non-empty
-`make docker` passes the version `git describe` gives on the host. The build
+`--build-arg VERSION=...` takes precedence; `make docker` passes the version
-fails when the context carries `.git`, as a directory or as a file, and the
+`git describe` gives on the host. The build fails when the context carries
-version comes out empty, `dev` or `unknown`. `.dockerignore` must list no
+`.git`, as a directory or as a file, and the version comes out empty, `dev` or
-tracked file: git in the build would see it as deleted and mark the version
+`unknown`.
-`-dirty`.
 
 ---
 

REPO_POLICIES.md

@@ -1,6 +1,6 @@
 ---
 title: Repository Policies
-last_modified: 2026-08-07
+last_modified: 2026-10-04
 ---
 
 This document covers repository structure, tooling, and workflow standards. Code
@@ -60,17 +60,28 @@ style conventions are in separate documents:
   prerequisite since nvm requires bash. yarn is then pinned via
   `corepack prepare yarn@<version> --activate`. Never install "latest" or "lts";
   always exact versions. `script/cibuild` runs the CI build: it changes to the
-  repo root and runs `docker build .`; the Gitea workflow calls it. Four further
+  repo root, runs `script/bootstrap`, runs `script/check`, and builds the image
-  scripts are our own extensions to the standard: `script/check` runs
+  with the version; the Gitea workflow calls it. **`script/cibuild` runs
-  `script/test`, `script/lint`, and `script/fmt-check`; `script/precommit` is
+  `script/bootstrap` first**, because the workflow checks out the repo and runs
-  what the git pre-commit hook runs, and it calls `script/check`;
+  nothing else, while `script/fmt-check` runs the formatter on the host: on a
-  `script/install-precommit` installs the git pre-commit hook (the `make hooks`
+  pristine checkout with nothing installed the run dies there, after the
-  target shims to it); and `script/projectname` (literally that filename) simply
+  containerised gates have passed. **The bootstrap alone is not enough**:
-  outputs the project's name. Scripts that need the name call
+  `script/bootstrap` installs node and yarn under nvm and leaves neither on the
-  `script/projectname` — e.g. `script/docker` assembles its image tag from it —
+  `PATH` of the shell that called it, so a bare `yarn` still exits 127. The host
-  so those scripts stay byte-identical across all repos. Repo-type-specific
+  entrypoints that need yarn — `script/fmt` and `script/fmt-check` — therefore
-  pre-commit extras (e.g. `go mod tidy` verification in Go repos) belong in
+  source nvm for the pinned node version before invoking it, exactly as
-  `script/precommit`, not in the hook itself. Model scripts are at
+  `script/bootstrap`'s own install step does. A runner carrying nothing but
+  docker and git then gets through `script/check`. Four further scripts are our
+  own extensions to the standard: `script/check` runs `script/test`,
+  `script/lint` and `script/fmt-check`; `script/precommit` is what the git
+  pre-commit hook runs, and it calls `script/check`; `script/install-precommit`
+  installs the git pre-commit hook (the `make hooks` target shims to it); and
+  `script/projectname` (literally that filename) simply outputs the project's
+  name. Scripts that need the name call `script/projectname` — e.g.
+  `script/docker` assembles its image tag from it — so those scripts stay
+  byte-identical across all repos. Repo-type-specific pre-commit extras (e.g.
+  `go mod tidy` verification in Go repos) belong in `script/precommit`, not in
+  the hook itself. Model scripts are at
   `https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`. The README
   must document the provided scripts in an **Entrypoints** section (see the
   README requirements below).
@@ -89,87 +100,198 @@ style conventions are in separate documents:
   contributor should be able to understand the entire development workflow by
   reading the Makefile.
 
-- Every repo should have a `Dockerfile`. All Dockerfiles must run `make check`
+- Every repo should have a `Dockerfile`, and it carries the repo's gates: a
-  as a build step so the build fails if the branch is not green. For non-server
+  `lint` phase and a `test` phase, with the final stage depending on both so the
-  repos, the Dockerfile should bring up a development environment and run
+  image cannot be built unless they pass. For non-server repos the final stage
-  `make check`. For server repos, `make check` should run as an early build
+  brings up a development environment; for server repos it is the runtime image.
-  stage before the final image is assembled. Dockerfiles install development
+  The gate phases and the build stage start from their pinned base images and
-  prerequisites by running `script/bootstrap` rather than duplicating installs
+  install what those images lack either inline, as the canonical Go `Dockerfile`
-  inline; COPY `script/` and the dependency manifests (`package.json` +
+  below does for `git`, or by running `script/bootstrap`, as the `prompts`
-  `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it so the bootstrap
+  repo's own `Dockerfile` does for its yarn packages. The development
-  layer stays cached until dependencies change.
+  environment stage installs development prerequisites by running
+  `script/bootstrap` rather than duplicating its installs inline. A stage that
+  runs `script/bootstrap` COPYs `script/` and the dependency manifests
+  (`package.json` + `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it.
 
-- **Dockerfiles must use a separate lint stage for fail-fast feedback.** Go
+- **Linting and testing run in Docker, as phases of the `Dockerfile`.** There is
-  repos use a multistage build where linting runs in an independent stage based
+  no separate lint file. `script/lint` and `script/test` each build one phase
-  on the `golangci/golangci-lint` image (pinned by hash). This stage runs
+  and nothing else:
-  `make fmt-check` and `make lint` before the full build begins. The build stage
-  then declares an explicit dependency on the lint stage via
-  `COPY --from=lint /src/go.sum /dev/null`, which forces BuildKit to complete
-  linting before proceeding to compilation and tests. This ensures lint failures
-  surface in seconds rather than minutes, without blocking on dependency
-  download or compilation in the build stage.
 
-    The standard pattern for a Go repo Dockerfile is:
+    ```sh
+    docker build --no-cache --target lint -t "$(script/projectname)-lint" .
+    docker build --no-cache --target test -t "$(script/projectname)-test" .
+    ```
+
+    **A stage that is not the last one in the file is built only when the final
+    stage's chain depends on it, or when `--target` names it.** That is why the
+    two gates are always invoked by name here, and why the final stage carries a
+    `COPY --from=` of a harmless file from each of them: without that edge a
+    plain `docker build .` builds the last stage alone and exits 0 having linted
+    and tested nothing.
+
+    **Every `docker build` in `script/` is tagged**, here and in
+    `script/cibuild` and `script/docker`. An untagged build leaves a dangling
+    image behind on every invocation, on every developer host and every CI
+    runner; a tagged one replaces the previous image.
+
+    Inside a phase the tool is invoked directly — `golangci-lint`, `go test`,
+    `eslint`, `prettier` — never through `make lint` or `script/test`, which are
+    themselves a `docker build` and would recurse into a daemon that does not
+    exist in a build step. Formatting is the exception and stays on the host:
+    `script/fmt` writes the working tree, and `script/fmt-check` is its
+    read-only twin.
+
+    **No lint verdict may come from a host invocation of the linter.** On a
+    shared host golangci-lint reads a result cache keyed on file content rather
+    than location, so a second checkout of the same content is served the first
+    one's findings, and a host-global lock in `$TMPDIR` makes concurrent runs
+    exit non-zero with `parallel golangci-lint is running` — a status a caller
+    cannot tell from real findings. Both have produced wrong verdicts in this
+    org, in both directions. A container has its own cache, its own `TMPDIR` and
+    a digest-pinned binary, so neither is reachable.
+
+- **Any build that runs checks is built with `--no-cache`.** Docker invalidates
+  a `COPY` layer only when the copied content changes, so on an unchanged tree
+  the check `RUN` is served from cache, nothing executes, and the build still
+  exits 0. Every `docker build` in `script/` therefore passes `--no-cache`:
+  `script/lint`, `script/test`, `script/cibuild` and `script/docker` are the
+  four, and there is no fifth — `script/check` runs the two gate phases and
+  `script/fmt-check`, and builds no image of its own. A bare `docker build .` is
+  not evidence that anything ran: a sub-second build reporting success is a
+  cache hit, not a result. Never invalidate by pruning — `docker builder prune`
+  and friends destroy a build cache shared with every other build on the host.
+  When a check is added or changed, prove it works by planting a defect it must
+  catch and watching the run fail on it, then revert the defect. A green run
+  alone shows neither that the check ran nor that it covers what it should.
+
+- **The gate phases are separate stages, and the build stage depends on both.**
+  The lint phase is based on the `golangci/golangci-lint` image (pinned by
+  hash), so lint failures surface in seconds rather than after a full compile,
+  and the test phase is based on the Debian Go image. The canonical Go repo
+  `Dockerfile`:
 
     ```dockerfile
-    # Lint stage — fast feedback on formatting and lint issues
+    # Lint phase
     # golangci/golangci-lint:v2.x.x, YYYY-MM-DD
     FROM golangci/golangci-lint@sha256:... AS lint
     WORKDIR /src
     COPY go.mod go.sum ./
     RUN go mod download
     COPY . .
-    RUN make fmt-check
+    RUN golangci-lint run --config .golangci.yml ./...
-    RUN make lint
 
-    # Build stage
+    # Test phase. -race needs cgo and so a C compiler, which the Debian Go
-    # golang:1.x-alpine, YYYY-MM-DD
+    # image ships and the alpine one does not.
-    FROM golang@sha256:... AS builder
+    # golang:1.x, YYYY-MM-DD
+    FROM golang@sha256:... AS test
     WORKDIR /src
-
-    # Force BuildKit to run the lint stage before proceeding
-    COPY --from=lint /src/go.sum /dev/null
-
     COPY go.mod go.sum ./
     RUN go mod download
     COPY . .
-    RUN make test
+    RUN go test -timeout 90s -race -cover ./... || \
+        { echo "--- Rerunning with -v for details ---"; \
+          go test -timeout 90s -race -v ./...; exit 1; }
 
-    ARG VERSION=dev
+    # Build stage. Nothing is wanted from either phase above; the copies
-    RUN CGO_ENABLED=0 go build -trimpath \
+    # are what make BuildKit build them first, so this stage cannot run
-        -ldflags="-s -w -X main.Version=${VERSION}" \
+    # unless lint and test passed.
-        -o /app ./cmd/app/
+    # golang:1.x-alpine, YYYY-MM-DD
+    FROM golang@sha256:... AS builder
+    COPY --from=lint /src/go.sum /dev/null
+    COPY --from=test /src/go.sum /dev/null
+    RUN apk add --no-cache git
+    # A tar-stream context keeps the sender's file owners, which git refuses.
+    RUN git config --system --add safe.directory /src
+    WORKDIR /src
+    COPY go.mod go.sum ./
+    RUN go mod download
+    COPY . .
 
-    # Runtime stage
+    # The VERSION build arg when one is given, otherwise
+    # `git describe --tags --always` on the .git in the build context. With
+    # .git present, a version that is still empty, dev or unknown fails the
+    # build: git is missing or could not read the checkout.
+    ARG VERSION
+    RUN VERSION="${VERSION:-$(git describe --tags --always)}"; \
+        if [ -e .git ]; then \
+            case "$VERSION" in ""|dev|unknown) \
+                echo "version is '$VERSION' although .git is present" >&2; \
+                exit 1 ;; \
+            esac; \
+        fi; \
+        CGO_ENABLED=0 go build -trimpath \
+            -ldflags="-s -w -X main.Version=${VERSION}" \
+            -o /app ./cmd/app/
+
+    # Runtime stage, and the last one
     FROM alpine@sha256:...
     COPY --from=builder /app /usr/local/bin/app
     ENTRYPOINT ["app"]
     ```
 
     Key points:
-    - The lint stage uses the `golangci/golangci-lint` image directly (it
+    - The lint phase uses the `golangci/golangci-lint` image directly (it has
-      includes both Go and the linter), so there is no need to install the
+      both Go and the linter), so nothing needs installing.
-      linter separately.
+    - `COPY --from=<phase> /src/go.sum /dev/null` is a no-op copy whose only
-    - `COPY --from=lint /src/go.sum /dev/null` is a no-op file copy that creates
+      purpose is the ordering edge. BuildKit runs stages in parallel by default,
-      a stage dependency. BuildKit runs stages in parallel by default; without
+      and a stage nothing depends on is not built at all, so without these two
-      this line, the build stage would not wait for lint to finish and a lint
+      lines a red gate would not fail the build.
-      failure might not fail the overall build.
+    - Keep the runtime stage last, and if you add a stage after it, give it the
+      same two copies. A plain `docker build .` builds the last stage's chain
+      and nothing else.
     - If the project uses `//go:embed` directives that reference build artifacts
-      (e.g. a web frontend compiled in a separate stage), the lint stage must
+      (e.g. a web frontend compiled in a separate stage), the lint phase must
       create placeholder files so the embed directives resolve. Example:
       `RUN mkdir -p web/dist && touch web/dist/index.html web/dist/style.css`.
-      The lint stage should not depend on the actual build output — it exists to
+    - If the project requires CGO or system libraries for linting, install them
-      fail fast.
+      in the lint phase. The `golangci/golangci-lint` image is Debian-based and
-    - If the project requires CGO or system libraries for linting (e.g.
+      has no `apk`, so install with `apt-get` under the Debian package name
-      `vips-dev`), install them in the lint stage with `apk add`.
+      (`libvips-dev`, where alpine says `vips-dev`), and delete the package
-    - The build stage runs `make test` after compilation setup. Tests run in the
+      lists in the same `RUN`, so the layer does not keep them:
-      build stage, not the lint stage, because they may require compiled
+
-      artifacts or heavier dependencies.
+        ```dockerfile
+        RUN apt-get update \
+            && apt-get install -y --no-install-recommends libvips-dev \
+            && rm -rf /var/lib/apt/lists/*
+        ```
+
+    - `.dockerignore` lets `.git` into the build context. It keeps out every git
+      `config` at any depth (`**/.git/config`, `**/.git/modules/**/config`): the
+      repository's own, each submodule's under `.git/modules/`, and that of a
+      submodule keeping its own `.git` directory. `git describe` does not need
+      them, and each can hold a credential: a password in a remote URL, or the
+      token the CI checkout step stores there. A submodule whose name has a
+      `config` segment (`config`, `deploy/config`, `config/lib`) loses its whole
+      git directory to `**/.git/modules/**/config`, and Go's version stamping
+      then fails the build: give it a name without that segment
+      (`git submodule add --name`). The stage that compiles has `git` (the
+      Debian Go image has it; an alpine one needs `apk add --no-cache git`) and
+      takes the version from the `VERSION` build argument when one is given,
+      otherwise from `git describe --tags --always`. That gives the tag on a
+      tagged commit; on a later commit, the tag, the number of commits since it
+      and the short commit (`v1.2.3-4-gabc1234`); and the short commit when no
+      tag is reachable. The stage that compiles also marks its working directory
+      safe for git (`git config --system --add safe.directory /src`): a context
+      sent as a tar stream keeps the sender's file owners, and git refuses a
+      checkout owned by another user, so the version would come out empty.
+      `ARG VERSION` has no default, and the build fails if the context carries
+      `.git` and the version still comes out empty, `dev` or `unknown`. A plain
+      `docker build .` with no build arguments must succeed; a Dockerfile that
+      refuses an empty build argument drops that refusal and keeps the argument.
 
 - Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
-  runs `script/cibuild` (which runs `docker build .`) on push. Since the
+  runs `script/cibuild` on push, and checks out the repo as its only other step.
-  Dockerfile already runs `make check`, a successful build implies all checks
+  That script bootstraps, runs the gate phases, and then builds the image, so a
-  pass.
+  successful run means every check passed; a bare `docker build .` does not
+  carry the same guarantee, because its gate phases may come from the cache. The
+  image build is uncached and so runs the gate phases a second time. That is the
+  price of the rule above, and it is worth paying: the image that ships is built
+  from a run of its own gates rather than from a cache entry. A separate
+  workflow limited to `main` by a `branches` list under `on: push` cannot be
+  checked by review: to try a change to it, add the feature branch to that list
+  and push, then remove the branch from the list again before merging. Keep any
+  job in it that publishes behind `if: github.ref_name == 'main'`, so the run
+  from the feature branch publishes nothing.
 
 - Use platform-standard formatters: `black` for Python, `prettier` for
   JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
@@ -193,15 +315,17 @@ style conventions are in separate documents:
   suite that exceeds it fails. Under 20 seconds is the target. A suite between
   20 and 60 seconds is still green, but the overage must be filed as an
   improvement bug against that repo. Add a 90-second timeout to the test
-  invocation in the Makefile (`go test -timeout 90s`). The backstop deliberately
+  invocation (`go test -timeout 90s`). The backstop deliberately sits above the
-  sits above the hard cap so that it catches a genuinely hung test rather than a
+  hard cap so that it catches a genuinely hung test rather than a merely slow
-  merely slow one.
+  one.
 
-- **`make test` should use the conditional verbose rerun pattern.** Run tests
+- **The test command should use the conditional verbose rerun pattern.** Run
-  without `-v` (verbose) first. If tests fail, automatically rerun with `-v` to
+  tests without `-v` (verbose) first. If tests fail, automatically rerun with
-  show full output. This keeps CI logs and `docker build` output clean on
+  `-v` to show full output. This keeps CI logs and `docker build` output clean
-  success (just package/suite summaries) while providing full diagnostic detail
+  on success (just package/suite summaries) while providing full diagnostic
-  on failure (every test case, every assertion). The general shell pattern:
+  detail on failure (every test case, every assertion). The command lives in the
+  `test` phase of the `Dockerfile`, since `script/test` builds that phase; the
+  Makefile form below is the same pattern for any repo-local invocation:
 
     ```makefile
     test:
@@ -214,11 +338,26 @@ style conventions are in separate documents:
 
     ```makefile
     test:
-    	@go test -timeout 90s -race -cover ./... || \
+    	@go test -count=1 -timeout 90s -race -cover ./... || \
     		{ echo "--- Rerunning with -v for details ---"; \
-    		  go test -timeout 90s -race -v ./...; exit 1; }
+    		  go test -count=1 -timeout 90s -race -v ./...; exit 1; }
     ```
 
+    `-count=1` is required on both invocations: it defeats Go's test _result_
+    cache, so neither run can report a stored pass in place of running the
+    tests. It leaves the build cache alone, so it costs the runtime of the suite
+    and no recompilation.
+
+    That cache is Go's own, separate from Docker's layer cache. Go stores a
+    passing result in its cache directory (`GOCACHE`), and when the same tests
+    run again on unchanged code it prints that result, marked `(cached)`,
+    without running them. That matters on a developer's machine, where this
+    target runs and the directory lasts from one run to the next. The `test`
+    phase of the `Dockerfile` needs no `-count=1`: its base image holds no
+    result for this repo's tests and nothing before its `go test` step runs a
+    test, so there is nothing to replay. `--no-cache` (above) is what makes that
+    step run on an unchanged tree.
+
     Python example:
 
     ```makefile
@@ -244,10 +383,84 @@ style conventions are in separate documents:
   must be in `.gitignore`. No exceptions.
 
 - `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
-  editor files (`.swp`, `*~`), language build artifacts, and `node_modules/`.
+  editor files (`.swp`, `*~`), in-repo agent scratch directories (`.claude/`),
-  Fetch the standard `.gitignore` from
+  language build artifacts, and `node_modules/`. Fetch the standard `.gitignore`
-  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up
+  from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when
-  a new repo.
+  setting up a new repo. These patterns are written to `.gitignore`'s own
+  semantics, in which an unanchored pattern already matches at every depth; they
+  are not a `.dockerignore` and must not be transplanted into one unmodified.
+
+- **`.dockerignore` does not use `.gitignore` semantics, and copying patterns
+  across unmodified leaves secrets in the build context.** Docker matches with
+  `moby/patternmatcher`: `filepath.Match` semantics plus a `**` extension, so
+  `*` does not cross `/` and a pattern without a leading `**/` is anchored at
+  the build-context root. A `.dockerignore` listing `.env`, `*.pem` and `*.key`
+  therefore excludes only the copies at the repository root, while `config/.env`
+  and `certs/server.key` still reach the context and can land in an image layer
+  — which is more dangerous than a short file with no secret patterns at all,
+  because it reads as solved and stops anyone looking. Give every
+  depth-independent pattern the `**/` prefix and leave only genuinely
+  root-anchored entries unprefixed: `.claude`, and the repo's own host-built
+  binary, written `/myapp` and never `**/myapp`, which would also match
+  `cmd/myapp/` and delete the package directory from the context. Matching is
+  case-sensitive, and an ALL-CAPS twin per pattern still misses `Server.Key`, so
+  secret names use character ranges — `**/*.[kK][eE][yY]`, `**/*.[pP][eE][mM]`,
+  and likewise for `.envrc` and the extensionless SSH keys. Where such a pattern
+  also catches something the build needs, re-include it with a negation
+  (`!docs/example.env`); deleting the pattern reopens the exposure for every
+  other file it covers. Fetch the standard `.dockerignore` from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` and extend
+  it with the repo's own artifacts.
+
+- **In-repo agent scratch belongs in both files, written to each file's own
+  semantics.** `.claude/` holds one worktree per in-flight agent — an entire
+  additional checkout of the repo — so under `COPY . .` the build context
+  inflates by a multiple of the repo and another session's unreviewed work can
+  be copied into an image layer. In `.gitignore` the entry is `.claude/`,
+  unanchored. In `.dockerignore` it is `.claude`, anchored and with **no** `**/`
+  prefix, because the prefixed form would also delete any nested directory of
+  that name from the build. Anchoring carries a known gap that the canonical
+  `.dockerignore` states in its own comment, since consuming repos receive the
+  file and not the tracker: the directory is created in the agent's working
+  directory, so a repo running agents in subdirectories still ships
+  `services/api/.claude/` and must add its own anchored entry there.
+
+- **A plain `docker build .` of a clone stamps the version that
+  `git describe --tags --always` gives**, derived from the `.git` in the build
+  context as the canonical `Dockerfile` above shows. Without its failure check,
+  a missing `git` or an unreadable checkout would leave `-X main.Version=` empty
+  and the build would still exit 0. `script/docker` and `script/cibuild` pass
+  the version they compute on the host; it takes precedence. They do this
+  byte-identically across repos:
+
+    ```sh
+    # Own line: a failing command substitution inside an argument does not
+    # trip `set -e`, so the inline form degrades to an empty constant.
+    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    [ -n "$version" ] || version="unknown"
+    docker build --no-cache \
+        --build-arg VERSION="$version" \
+        -t "$(script/projectname)" .
+    ```
+
+    `--always` makes an untagged repo yield an abbreviated commit hash rather
+    than failing, and the `[ -n "$version" ]` line is the single place the
+    fallback is applied — a live check that fires on a build from an export with
+    no `.git` and on a repository with no commits yet. Do not fold it into the
+    substitution as `|| echo unknown`, which makes the guard unreachable. The
+    Dockerfile's side is `ARG VERSION` in the stage that compiles, declared
+    there because `ARG` is stage-scoped; passing `VERSION` to a repo whose
+    Dockerfile declares no such `ARG` is ignored and costs nothing, which is why
+    the scripts stay byte-identical. One consequence for CI: the standard
+    checkout action clones shallow and fetches no tags, so a repo that embeds a
+    tag-derived version must set `fetch-depth: 0` on its checkout step.
+
+- **Verify `.dockerignore` by enumerating the image, not by reading the
+  patterns.** Plant files at the root _and_ at least two directories deep, build
+  a probe image that does `COPY . .`, and list what actually landed
+  (`docker run --rm --entrypoint find IMAGE /app`). The `transferring context`
+  size is not a substitute: a nested secret is a few bytes, and BuildKit
+  transfers only the delta from the previous build.
 
 - **No build artifacts in version control.** Code-derived data (compiled
   bundles, minified output, generated assets) must never be committed to the
@@ -263,12 +476,56 @@ style conventions are in separate documents:
 - Make all changes on a feature branch. You can do whatever you want on a
   feature branch.
 
-- `.golangci.yml` is standardized and must _NEVER_ be modified by an agent, only
+- `.golangci.yml` is standardized. The vendored copy in a consuming repo must
-  manually by the user. Fetch from
+  _NEVER_ be modified by an agent: fetch it from
-  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`. The
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml` and keep it
-  canonical golangci-lint version is v2.12.2 (released 2026-05-06), installed
+  byte-identical, so that no repo can quietly loosen its own linting. Linter
-  commit-pinned via
+  configuration changes are made to the canonical copy in the `prompts` repo and
-  `go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@c0d3ddc9cf3faa61a4e378e879ece580256d76e5`.
+  reach consuming repos by re-vendoring; an agent may open a PR against
+  canonical, which only the user merges. One list is exempt from byte-identity,
+  because it cannot be written once for every repo: the `deny` list of the
+  `test-support` depguard rule, where a repo names its own test-support packages
+  by full import path. A repo adds entries there and changes nothing else, and a
+  re-vendor carries its entries forward. The canonical golangci-lint version is
+  v2.14.0 (released 2026-09-24), pinned as the digest of the lint phase's base
+  image
+  (`golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f`,
+  which reports `2.14.0 built with go1.27.0 from 114493f9`). A module's `go`
+  directive must not name a newer Go minor version than the one golangci-lint
+  was built with, or golangci-lint refuses to lint it: this release lints
+  `go 1.27.1` but not `go 1.28`. That digest is the only pin, since no repo
+  installs golangci-lint on the host. A repo sets the lint phase digest to the
+  one named here and re-vendors `.golangci.yml` in the same commit, whichever of
+  the two prompted the change: the canonical copy can name linters that an older
+  golangci-lint rejects, and a newer golangci-lint can add linters that
+  `default: all` switches on until the canonical copy disables them.
+
+- **`script/bootstrap` installs a pinned tool by comparing versions, never by
+  testing presence.** An `if ! command -v <tool>; then install; fi` guard tests
+  `PATH` only, so on an already-provisioned machine the pin is inert and a
+  version bump is a silent no-op — while the Dockerfile, installing into a clean
+  image, gets the pinned version, so a local `make check` and `make docker` can
+  disagree about what the tool even is. The canonical form:
+    - compares the installed version against the pin over the **whole** version
+      token; a parser that stops at the first `-` reports `2.12.2` for a host
+      running `2.12.2-rc1` and skips the install;
+    - treats absent, non-zero, empty or unrecognised `--version` output as a
+      mismatch, so the failure direction is a redundant install and never a
+      skipped one;
+    - after installing, re-resolves the binary the way callers do — `hash -r`,
+      then through `PATH`, not through the directory the installer wrote to —
+      and fails naming the resolved path, since an install that a shadowing
+      binary hides succeeds while changing nothing any caller sees;
+    - is actually called, and prints the version on both success paths: a
+      function defined and never invoked has the same exit status and the same
+      empty output as one that worked.
+
+    Keep it POSIX sh: no arrays, no `[[`, no `grep -P`.
+
+    A Go tool a repo needs on the host is installed with `go install` pinned to
+    a commit hash (`go install <package>@<commit hash>`). It is never tracked as
+    a `go.mod` tool dependency or through a `tools.go` file, either of which
+    pulls the tool's own dependencies into the repo's `go.mod` and `go.sum`.
 
 - When pinning images or packages by hash, add a comment above the reference
   with the version and date (YYYY-MM-DD).
@@ -382,12 +639,14 @@ style conventions are in separate documents:
   settings.
 
 - Avoid putting files in the repo root unless necessary. Root should contain
-  only project-level config files (`README.md`, `Makefile`, `Dockerfile`,
+  only project-level config files (`README.md`, `AGENTS.md`, `Makefile`,
-  `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, and
+  `Dockerfile`, `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`,
-  language-specific config). Everything else goes in a subdirectory. Canonical
+  and language-specific config). Everything else goes in a subdirectory.
-  subdirectory names:
+  Canonical subdirectory names:
     - `bin/` — executable scripts and tools
-    - `cmd/` — Go command entrypoints
+    - `cmd/` — Go command entrypoints; thin only: one `main.go` per binary whose
+      body is a single call into `internal/` or `pkg/`, no project logic in
+      `cmd/`
     - `configs/` — configuration templates and examples
     - `deploy/` — deployment manifests (k8s, compose, terraform)
     - `docs/` — documentation and markdown (README.md stays in root)
@@ -414,3 +673,7 @@ style conventions are in separate documents:
     - Go: `go.mod`, `go.sum`, `.golangci.yml`
     - JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
     - Python: `pyproject.toml`
+
+- Guidance for coding agents lives in one `AGENTS.md` at the repository root. It
+  is never committed under a file or directory named after one agent tool, such
+  as `CLAUDE.md` or `.claude/`, and never split into separate memory files.

TESTING.md

@@ -38,7 +38,7 @@ works correctly in production.
   responses
 - **Do not add `-short` flags** to skip slow tests
 - **Do not increase `-timeout`** to hide hanging queries
-- **Do not remove `-count=1` from `script/test`** — Go's test cache replays a
+- **Do not remove `-count=1` from the test phase of the `Dockerfile`** — Go's
-  previous run's output without querying anything, so a cached pass is not
+  test cache replays a previous run's output without querying anything, so a
-  evidence that live resolution works
+  cached pass is not evidence that live resolution works
 - **Do not modify linter configuration** to suppress findings

TODO.md

@@ -19,6 +19,9 @@ trial run of the finished image: https://git.eeqj.de/sneak/dnswatcher/issues/149
 
 # Completed Steps
 
+- 2026-10-06: canonical files re-fetched from `sneak/prompts` at `dd4027b`; lint
+  and test are phases of the `Dockerfile`, every scripted build uncached (closes
+  #257).
 - 2026-10-05: a name listed in `DNSWATCHER_SKIP_RECORD_NOTIFICATIONS` gets no
   Record Change or Inconsistency notification; a name listed there that is not
   in `DNSWATCHER_TARGETS` stops startup (closes #255).

script/bootstrap

@@ -3,12 +3,12 @@
 # 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.
-# goimports is not installed here: script/fmt and script/fmt-check-go
+# goimports is not installed here: script/fmt and script/fmt-check run
-# run it with `go run` at a pinned commit.
+# it with `go run` at a pinned commit.
 # The linter is NOT installed here: golangci-lint runs via docker only
 # (script/lint), pinned by image digest, so its only prerequisite is a
-# working docker. Nor is prettier: script/fmt and
+# working docker. Nor is prettier: script/fmt and script/fmt-check run
-# script/fmt-check-markdown run it in a container from Dockerfile.fmt.
+# it in a stage of the Dockerfile.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
@@ -67,12 +67,12 @@ main() {
     if missing make; then pkg_install gnumake make make make; fi
     if missing go; then pkg_install go golang go go; fi
 
-    # Linting and the markdown formatter run via docker only. Warn,
+    # Testing, linting and the markdown formatter run via docker only.
-    # don't fail: building and testing work without it.
+    # Warn, don't fail: make build works without it.
     if missing docker; then
         echo "bootstrap: WARNING: docker not found; install it to" \
-            "run make lint, make fmt, make fmt-check, make check" \
+            "run make test, make lint, make fmt, make fmt-check," \
-            "and make docker." >&2
+            "make check and make docker." >&2
     fi
 
     go mod download

script/cibuild

@@ -1,14 +1,10 @@
 #!/bin/sh
-# script/cibuild: run the CI build. The Dockerfile's lint stage runs
+# script/cibuild: run the CI build. It bootstraps first: a CI runner
-# the Go half of make fmt-check and golangci-lint; its builder stage
+# checks out and runs this and nothing else, and script/fmt-check runs
-# runs make test and make build. The markdown half of make fmt-check
+# the formatter on the host, which a pristine checkout cannot do.
-# runs after that build, as its own build of Dockerfile.fmt, because
+# --no-cache for the same reason as script/docker: the gate phases the
-# there is no docker inside a docker build.
+# final stage depends on are RUN steps, and a cached one is a check that
-#
+# did not run.
-# --no-cache-filter=lint,builder runs both stages on every invocation;
-# otherwise an unchanged tree is served from the layer cache and passes
-# without linting or querying live DNS. script/fmt-check-markdown busts
-# its own cache the same way.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -16,8 +12,17 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build --no-cache-filter=lint,builder .
+    "$SCRIPT_DIR/bootstrap"
-    "$SCRIPT_DIR/fmt-check-markdown"
+    "$SCRIPT_DIR/check"
+    # Own line: a failing command substitution inside an argument does
+    # not trip `set -e`, so the inline form degrades silently to an
+    # empty constant. The VERSION build argument takes precedence over
+    # the version a build stage derives from the .git in the context.
+    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    [ -n "$version" ] || version="unknown"
+    docker build --no-cache \
+        --build-arg VERSION="$version" \
+        -t "$("$SCRIPT_DIR/projectname")" .
 }
 
 main "$@"

script/docker

@@ -1,10 +1,8 @@
 #!/bin/sh
 # script/docker: build the Docker image tagged with the project name.
-# The tag comes from script/projectname.
+# Identical in all repos; the tag comes from script/projectname.
-#
+# --no-cache because the gate phases the final stage depends on are RUN
-# --no-cache-filter=lint,builder runs the lint stage and the builder
+# steps, and a cached one is a check that did not run.
-# stage (make test) on every invocation; otherwise an unchanged tree is
-# served from the layer cache without linting or querying live DNS.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -14,11 +12,11 @@ main() {
     cd "$ROOT"
     # Own line: a failing command substitution inside an argument does
     # not trip `set -e`, so the inline form degrades silently to an
-    # empty constant. The VERSION build arg takes precedence over what
+    # empty constant. The VERSION build argument takes precedence over
-    # the build would derive from the .git in its context.
+    # the version a build stage derives from the .git in the context.
     version="$(git describe --tags --always --dirty 2>/dev/null || true)"
     [ -n "$version" ] || version="unknown"
-    docker build --no-cache-filter=lint,builder \
+    docker build --no-cache \
         --build-arg VERSION="$version" \
         -t "$("$SCRIPT_DIR/projectname")" .
 }

script/fmt

@@ -1,6 +1,6 @@
 #!/bin/sh
 # script/fmt: format all files (writes). Go with gofmt and goimports on
-# the host, markdown with the prettier pinned by Dockerfile.fmt.
+# the host, markdown with prettier in the Dockerfile's fmt stage.
 #
 # goimports runs with `go run` at a pinned commit, never from PATH, so
 # every machine formats with the same version and nothing installs it.
@@ -8,21 +8,15 @@
 # The markdown pass is a `docker build --output type=local` rather than a
 # `docker run -v`, so it needs no bind mount and behaves the same against
 # a remote daemon; the formatted documents come back out of the build and
-# are copied over the tree here.
+# are copied over the tree here. --output writes files and makes no
-#
+# image, so there is nothing to tag.
-# Unlike script/fmt-check-markdown this does not bust the cache: it is
-# not a gate, and any edit to a document changes the COPY layer above the
-# prettier step, so a cached result is a result over this exact tree.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
-# goimports v0.42.0, 2026-08-07. Must match script/fmt-check-go.
+# goimports v0.42.0, 2026-08-07. Must match script/fmt-check.
 GOIMPORTS_REF="golang.org/x/tools/cmd/goimports@009367f5c17a8d4c45a961a3a509277190a9a6f0"
 
-# Must match the export stage name in Dockerfile.fmt.
-stage=fmt-out
-
 die() {
     echo "script/fmt: $*" >&2
     exit 1
@@ -36,10 +30,9 @@ main() {
     tmp="$(mktemp -d "${TMPDIR:-/tmp}/dnswatcher-fmt.XXXXXX")"
     trap 'rm -rf "$tmp"' EXIT INT TERM
 
-    docker build \
+    docker build --no-cache \
-        --target "$stage" \
+        --target fmt-out \
-        --output "type=local,dest=$tmp/out" \
+        --output "type=local,dest=$tmp/out" .
-        -f Dockerfile.fmt .
 
     # An empty export means prettier was handed nothing, which must not
     # read as "already formatted".

script/fmt-check

@@ -1,14 +1,37 @@
 #!/bin/sh
 # script/fmt-check: check formatting (read-only). Same tools and scope
-# as script/fmt, but fails instead of writing: the Go on the host, the
+# as script/fmt, but fails instead of writing and names what it would
-# markdown with prettier in a container.
+# change: the Go on the host, the markdown with prettier in the
+# Dockerfile's fmt-check stage.
+#
+# --no-cache because a cached check layer is a check that did not run.
+# The tag makes each build replace the previous image instead of leaving
+# a dangling one behind.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+
+# goimports v0.42.0, 2026-08-07. Must match script/fmt.
+GOIMPORTS_REF="golang.org/x/tools/cmd/goimports@009367f5c17a8d4c45a961a3a509277190a9a6f0"
 
 main() {
-    "$SCRIPT_DIR/fmt-check-go"
+    cd "$ROOT"
-    "$SCRIPT_DIR/fmt-check-markdown"
+    files="$(gofmt -s -l .)"
+    if [ -n "$files" ]; then
+        echo "gofmt: files not formatted:" >&2
+        echo "$files" >&2
+        exit 1
+    fi
+    files="$(go run "$GOIMPORTS_REF" -l .)"
+    if [ -n "$files" ]; then
+        echo "goimports: files not formatted:" >&2
+        echo "$files" >&2
+        exit 1
+    fi
+    docker build --no-cache \
+        --target fmt-check \
+        -t "$("$SCRIPT_DIR/projectname")-fmt-check" .
 }
 
 main "$@"

script/fmt-check-go

@@ -1,31 +0,0 @@
-#!/bin/sh
-# script/fmt-check-go: fail unless every Go source is formatted the way
-# script/fmt would leave it, and name the files that are not. Read-only.
-#
-# Its own script because the Dockerfile's lint stage runs this half
-# alone: there is no docker inside a docker build to run the markdown
-# half in.
-set -eu
-
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
-
-# goimports v0.42.0, 2026-08-07. Must match script/fmt.
-GOIMPORTS_REF="golang.org/x/tools/cmd/goimports@009367f5c17a8d4c45a961a3a509277190a9a6f0"
-
-main() {
-    cd "$ROOT"
-    files="$(gofmt -s -l .)"
-    if [ -n "$files" ]; then
-        echo "gofmt: files not formatted:" >&2
-        echo "$files" >&2
-        exit 1
-    fi
-    files="$(go run "$GOIMPORTS_REF" -l .)"
-    if [ -n "$files" ]; then
-        echo "goimports: files not formatted:" >&2
-        echo "$files" >&2
-        exit 1
-    fi
-}
-
-main "$@"

script/fmt-check-markdown

@@ -1,29 +0,0 @@
-#!/bin/sh
-# script/fmt-check-markdown: fail unless every .md is formatted the way
-# script/fmt would leave it. Read-only.
-#
-# prettier is never installed on the host: it runs in a container built
-# from Dockerfile.fmt, pinned by package.json and yarn.lock.
-# --no-cache-filter is here for the reason script/lint gives: a cached
-# build checks nothing.
-#
-# Its own script because script/cibuild runs this half alone, after the
-# Dockerfile's lint stage has checked the Go.
-set -eu
-
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
-
-# Must match the markdown check stage name in Dockerfile.fmt.
-stage=fmt-check
-
-main() {
-    cd "$ROOT"
-    docker build \
-        --progress=plain \
-        --no-cache-filter="$stage" \
-        --target "$stage" \
-        -f Dockerfile.fmt \
-        .
-}
-
-main "$@"

script/lint

@@ -1,28 +1,23 @@
 #!/bin/sh
-# script/lint: run the linter. golangci-lint is never installed or run
+# script/lint: run the linter. Linting is a phase of the Dockerfile and
-# on the host: it runs via docker only, one way, everywhere. This
+# this builds that phase alone; the linter is never installed or run on
-# builds Dockerfile.lint, which COPYs the repo into the digest-pinned
+# a developer host, where a shared result cache and a host-global lock
-# golangci-lint image and lints as a build step, so a successful build
+# make its answer untrustworthy.
-# means a clean lint.
 #
-# --no-cache-filter=lint forces the lint stage (source copy + linter
+# The phase is not the last stage in the file, so it is built only when
-# run) to execute on every invocation. Without it an unchanged tree
+# --target names it. --no-cache because a cached lint layer is a lint
-# returns success in well under a second having linted nothing. The
+# that did not run. The tag makes each build replace the previous image
-# deps stage (base image + go mod download) stays cached, and no global
+# instead of leaving a dangling one behind.
-# cache invalidation is performed. --progress=plain keeps the linter's
-# own output visible.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build \
+    docker build --no-cache \
-        --progress=plain \
-        --no-cache-filter=lint \
         --target lint \
-        -f Dockerfile.lint \
+        -t "$("$SCRIPT_DIR/projectname")-lint" .
-        .
 }
 
 main "$@"

script/test

@@ -1,35 +1,19 @@
 #!/bin/sh
-# script/test: run the test suite.
+# script/test: run the test suite. Testing is a phase of the Dockerfile
-#
+# and this builds that phase alone, on the same terms as script/lint:
-# -count=1 disables Go's test cache, and is load-bearing here. This
+# --target because a phase that is not the last stage is built only when
-# suite queries live DNS on every run by policy (TESTING.md); a cached
+# named, --no-cache because a cached test layer is a test that did not
-# result is a replay of an earlier run's output with no query made at
+# run, and a tag so each build replaces the previous image.
-# all. On an unchanged tree the whole suite would return success in
-# under a second having resolved nothing, which makes the repeated-run
-# green that is used as evidence for flakiness fixes worthless. Do not
-# remove it.
-#
-# Conditional verbose rerun per REPO_POLICIES.md: run quiet first so
-# CI and docker build logs stay readable, and rerun with -v only on
-# failure. The rerun also carries -count=1 (a cached replay of the
-# failure would show nothing new), and the exit status is forced to 1
-# no matter how the rerun ends: the first failure already proved the
-# suite broken, so a flaky test that passes the second time must not
-# turn the build green.
-#
-# -timeout 90s is a deliberate backstop above the 60s hard cap on
-# suite duration. Do not lower it.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    go test -count=1 -race -timeout 90s -cover ./... || {
+    docker build --no-cache \
-        echo "--- Rerunning with -v for details ---" >&2
+        --target test \
-        go test -count=1 -race -timeout 90s -v ./... || true
+        -t "$("$SCRIPT_DIR/projectname")-test" .
-        exit 1
-    }
 }
 
 main "$@"