Rewrite the -count=1 note to match the current files (closes #77)

The note under the canonical Go `make test` example in `prompts/REPO_POLICIES.md` still named the cache-busting build argument that `--no-cache` replaced, and said Go's cache was baked into earlier image layers.

It now says where Go's test result cache can replay a pass: on a developer's machine, where the Makefile target runs, so `-count=1` stays on both invocations. The `test` phase of the `Dockerfile` has nothing to replay: its base image holds no result for the repo's tests and no earlier step runs one.

The first paragraph no longer says the rerun would replay a failure: Go stores only passes.

Model: opus-5-5

.dockerignore

@@ -13,9 +13,11 @@
 # `/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
+# .git is sent without its config. Without a VERSION build argument the
-# fails quietly there; pass the version in with --build-arg VERSION.
+# stage that compiles runs `git describe --tags --always` on .git, which
-.git
+# 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.
+.git/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.

.gitignore

@@ -20,8 +20,26 @@ Thumbs.db
 # Node
 node_modules/
 
-# Environment / secrets
+# Secrets. Unanchored like every entry above, so each matches at every
-.env
+# depth. Matching is case-sensitive on Linux, so names use character
-.env.*
+# ranges rather than a lowercase form that misses `Server.Key`.
-*.pem
+
-*.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][dD]25519

.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
+# Nothing here is compiled and a LABEL cannot run git, so the version is
-# .dockerignore excludes .git.
+# the VERSION build argument that script/docker and script/cibuild pass;
-ARG VERSION=dev
+# 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
+  `script/fmt-check` is native)
-  `.dockerignore` excludes `.git`)
 - `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,40 @@ fmt-check, and commit.
 
 # Completed Steps
 
+- 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-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

prompts/CODE_STYLEGUIDE_GO.md

@@ -1,6 +1,6 @@
 ---
 title: Code Styleguide — Go
-last_modified: 2026-09-08
+last_modified: 2026-10-02
 ---
 
 1.  Try to hard wrap long lines at 77 characters or less.
@@ -24,7 +24,8 @@ last_modified: 2026-09-08
 1.  Embed the git commit hash into the binary and include it in startup logs and
     in health check output. This is to make it easier to correlate running
     instances with their code. Do not include build time or build user, as these
-    will make the build nondeterministic.
+    will make the build nondeterministic. The architecture is not passed in at
+    build time; a program that reports it reads `runtime.GOARCH` at run time.
 
     Example relevant Makefile sections:
 
@@ -35,32 +36,25 @@ last_modified: 2026-09-08
 
     import (
         "fmt"
+        "runtime"
     )
 
-    var (
+    var Version string
-        Version   string
-        Buildarch string
-    )
 
     func main() {
         fmt.Printf("Version: %s\n", Version)
-        fmt.Printf("Buildarch: %s\n", Buildarch)
+        fmt.Printf("Arch: %s\n", runtime.GOARCH)
     }
     ```
 
     ```make
-    # ?= rather than := because this `$(shell git describe ...)` is only
+    # ?= rather than := so that a `VERSION` build argument takes precedence:
-    # correct on the host: `.dockerignore` excludes `.git`, so evaluated
+    # where a build stage invokes make, `ARG VERSION` puts it in the
-    # inside a build stage it expands to the empty string without failing
+    # environment and `?=` defers to it. Otherwise `git describe` runs, in a
-    # and the binary reports no version. The version is computed on the
+    # build stage on the `.git` the build context carries.
-    # host by `script/docker` / `script/cibuild` and passed with
+    VERSION ?= $(shell git describe --tags --always)
-    # `--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)
-    BUILDARCH := $(shell uname -m)
 
     GOLDFLAGS += -X main.Version=$(VERSION)
-    GOLDFLAGS += -X main.Buildarch=$(BUILDARCH)
 
     # osx can't statically link apparently?!
     ifeq ($(UNAME_S),Darwin)

prompts/EXISTING_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: Existing Repo Checklist
-last_modified: 2026-09-08
+last_modified: 2026-10-03
 ---
 
 Use this checklist when beginning work in a repo that may not yet conform to our
@@ -44,7 +44,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 +58,35 @@ 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
+- [ ] If the repo embeds a version in a binary: `.dockerignore` lets `.git` into
-      host and passed with `--build-arg VERSION=...` by `script/docker` and
+      the build context. It keeps out `.git/config`, which `git describe` does
-      `script/cibuild`, and no stage calls `git describe`. A tag-derived version
+      not need and which can hold a credential: a password in a remote URL, or
-      additionally needs `fetch-depth: 0` on the CI checkout step, which clones
+      the token the CI checkout step stores there. The stage that compiles has
-      shallow and fetches no tags by default.
+      `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-02
 ---
 
 This document defines the architectural patterns, design decisions, and
@@ -118,15 +118,13 @@ import (
 )
 
 var (
-    Appname   string = "CHANGEME"
+    Appname string = "CHANGEME"
-    Version   string
+    Version string
-    Buildarch string
 )
 
 func main() {
     globals.Appname = Appname
     globals.Version = Version
-    globals.Buildarch = Buildarch
 
     fx.New(
         fx.Provide(
@@ -826,7 +824,7 @@ func (l *Logger) Identify() {
     l.log.Info("starting",
         "appname", l.params.Globals.Appname,
         "version", l.params.Globals.Version,
-        "buildarch", l.params.Globals.Buildarch,
+        "arch", runtime.GOARCH,
     )
 }
 ```
@@ -946,23 +944,20 @@ import "go.uber.org/fx"
 
 // Package-level variables (set from main)
 var (
-    Appname   string
+    Appname string
-    Version   string
+    Version string
-    Buildarch string
 )
 
 // Struct for DI
 type Globals struct {
-    Appname   string
+    Appname string
-    Version   string
+    Version string
-    Buildarch string
 }
 
 func New(lc fx.Lifecycle) (*Globals, error) {
     n := &Globals{
-        Appname:   Appname,
+        Appname: Appname,
-        Buildarch: Buildarch,
+        Version: Version,
-        Version:   Version,
     }
     return n, nil
 }
@@ -973,15 +968,13 @@ func New(lc fx.Lifecycle) (*Globals, error) {
 ```go
 // cmd/httpd/main.go
 var (
-    Appname   string = "CHANGEME"  // Default, overridden by build
+    Appname string = "CHANGEME"  // Default, overridden by build
-    Version   string               // Set at build time
+    Version string               // Set at build time
-    Buildarch string               // Set at build time
 )
 
 func main() {
     globals.Appname = Appname
     globals.Version = Version
-    globals.Buildarch = Buildarch
     // ...
 }
 ```
@@ -991,18 +984,14 @@ func main() {
 Use ldflags to inject version information at build time:
 
 ```makefile
-# ?= rather than := because this `$(shell git describe ...)` is only correct
+# ?= rather than := so that a `VERSION` build argument takes precedence:
-# on the host: `.dockerignore` excludes `.git`, so evaluated inside a build
+# where a build stage invokes make, `ARG VERSION` puts it in the
-# stage it expands to the empty string without failing and the binary reports
+# environment and `?=` defers to it. Otherwise `git describe` runs, in a
-# no version. The version is computed on the host by `script/docker` /
+# build stage on the `.git` the build context carries.
-# `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)
-BUILDARCH := $(shell go env GOARCH)
 
 build:
-    go build -ldflags "-X main.Version=$(VERSION) -X main.Buildarch=$(BUILDARCH)" ./cmd/httpd
+    go build -ldflags "-X main.Version=$(VERSION)" ./cmd/httpd
 ```
 
 ---

prompts/NEW_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: New Repo Checklist
-last_modified: 2026-09-08
+last_modified: 2026-10-03
 ---
 
 Use this checklist when creating a new repository from scratch. Follow the steps
@@ -67,11 +67,24 @@ 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
+    - If the image embeds a version in a binary: `.dockerignore` lets `.git`
-      host and passed with `--build-arg VERSION=...`, and `ARG VERSION=dev` is
+      into the build context. It keeps out `.git/config`, which `git describe`
-      declared in the stage that compiles. **No stage calls `git describe`** —
+      does not need and which can hold a credential: a password in a remote URL,
-      `.dockerignore` excludes `.git`, so it yields an empty version without
+      or the token the CI checkout step stores there. The stage that compiles
-      failing the build.
+      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 +98,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`
 

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
@@ -160,7 +160,7 @@ style conventions are in separate documents:
 - **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 +173,9 @@ style conventions are in separate documents:
     COPY . .
     RUN golangci-lint run --config .golangci.yml ./...
 
-    # Test phase
+    # 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.
+    # golang:1.x, YYYY-MM-DD
     FROM golang@sha256:... AS test
     WORKDIR /src
     COPY go.mod go.sum ./
@@ -191,15 +192,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
+    # The VERSION build arg when one is given, otherwise
-    RUN CGO_ENABLED=0 go build -trimpath \
+    # `git describe --tags --always` on the .git in the build context. With
-        -ldflags="-s -w -X main.Version=${VERSION}" \
+    # .git present, a version that is still empty, dev or unknown fails the
-        -o /app ./cmd/app/
+    # 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:...
@@ -223,8 +238,23 @@ style conventions are in separate documents:
       `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
+    - `.dockerignore` lets `.git` into the build context. It keeps out
-      `script/docker` and `script/cibuild`; no stage may call `git describe`.
+      `.git/config`, which `git describe` does not need and which can hold a
+      credential: a password in a remote URL, or the token the CI checkout step
+      stores there. 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.
@@ -286,17 +316,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
+    cache, so neither run can report a stored pass in place of running the
-    reproduces a failure instead of replaying it. It leaves the build cache
+    tests. It leaves the build cache alone, so it costs the runtime of the suite
-    alone, so it costs the runtime of the suite and no recompilation.
+    and no recompilation.
 
-    Note that this is a second, independent cache, stacked below the Docker
+    That cache is Go's own, separate from Docker's layer cache. Go stores a
-    layer cache that [issue #26](https://git.eeqj.de/sneak/prompts/issues/26)
+    passing result in its cache directory (`GOCACHE`), and when the same tests
-    addresses. `CHECK_EPOCH` guarantees the `RUN make test` _step_ re-executes;
+    run again on unchanged code it prints that result, marked `(cached)`,
-    it does not guarantee `go test` inside that step does any work, because the
+    without running them. That matters on a developer's machine, where this
-    `GOCACHE` baked into earlier image layers survives into the re-executed
+    target runs and the directory lasts from one run to the next. The `test`
-    step. They are two separate defects requiring two separate fixes, and a fix
+    phase of the `Dockerfile` needs no `-count=1`: its base image holds no
-    for one must not be recorded as covering the other.
+    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 +372,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 +397,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
+- **A plain `docker build .` of a clone stamps the version that
-  it fails quietly there.** In a build stage there is no repository, so
+  `git describe --tags --always` gives**, derived from the `.git` in the build
-  `git describe` writes nothing to stdout, `-X main.Version=` comes out empty,
+  context as the canonical `Dockerfile` above shows. Without its failure check,
-  the binary reports no version at all, and the build still exits 0. Compute the
+  a missing `git` or an unreadable checkout would leave `-X main.Version=` empty
-  version on the host and thread it in as a build arg. `script/docker` and
+  and the build would still exit 0. `script/docker` and `script/cibuild` pass
-  `script/cibuild` do this, byte-identically across repos:
+  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 +420,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 +459,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`,
+  (`golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f`,
-  which reports `2.12.2 built with go1.26.2 from c0d3ddc9`). That digest is the
+  which reports `2.14.0 built with go1.27.0 from 114493f9`). A module's `go`
-  only pin, since no repo installs golangci-lint on the host: bumping the
+  directive must not name a newer Go minor version than the one golangci-lint
-  version means changing it and nothing else.
+  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

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
+    # empty constant. The VERSION build argument takes precedence over
-    # excludes .git, so `git describe` in a build stage yields an empty
+    # the version a build stage derives from the .git in the context.
-    # version without failing.
     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
+    # empty constant. The VERSION build argument takes precedence over
-    # excludes .git, so `git describe` in a build stage yields an empty
+    # the version a build stage derives from the .git in the context.
-    # version without failing.
     version="$(git describe --tags --always --dirty 2>/dev/null || true)"
     [ -n "$version" ] || version="unknown"
     docker build --no-cache \