Fold the August fleet findings into the policies, or drop them (closes #62)

Two findings from 2026-08-09 were rules a repository must follow that
`prompts/REPO_POLICIES.md` did not yet state, and are now added where a
reader would look: a new or changed check is proven by planting a defect
it must catch; and a change to a separate workflow limited to `main` by
a `branches` list is first run from the feature branch, added to that
list and removed again before merging. The issue records why every
other finding was dropped. The warning against `golangci-lint config
verify` is dropped because sneak ruled on
#40 (2026-08-10) that there is
no config check step and the config is assumed valid; a vendored
`.golangci.yml` stays byte-identical to the canonical copy.

Model: opus-5-5

.dockerignore

@@ -13,9 +13,21 @@
 # `/myapp`, never `**/myapp`, which also matches `cmd/myapp/` and
 # deletes the package directory from the context.
 
-# Excluding .git means `git describe` cannot run in any build stage and
-# fails quietly there; pass the version in with --build-arg VERSION.
-.git
+# .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.
@@ -39,7 +51,9 @@
 **/[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

.gitattributes

@@ -0,0 +1,4 @@
+# Every PR adds an entry at the top of TODO.md's Completed Steps; union keeps
+# both sides instead of conflicting. Git never reports a conflict here: read
+# the merged entries after every merge or rebase.
+TODO.md merge=union

.gitignore

@@ -20,8 +20,28 @@ Thumbs.db
 # Node
 node_modules/
 
-# Environment / secrets
-.env
-.env.*
-*.pem
-*.key
+# 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]

.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

Dockerfile

@@ -52,7 +52,8 @@ RUN script/bootstrap
 
 COPY . .
 
-# The version is computed on the host and passed in, because
-# .dockerignore excludes .git.
-ARG VERSION=dev
+# Nothing here is compiled and a LABEL cannot run git, so the version is
+# the VERSION build argument that script/docker and script/cibuild pass;
+# a plain `docker build .` leaves it empty.
+ARG VERSION
 LABEL org.opencontainers.image.version="${VERSION}"

README.md

@@ -132,8 +132,7 @@ alpine. We provide:
   `script/check`, compute `version` from `git describe`, then
   `docker build --no-cache --build-arg VERSION="$version" -t prompts .` (what CI
   runs; it bootstraps because CI checks out and runs this alone while
-  `script/fmt-check` is native, and the version is computed on the host because
-  `.dockerignore` excludes `.git`)
+  `script/fmt-check` is native)
 - `script/precommit` — run by the git pre-commit hook (our own extension); calls
   `script/check`
 - `script/install-precommit` — installs the git pre-commit hook (our own

TODO.md

@@ -21,6 +21,118 @@ fmt-check, and commit.
 
 # Completed Steps
 
+- 2026-10-04: Went through the fleet findings recorded on 2026-08-09 (issue 62)
+  and added the two rules `REPO_POLICIES.md` did not yet state: a new or changed
+  check is proven by planting a defect it must catch; and a change to a separate
+  workflow limited to `main` is first run from the feature branch, added to that
+  workflow's `branches` list and removed again before merging. The other
+  findings were already stated, replaced by `--no-cache`, about git worktrees,
+  or about how agents work together. The warning against
+  `golangci-lint config verify` is dropped because sneak ruled on
+  https://git.eeqj.de/sneak/prompts/issues/40 (2026-08-10) that there is no
+  config check step and the config is assumed valid; a vendored `.golangci.yml`
+  stays byte-identical to the canonical copy. The issue gives each reason.
+- 2026-10-04: `REPO_POLICIES.md` now says which `Dockerfile` stages run
+  `script/bootstrap` (issue 90). The gate phases and the build stage start from
+  their pinned base images and install what those images lack either inline, as
+  the canonical Go `Dockerfile` does for `git`, or by running
+  `script/bootstrap`, as this repo's own `Dockerfile` does for its yarn
+  packages. The development environment stage, the final stage of a non-server
+  repo, runs `script/bootstrap`. The new repo checklist says the same.
+- 2026-10-04: Added a root `.gitattributes` that merges `TODO.md` with git's
+  union merge (issue 98), so two branches that each add an entry at the top of
+  Completed Steps merge without a conflict. Git now never reports a conflict in
+  `TODO.md`: a real conflict elsewhere keeps both versions of the line, and when
+  two new entries share an identical line, one is inserted into the middle of
+  the other, which a rebase can do to an entry already on `next`. Read the
+  merged entries after every merge or rebase. This applies to this repository
+  only; no canonical file changed.
+- 2026-10-04: The canonical `.dockerignore` now also keeps out the git `config`
+  of a submodule that keeps its own `.git` directory, which still reached the
+  image (issue 88): both git patterns now carry the `**/` prefix. A submodule
+  whose name has a `config` segment (`config`, `deploy/config`, `config/lib`)
+  still loses its whole git directory, so Go's version stamping fails the build;
+  the file records this as a `KNOWN GAP:` with the remedy,
+  `git submodule add --name`. Closing it would take a wildcard re-include, which
+  makes BuildKit walk every excluded directory, such as `node_modules`, on every
+  build. `REPO_POLICIES.md` and both checklists say so in the same words.
+- 2026-10-04: The note under the canonical Go `Dockerfile` example in
+  `REPO_POLICIES.md` now installs lint-phase system libraries with `apt-get`
+  under their Debian package names (issue 83). The `golangci/golangci-lint`
+  image is Debian-based and has no `apk`, so the old `apk add` instruction
+  failed as written. Nothing is pinned or unpinned; that is still open on
+  issue 72.
+- 2026-10-04: Fixed the server lifecycle example in
+  `prompts/GO_HTTP_SERVER_CONVENTIONS.md` (issue 86). Only fx handles SIGINT and
+  SIGTERM, and `Run()` in `main` exits with the shutdown's exit code. A listen
+  error asks fx to shut down with exit code 1 through `fx.Shutdowner`; a Sentry
+  start failure is returned from the server's start hook instead of calling
+  `os.Exit` from a goroutine, so the stop hooks of what had started still run.
+  The server's stop hook shuts the HTTP server down within 5 seconds and fails
+  when requests are still running. A new paragraph says who owns signals and the
+  exit code.
+- 2026-10-04: `REPO_POLICIES.md` now says how a Go tool a repo needs on the host
+  is pinned (issue 37): installed with `go install` pinned to a commit hash,
+  never tracked as a `go.mod` tool dependency or through a `tools.go` file.
+  golangci-lint is unaffected, since no repo installs it on the host.
+- 2026-10-04: The canonical `.gitignore` and `.dockerignore` now also keep out
+  `id_ecdsa_sk` and `id_ed25519_sk`, the private key files `ssh-keygen` writes
+  for keys backed by a hardware security key (issue 81). Their `.pub` halves
+  stay trackable.
+- 2026-10-04: `package.json` now has `"license": "MIT"`, matching `LICENSE`, so
+  yarn no longer prints "No license field" when `script/bootstrap` runs it
+  inside the Docker phases (issue 76). That was the only yarn warning there.
+- 2026-10-04: `REPO_POLICIES.md` now states that guidance for coding agents
+  lives in one `AGENTS.md` at the repository root, never under a file or
+  directory named after one agent tool and never in separate memory files (issue
+  31). This retires the rule, still present in older vendored copies, that kept
+  agent memory as committed files under `.claude/memory/`. `AGENTS.md` joins the
+  list of files allowed in the root, and both checklists say so.
+- 2026-10-04: Rewrote the note under the canonical Go `make test` example in
+  `REPO_POLICIES.md` (issue 77), which still named the cache-busting build
+  argument that `--no-cache` replaced. It now says where Go's test result cache
+  can replay a pass: on a developer's machine, where the Makefile target runs,
+  and not in the `test` phase of the `Dockerfile`, whose base image and earlier
+  steps hold no result for the repo's tests.
+- 2026-10-04: The Makefile examples in the Go styleguide and the HTTP server
+  conventions now fall back to `dev` when `git describe` prints nothing (outside
+  a git checkout, or where git is missing or refuses the checkout), instead of
+  stamping an empty version (issue 74). The canonical `Dockerfile` already fails
+  on a `dev` version when `.git` is in the build context.
+- 2026-10-04: The canonical `.dockerignore` now also keeps out each submodule's
+  `config` (issue 75). A submodule's git directory lives under `.git/modules/`,
+  nested again for its own submodules, and its `config` can hold a credential
+  just like `.git/config`. The pattern `.git/modules/**/config` covers every
+  depth and leaves the top-level `.git` that `git describe` reads untouched.
+  `REPO_POLICIES.md` and both checklists say so in the same words.
+- 2026-10-03: Fixed two defects in the canonical Go `Dockerfile` example (issue
+  73). The test phase now uses the Debian Go image, since `-race` needs cgo and
+  the alpine image has no C compiler, so the phase failed before running a test.
+  The stage that compiles runs `git config --system --add safe.directory /src`,
+  because a context sent as a tar stream keeps the sender's file owners and git
+  refuses that checkout, leaving the version empty. Both checklists state that
+  step in the same words.
+- 2026-10-03: Moved the canonical golangci-lint to v2.14.0, built with go1.27,
+  because v2.12.2 refuses to lint a module whose `go` directive is 1.27 (issue
+  65). Releases from v2.13.0 deprecate `exhaustruct` in favour of
+  `exhaustruct_v5`, which `default: all` switches on, so the canonical
+  `.golangci.yml` now disables `exhaustruct_v5` beside `exhaustruct`. v2.12.2
+  rejects that file, so `REPO_POLICIES.md` and both repo checklists now say a
+  repo sets the lint phase digest and re-vendors `.golangci.yml` in one commit.
+- 2026-10-03: Brought the canonical `.gitignore` level with `.dockerignore` on
+  secrets (issue 38): it now also ignores `prod.env`-style `*.env` files,
+  `.envrc`, `*.p12`, `*.pfx` and the extensionless SSH private keys, written to
+  `.gitignore`'s own rules (no `**/` prefix) and case-folded with character
+  ranges. `example.env` and `sample.env` stay trackable through negations.
+- 2026-10-02: The image version now comes from git inside the build (issues 69
+  and 71), superseding the 2026-09-08 entry that excluded `.git`. The canonical
+  `.dockerignore` sends `.git` but keeps out `.git/config`, which can hold a
+  credential. The Dockerfile example in `REPO_POLICIES.md` installs `git`, takes
+  the `VERSION` build argument when one is given and otherwise
+  `git describe --tags --always`, and fails when `.git` exists but the version
+  is empty, `dev` or `unknown`; a plain `docker build .` with no build arguments
+  must succeed. This repo's `script/docker` and `script/cibuild` still pass
+  `--build-arg VERSION`, since its own `Dockerfile` compiles nothing.
 - 2026-09-08: Moved linting and testing into Docker as phases of the main
   `Dockerfile`, per the owner ruling on issue 40. `script/lint` and
   `script/test` build one phase each by name with `--no-cache` — the same answer

package.json

@@ -1,4 +1,5 @@
 {
+  "license": "MIT",
   "devDependencies": {
     "prettier": "3.8.1"
   }

prompts/CODE_STYLEGUIDE_GO.md

@@ -1,6 +1,6 @@
 ---
 title: Code Styleguide — Go
-last_modified: 2026-09-08
+last_modified: 2026-10-04
 ---
 
 1.  Try to hard wrap long lines at 77 characters or less.
@@ -48,14 +48,13 @@ last_modified: 2026-09-08
     ```
 
     ```make
-    # ?= rather than := because this `$(shell git describe ...)` is only
-    # correct on the host: `.dockerignore` excludes `.git`, so evaluated
-    # inside a build stage it expands to the empty string without failing
-    # and the binary reports no version. The version is computed on the
-    # host by `script/docker` / `script/cibuild` and passed with
-    # `--build-arg VERSION=...`; where a build stage invokes make,
-    # `ARG VERSION` puts it in the environment and `?=` defers to it.
-    VERSION ?= $(shell git describe --always --dirty)
+    # ?= rather than := so that a `VERSION` build argument takes precedence:
+    # where a build stage invokes make, `ARG VERSION` puts it in the
+    # environment and `?=` defers to it. Otherwise `git describe` runs, in a
+    # build stage on the `.git` the build context carries. When it prints
+    # nothing (outside a git checkout, or where git is missing or refuses the
+    # checkout), the version falls back to `dev`.
+    VERSION ?= $(or $(shell git describe --tags --always 2>/dev/null),dev)
 
     GOLDFLAGS += -X main.Version=$(VERSION)
 

prompts/EXISTING_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: Existing Repo Checklist
-last_modified: 2026-09-08
+last_modified: 2026-10-04
 ---
 
 Use this checklist when beginning work in a repo that may not yet conform to our
@@ -24,6 +24,10 @@ with your task.
 - [ ] `LICENSE` file exists and matches the README
 - [ ] `REPO_POLICIES.md` exists and version date is current — fetch from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md`
+- [ ] Guidance for coding agents, if the repo has any, is one `AGENTS.md` at the
+      root — never a file or directory named after one agent tool, such as
+      `CLAUDE.md` or `.claude/`, and never separate memory files. Move what any
+      such committed file says into `AGENTS.md` and delete it.
 - [ ] `.gitignore` is comprehensive (OS, editor, agent scratch, language
       artifacts, secrets) — fetch from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` if missing.
@@ -44,7 +48,7 @@ with your task.
       `script/test` — those are themselves a `docker build` and would recurse
       inside a build step
 - [ ] Every depth-independent pattern in `.dockerignore` carries a `**/` prefix,
-      only genuinely root-anchored entries such as `.git` are unprefixed, and
+      only genuinely root-anchored entries such as `.claude` are unprefixed, and
       `.gitignore`'s patterns have not been transplanted unmodified — the
       transplanted form leaves `config/.env` and `certs/server.key` in the build
       context while reading as solved
@@ -58,17 +62,42 @@ with your task.
       can copy another session's unreviewed work into an image layer. If agents
       here run anywhere other than the repo root, the anchored entry misses
       `services/api/.claude/`: add anchored entries for those directories.
-- [ ] If the repo embeds a version in a binary, that version is computed on the
-      host and passed with `--build-arg VERSION=...` by `script/docker` and
-      `script/cibuild`, and no stage calls `git describe`. A tag-derived version
-      additionally needs `fetch-depth: 0` on the CI checkout step, which clones
-      shallow and fetches no tags by default.
+- [ ] If the repo embeds a version in a binary: `.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.
+      `script/docker` and `script/cibuild` pass the version they compute on the
+      host; it takes precedence. A tag-derived version additionally needs
+      `fetch-depth: 0` on the CI checkout step, which clones shallow and fetches
+      no tags by default.
 - [ ] Gitea Actions workflow in `.gitea/workflows/` runs `script/cibuild` on
       push — reference
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitea/workflows/check.yml`
 - [ ] Language-specific config:
     - [ ] Go: `go.mod`, `go.sum`, `.golangci.yml` (fetch from
-          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`)
+          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml` and,
+          in the same commit, set the lint phase digest to the one named in the
+          `.golangci.yml` paragraph of `REPO_POLICIES.md`)
     - [ ] JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
           (fetch from
           `https://git.eeqj.de/sneak/prompts/raw/branch/main/.prettierrc` and

prompts/GO_HTTP_SERVER_CONVENTIONS.md

@@ -1,6 +1,6 @@
 ---
 title: Go HTTP Server Conventions
-last_modified: 2026-09-08
+last_modified: 2026-10-04
 ---
 
 This document defines the architectural patterns, design decisions, and
@@ -106,6 +106,9 @@ project-root/
 package main
 
 import (
+    "os/signal"
+    "syscall"
+
     "yourproject/internal/config"
     "yourproject/internal/database"
     "yourproject/internal/globals"
@@ -126,6 +129,9 @@ func main() {
     globals.Appname = Appname
     globals.Version = Version
 
+    // A write to a closed stdout or stderr must not end the process.
+    signal.Ignore(syscall.SIGPIPE)
+
     fx.New(
         fx.Provide(
             config.New,
@@ -198,7 +204,8 @@ Providers are resolved automatically by fx, but conceptually follow this order:
    Database)
 6. `middleware.New` - Middleware (depends on Logger, Globals, Config)
 7. `handlers.New` - Handlers (depends on Logger, Globals, Database, Healthcheck)
-8. `server.New` - Server (depends on all above)
+8. `server.New` - Server (depends on all above, and on `fx.Shutdowner`, which fx
+   provides itself)
 
 ---
 
@@ -217,16 +224,14 @@ type ServerParams struct {
     Config     *config.Config
     Middleware *middleware.Middleware
     Handlers   *handlers.Handlers
+    Shutdowner fx.Shutdowner
 }
 
 type Server struct {
     startupTime   time.Time
     port          int
-    exitCode      int
     sentryEnabled bool
     log           *slog.Logger
-    ctx           context.Context
-    cancelFunc    context.CancelFunc
     httpServer    *http.Server
     router        *chi.Mux
     params        ServerParams
@@ -248,13 +253,15 @@ func New(lc fx.Lifecycle, params ServerParams) (*Server, error) {
     lc.Append(fx.Hook{
         OnStart: func(ctx context.Context) error {
             s.startupTime = time.Now()
-            go s.Run()
-            return nil
-        },
-        OnStop: func(ctx context.Context) error {
-            // Server shutdown logic
+            if err := s.enableSentry(); err != nil {
+                return err
+            }
+            s.SetupRoutes()
+            s.httpServer = s.newHTTPServer()
+            go s.serveUntilShutdown()
             return nil
         },
+        OnStop: s.cleanShutdown,
     })
     return s, nil
 }
@@ -264,23 +271,25 @@ func New(lc fx.Lifecycle, params ServerParams) (*Server, error) {
 
 ```go
 // internal/server/http.go
-func (s *Server) serveUntilShutdown() {
-    listenAddr := fmt.Sprintf(":%d", s.params.Config.Port)
-    s.httpServer = &http.Server{
-        Addr:           listenAddr,
+func (s *Server) newHTTPServer() *http.Server {
+    return &http.Server{
+        Addr:           fmt.Sprintf(":%d", s.params.Config.Port),
         ReadTimeout:    10 * time.Second,
         WriteTimeout:   10 * time.Second,
         MaxHeaderBytes: 1 << 20,
         Handler:        s,
     }
+}
 
-    s.SetupRoutes()
-
-    s.log.Info("http begin listen", "listenaddr", listenAddr)
+// serveUntilShutdown returns when the stop hook shuts the HTTP server down.
+// If it stops for any other reason, such as its port being taken, it asks fx
+// to shut down with exit code 1.
+func (s *Server) serveUntilShutdown() {
+    s.log.Info("http begin listen", "listenaddr", s.httpServer.Addr)
     if err := s.httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed {
         s.log.Error("listen error", "error", err)
-        if s.cancelFunc != nil {
-            s.cancelFunc()
+        if err := s.params.Shutdowner.Shutdown(fx.ExitCode(1)); err != nil {
+            s.log.Error("shutdown request failed", "error", err)
         }
     }
 }
@@ -292,43 +301,30 @@ func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 
 ## Signal Handling and Graceful Shutdown
 
+fx owns SIGINT, SIGTERM and the exit code. `Run()` in `main` waits for one of
+those signals or for a call to `Shutdown()` on `fx.Shutdowner`, runs the stop
+hooks, and exits 0 after a signal, or with the code the call gave in
+`fx.ExitCode`. It exits 1 instead when a start hook or a stop hook returns an
+error; when a start hook fails, fx first runs the stop hooks of everything
+already started. No other code calls `signal.Notify` or `os.Exit`: the listen
+error above asks fx to shut down with `fx.ExitCode(1)`, and a Sentry start
+failure is returned from the start hook. Each component releases its own
+resources in its own stop hook, which fx runs in the reverse order of start.
+
 ```go
-func (s *Server) serve() int {
-    s.ctx, s.cancelFunc = context.WithCancel(context.Background())
-
-    // Signal watcher
-    go func() {
-        c := make(chan os.Signal, 1)
-        signal.Ignore(syscall.SIGPIPE)
-        signal.Notify(c, os.Interrupt, syscall.SIGTERM)
-        sig := <-c
-        s.log.Info("signal received", "signal", sig)
-        if s.cancelFunc != nil {
-            s.cancelFunc()
-        }
-    }()
-
-    go s.serveUntilShutdown()
-
-    for range s.ctx.Done() {
-    }
-    s.cleanShutdown()
-    return s.exitCode
-}
-
-func (s *Server) cleanShutdown() {
-    s.exitCode = 0
-    ctxShutdown, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second)
-    if err := s.httpServer.Shutdown(ctxShutdown); err != nil {
-        s.log.Error("server clean shutdown failed", "error", err)
-    }
-    if shutdownCancel != nil {
-        shutdownCancel()
-    }
-    s.cleanupForExit()
+// cleanShutdown is the server's stop hook. It fails when requests are still
+// running after 5 seconds.
+func (s *Server) cleanShutdown(ctx context.Context) error {
+    ctxShutdown, shutdownCancel := context.WithTimeout(ctx, 5*time.Second)
+    defer shutdownCancel()
+    err := s.httpServer.Shutdown(ctxShutdown)
     if s.sentryEnabled {
         sentry.Flush(2 * time.Second)
     }
+    if err != nil {
+        return fmt.Errorf("http server shutdown: %w", err)
+    }
+    return nil
 }
 ```
 
@@ -984,14 +980,13 @@ func main() {
 Use ldflags to inject version information at build time:
 
 ```makefile
-# ?= rather than := because this `$(shell git describe ...)` is only correct
-# on the host: `.dockerignore` excludes `.git`, so evaluated inside a build
-# stage it expands to the empty string without failing and the binary reports
-# no version. The version is computed on the host by `script/docker` /
-# `script/cibuild` and passed with `--build-arg VERSION=...`; where the build
-# stage invokes make, `ARG VERSION` puts it in the environment and `?=` defers
-# to it.
-VERSION ?= $(shell git describe --tags --always)
+# ?= rather than := so that a `VERSION` build argument takes precedence:
+# where a build stage invokes make, `ARG VERSION` puts it in the
+# environment and `?=` defers to it. Otherwise `git describe` runs, in a
+# build stage on the `.git` the build context carries. When it prints
+# nothing (outside a git checkout, or where git is missing or refuses the
+# checkout), the version falls back to `dev`.
+VERSION ?= $(or $(shell git describe --tags --always 2>/dev/null),dev)
 
 build:
     go build -ldflags "-X main.Version=$(VERSION)" ./cmd/httpd
@@ -1161,11 +1156,11 @@ s.router.Get("/.well-known/healthcheck", s.h.HandleHealthCheck())
 Sentry is conditionally enabled based on `SENTRY_DSN` environment variable:
 
 ```go
-func (s *Server) enableSentry() {
+func (s *Server) enableSentry() error {
     s.sentryEnabled = false
 
     if s.params.Config.SentryDSN == "" {
-        return
+        return nil
     }
 
     err := sentry.Init(sentry.ClientOptions{
@@ -1173,15 +1168,17 @@ func (s *Server) enableSentry() {
         Release: fmt.Sprintf("%s-%s", s.params.Globals.Appname, s.params.Globals.Version),
     })
     if err != nil {
-        s.log.Error("sentry init failure", "error", err)
-        os.Exit(1)
-        return
+        return fmt.Errorf("sentry init failure: %w", err)
     }
     s.log.Info("sentry error reporting activated")
     s.sentryEnabled = true
+    return nil
 }
 ```
 
+The server's start hook calls `enableSentry()` and returns its error, so a DSN
+Sentry rejects stops startup and fx exits 1.
+
 Sentry middleware with repanic (bubbles panics to chi's Recoverer):
 
 ```go
@@ -1193,7 +1190,7 @@ if s.sentryEnabled {
 }
 ```
 
-Flush Sentry on shutdown:
+Flush Sentry in the server's stop hook, `cleanShutdown()`:
 
 ```go
 if s.sentryEnabled {

prompts/NEW_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: New Repo Checklist
-last_modified: 2026-09-08
+last_modified: 2026-10-04
 ---
 
 Use this checklist when creating a new repository from scratch. Follow the steps
@@ -54,6 +54,9 @@ Template files can be fetched from:
 - [ ] `LICENSE` file matching the chosen license
 - [ ] `REPO_POLICIES.md` — fetch from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md`
+- [ ] Guidance for coding agents, if the repo has any, is one `AGENTS.md` at the
+      root — never a file or directory named after one agent tool, such as
+      `CLAUDE.md` or `.claude/`, and never separate memory files
 - [ ] `Dockerfile` and `.dockerignore` — fetch `.dockerignore` from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore`
     - Extend `.dockerignore` with the repo's own host-built artifacts, giving
@@ -67,11 +70,30 @@ Template files can be fetched from:
       note that it only covers agents running at the repo root — if this repo
       will run them in subdirectories, `services/api/.claude/` needs its own
       anchored entry.
-    - If the image embeds a version in a binary, the version is computed on the
-      host and passed with `--build-arg VERSION=...`, and `ARG VERSION=dev` is
-      declared in the stage that compiles. **No stage calls `git describe`** —
-      `.dockerignore` excludes `.git`, so it yields an empty version without
-      failing the build.
+    - If the image embeds a version in a binary: `.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.
     - The Dockerfile carries a `lint` phase and a `test` phase, each invoking
       its tool directly rather than through `make` or `script/`, and the final
       stage carries a `COPY --from=` of a harmless file from each so the image
@@ -85,7 +107,9 @@ Template files can be fetched from:
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitea/workflows/check.yml`
 - [ ] Language-specific:
     - [ ] Go: `go mod init sneak.berlin/go/<name>`, `.golangci.yml` (fetch from
-          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`)
+          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml` and,
+          in the same commit, set the lint phase digest to the one named in the
+          `.golangci.yml` paragraph of `REPO_POLICIES.md`)
     - [ ] JS: `yarn init`, `yarn add --dev prettier`
     - [ ] Python: `pyproject.toml`
 
@@ -100,8 +124,10 @@ are thin shims calling them. Model scripts:
 - [ ] `script/bootstrap` / `make bootstrap` — installs all dependencies,
       idempotently, assuming nothing (pkg manager detection nix/apt/brew/apk;
       node used if present, else pinned version via nvm from a hash-verified
-      archive; pinned yarn via corepack); Dockerfile runs it instead of inline
-      installs
+      archive; pinned yarn via corepack); a non-server repo's development
+      environment stage runs it instead of inline installs; a gate phase or the
+      build stage installs what its base image lacks either inline or by running
+      it
 - [ ] `script/setup` / `make setup` — readies a fresh clone: runs `bootstrap`,
       then `install-precommit`, plus repo-specific init
 - [ ] `script/test` / `make test` — `docker build --no-cache --target test .`,

prompts/REPO_POLICIES.md

@@ -1,6 +1,6 @@
 ---
 title: Repository Policies
-last_modified: 2026-09-08
+last_modified: 2026-10-04
 ---
 
 This document covers repository structure, tooling, and workflow standards. Code
@@ -104,10 +104,14 @@ style conventions are in separate documents:
   `lint` phase and a `test` phase, with the final stage depending on both so the
   image cannot be built unless they pass. For non-server repos the final stage
   brings up a development environment; for server repos it is the runtime image.
-  Dockerfiles install development prerequisites by running `script/bootstrap`
-  rather than duplicating installs inline; COPY `script/` and the dependency
-  manifests (`package.json` + `yarn.lock`, `go.mod` + `go.sum`, etc.) before
-  running it.
+  The gate phases and the build stage start from their pinned base images and
+  install what those images lack either inline, as the canonical Go `Dockerfile`
+  below does for `git`, or by running `script/bootstrap`, as the `prompts`
+  repo's own `Dockerfile` does for its yarn packages. The development
+  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.
 
 - **Linting and testing run in Docker, as phases of the `Dockerfile`.** There is
   no separate lint file. `script/lint` and `script/test` each build one phase
@@ -156,11 +160,14 @@ style conventions are in separate documents:
   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 Go image. The canonical Go repo
+  and the test phase is based on the Debian Go image. The canonical Go repo
   `Dockerfile`:
 
     ```dockerfile
@@ -173,8 +180,9 @@ style conventions are in separate documents:
     COPY . .
     RUN golangci-lint run --config .golangci.yml ./...
 
-    # Test phase
-    # golang:1.x-alpine, YYYY-MM-DD
+    # Test phase. -race needs cgo and so a C compiler, which the Debian Go
+    # image ships and the alpine one does not.
+    # golang:1.x, YYYY-MM-DD
     FROM golang@sha256:... AS test
     WORKDIR /src
     COPY go.mod go.sum ./
@@ -191,15 +199,29 @@ style conventions are in separate documents:
     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 . .
 
-    ARG VERSION=dev
-    RUN CGO_ENABLED=0 go build -trimpath \
-        -ldflags="-s -w -X main.Version=${VERSION}" \
-        -o /app ./cmd/app/
+    # 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:...
@@ -221,10 +243,41 @@ style conventions are in separate documents:
       (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`.
-    - If the project requires CGO or system libraries for linting (e.g.
-      `vips-dev`), install them in the lint phase with `apk add`.
-    - `ARG VERSION=dev` is declared in the stage that compiles and supplied by
-      `script/docker` and `script/cibuild`; no stage may call `git describe`.
+    - If the project requires CGO or system libraries for linting, install them
+      in the lint phase. The `golangci/golangci-lint` image is Debian-based and
+      has no `apk`, so install with `apt-get` under the Debian package name
+      (`libvips-dev`, where alpine says `vips-dev`), and delete the package
+      lists in the same `RUN`, so the layer does not keep them:
+
+        ```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` on push, and checks out the repo as its only other step.
@@ -233,7 +286,12 @@ style conventions are in separate documents:
   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.
+  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
@@ -286,17 +344,19 @@ style conventions are in separate documents:
     ```
 
     `-count=1` is required on both invocations: it defeats Go's test _result_
-    cache, so the target cannot report a pass it did not earn, and the rerun
-    reproduces a failure instead of replaying it. It leaves the build cache
-    alone, so it costs the runtime of the suite and no recompilation.
+    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.
 
-    Note that this is a second, independent cache, stacked below the Docker
-    layer cache that [issue #26](https://git.eeqj.de/sneak/prompts/issues/26)
-    addresses. `CHECK_EPOCH` guarantees the `RUN make test` _step_ re-executes;
-    it does not guarantee `go test` inside that step does any work, because the
-    `GOCACHE` baked into earlier image layers survives into the re-executed
-    step. They are two separate defects requiring two separate fixes, and a fix
-    for one must not be recorded as covering the other.
+    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:
 
@@ -340,7 +400,7 @@ style conventions are in separate documents:
   — 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: `.git`, and the repo's own host-built
+  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
@@ -365,12 +425,13 @@ style conventions are in separate documents:
   directory, so a repo running agents in subdirectories still ships
   `services/api/.claude/` and must add its own anchored entry there.
 
-- **Excluding `.git` means `git describe` cannot run inside any build stage, and
-  it fails quietly there.** In a build stage there is no repository, so
-  `git describe` writes nothing to stdout, `-X main.Version=` comes out empty,
-  the binary reports no version at all, and the build still exits 0. Compute the
-  version on the host and thread it in as a build arg. `script/docker` and
-  `script/cibuild` do this, byte-identically across repos:
+- **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
@@ -387,7 +448,7 @@ style conventions are in separate documents:
     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=dev` in the stage that compiles, declared
+    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
@@ -426,12 +487,18 @@ style conventions are in separate documents:
   `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.12.2 (released 2026-05-06), pinned as the digest of the lint phase's base
+  v2.14.0 (released 2026-09-24), pinned as the digest of the lint phase's base
   image
-  (`golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240`,
-  which reports `2.12.2 built with go1.26.2 from c0d3ddc9`). That digest is the
-  only pin, since no repo installs golangci-lint on the host: bumping the
-  version means changing it and nothing else.
+  (`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
@@ -455,6 +522,11 @@ style conventions are in separate documents:
 
     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).
 
@@ -567,10 +639,10 @@ 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`,
-  `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, and
-  language-specific config). Everything else goes in a subdirectory. Canonical
-  subdirectory names:
+  only project-level config files (`README.md`, `AGENTS.md`, `Makefile`,
+  `Dockerfile`, `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`,
+  and language-specific config). Everything else goes in a subdirectory.
+  Canonical subdirectory names:
     - `bin/` — executable scripts and tools
     - `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
@@ -601,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.

script/cibuild

@@ -16,9 +16,8 @@ main() {
     "$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. VERSION is computed here because .dockerignore
-    # excludes .git, so `git describe` in a build stage yields an empty
-    # version without failing.
+    # 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 \

script/docker

@@ -12,9 +12,8 @@ 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. VERSION is computed here because .dockerignore
-    # excludes .git, so `git describe` in a build stage yields an empty
-    # version without failing.
+    # 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 \