Say that a build from a linked worktree needs the version passed in (closes #111)

A plain `docker build .` from a checkout whose `.git` is a file (a linked worktree, or a repository checked out as a submodule) stops at the version check of the canonical `Dockerfile` example: that file points to a git directory outside the build context, so `git describe` prints nothing. The check is right to refuse an empty version; what was missing is what to do. `prompts/REPO_POLICIES.md` and both checklists now say such a build is given its version with `--build-arg VERSION=...`, as `script/docker` and `script/cibuild` already do. The check itself is unchanged.

Model: opus-5-5

.dockerignore

@@ -17,7 +17,17 @@
 # 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.
-.git/config
+# 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.
@@ -41,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

.editorconfig

@@ -10,3 +10,9 @@ insert_final_newline = true
 
 [Makefile]
 indent_style = tab
+
+[*.go]
+indent_style = tab
+
+# This repository's own sections, such as one for another language it
+# uses, go below this comment, and a re-vendor keeps them.

.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

.gitea/workflows/check.yml

@@ -1,9 +1,16 @@
 name: check
 on: [push]
+# Free the shared runner: a new push cancels only the same branch's older run.
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
 jobs:
     check:
         runs-on: ubuntu-latest
         steps:
             # 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:
+                  persist-credentials: false
             - run: script/cibuild

.gitignore

@@ -20,8 +20,32 @@ 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 at the end of this file, 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, such as its build outputs, go below
+# this comment, and a re-vendor keeps them. Anchor a binary built at the
+# root: `/myapp`, never `myapp`, which also ignores `cmd/myapp/`.

.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
@@ -24,6 +25,8 @@ linters:
     # silenced by disabling that name, not by enabling the successor.
     - wsl              # Deprecated, replaced by wsl_v5
     - gomodguard       # Deprecated, replaced by gomodguard_v2
+    # Misses findings at random in v2.14.0; back once a pinned release fixes it
+    - canonicalheader
   settings:
     lll:
       line-length: 88

TODO.md

@@ -21,6 +21,144 @@ fmt-check, and commit.
 
 # Completed Steps
 
+- 2026-10-06: `REPO_POLICIES.md` and both checklists now say that a checkout
+  whose `.git` is a file, a linked worktree or a repository checked out as a
+  submodule, is the exception to a plain `docker build .` succeeding (issue
+  111): that file points to a git directory outside the build context, so the
+  build cannot read the version and the version check in the canonical
+  `Dockerfile` stops it. Such a build is given its version with
+  `--build-arg VERSION=...`, as `script/docker` and `script/cibuild` already do.
+  The check itself is unchanged.
+- 2026-10-06: The canonical `.gitea/workflows/check.yml` now has a `concurrency`
+  block, so a new push cancels the older run on the same branch and no other,
+  and its checkout step sets `persist-credentials: false`, so the job's token is
+  not left in `.git/config` (issue 107). `REPO_POLICIES.md` and both checklists
+  describe the workflow as it now is. Not yet tried on the shared runner, which
+  is out of disk space. Repositories pick this up on their next re-vendor.
+- 2026-10-06: The canonical `.golangci.yml` now disables `canonicalheader`
+  (issue 105). In golangci-lint v2.14.0 it misses findings at random in a
+  package that also calls `ResponseWriter.Header()`, so the same tree can fail
+  lint on one run and pass on the next. It comes back once a pinned
+  golangci-lint release fixes it.
+- 2026-10-06: The canonical `.gitignore` and `.editorconfig` now each end with a
+  comment saying the repository's own entries go below it and a re-vendor keeps
+  them (issue 103, which took in issue 104), as `.dockerignore`'s header already
+  does. `.editorconfig` gains a `[*.go]` section with tabs, since `gofmt`
+  decides Go indentation everywhere. `REPO_POLICIES.md` and both checklists say
+  that each of these two files is the canonical content followed by the
+  repository's own entries, which a re-vendor keeps, and the Go styleguide puts
+  `*.log`, `*.out`, `*.test` and binaries among those entries. Common outputs
+  stay out of the canonical `.gitignore`; each repository lists its own.
+- 2026-10-05: `script/cibuild`, `script/docker`, `script/lint` and `script/test`
+  now assign the image tag from `script/projectname` on its own line before the
+  `docker build` (issue 101), so `set -e` stops the script where
+  `script/projectname` fails instead of running `docker build` with a broken
+  tag. The comment above it in each script says why, and the snippets in
+  `REPO_POLICIES.md` show the same form. Repositories pick this up on their next
+  re-vendor.
+- 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

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-10-02
+last_modified: 2026-10-06
 ---
 
 1.  Try to hard wrap long lines at 77 characters or less.
@@ -51,8 +51,10 @@ last_modified: 2026-10-02
     # ?= 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.
+    # build stage on the `.git` the build context carries. When it prints
-    VERSION ?= $(shell git describe --tags --always)
+    # 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)
 
@@ -146,8 +148,9 @@ last_modified: 2026-10-02
     handle HTTP requests. Don't use methods or your top level functions as
     handlers.
 
-1.  Provide a .gitignore file that ignores at least `*.log`, `*.out`, and
+1.  The repository's own entries at the end of `.gitignore`, which a re-vendor
-    `*.test` files, as well as any binaries.
+    keeps, ignore at least `*.log`, `*.out`, and `*.test` files, as well as any
+    binaries.
 
 1.  Constructors **must** be called `New()`. `modulename.New()` works great if
     you name the packages properly. If the constructor creates an instance from

prompts/EXISTING_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: Existing Repo Checklist
-last_modified: 2026-10-02
+last_modified: 2026-10-06
 ---
 
 Use this checklist when beginning work in a repo that may not yet conform to our
@@ -24,13 +24,22 @@ 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`
-- [ ] `.gitignore` is comprehensive (OS, editor, agent scratch, language
+- [ ] Guidance for coding agents, if the repo has any, is one `AGENTS.md` at the
-      artifacts, secrets) — fetch from
+      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, secrets, the
+      repo's own build outputs) — fetch from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` if missing.
       An existing repo usually has a hand-written one that is never re-fetched,
-      so check the entries rather than the file's presence.
+      so check the entries rather than the file's presence. The file is the
+      canonical content followed by the repo's own entries, such as its
+      binaries; a re-vendor replaces the canonical part and keeps those entries.
 - [ ] `.editorconfig` exists — fetch from
-      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`
+      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`. The
+      file is the canonical content followed by the repo's own sections, such as
+      one for another language it uses; a re-vendor replaces the canonical part
+      and keeps those sections.
 - [ ] `Dockerfile` and `.dockerignore` exist; the Dockerfile carries a `lint`
       phase and a `test` phase, and the final stage carries a `COPY --from=` of
       a harmless file from each — fetch `.dockerignore` from
@@ -59,28 +68,47 @@ with your task.
       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: `.dockerignore` lets `.git` into
-      the build context. It keeps out `.git/config`, which `git describe` does
+      the build context. It keeps out every git `config` at any depth
-      not need and which can hold a credential: a password in a remote URL, or
+      (`**/.git/config`, `**/.git/modules/**/config`): the repository's own,
-      the token the CI checkout step stores there. The stage that compiles has
+      each submodule's under `.git/modules/`, and that of a submodule keeping
-      `git` (the Debian Go image has it; an alpine one needs
+      its own `.git` directory. `git describe` does not need them, and each can
-      `apk add --no-cache git`) and takes the version from the `VERSION` build
+      hold a credential: a password in a remote URL, or the token the CI
-      argument when one is given, otherwise from `git describe --tags --always`.
+      checkout step stores there. A submodule whose name has a `config` segment
-      That gives the tag on a tagged commit; on a later commit, the tag, the
+      (`config`, `deploy/config`, `config/lib`) loses its whole git directory to
-      number of commits since it and the short commit (`v1.2.3-4-gabc1234`); and
+      `**/.git/modules/**/config`, and Go's version stamping then fails the
-      the short commit when no tag is reachable. `ARG VERSION` has no default,
+      build: give it a name without that segment (`git submodule add --name`).
-      and the build fails if the context carries `.git` and the version still
+      The stage that compiles has `git` (the Debian Go image has it; an alpine
-      comes out empty, `dev` or `unknown`. A plain `docker build .` with no
+      one needs `apk add --no-cache git`) and takes the version from the
-      build arguments must succeed; a Dockerfile that refuses an empty build
+      `VERSION` build argument when one is given, otherwise from
-      argument drops that refusal and keeps the argument. `script/docker` and
+      `git describe --tags --always`. That gives the tag on a tagged commit; on
-      `script/cibuild` pass the version they compute on the host; it takes
+      a later commit, the tag, the number of commits since it and the short
-      precedence. A tag-derived version additionally needs `fetch-depth: 0` on
+      commit (`v1.2.3-4-gabc1234`); and the short commit when no tag is
-      the CI checkout step, which clones shallow and fetches no tags by default.
+      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.
+      A checkout whose `.git` is a file (a linked worktree, or a repository
+      checked out as a submodule) is the exception: that file points to a git
+      directory outside the build context, so the build cannot read the version
+      and a plain `docker build .` fails; pass the version with
+      `--build-arg VERSION=...`. `script/docker` and `script/cibuild` already
+      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
+      push, checks out with `persist-credentials: false`, and carries the
+      `concurrency` block that lets a new push cancel only the same branch's
+      older run — 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-10-02
+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()
+            if err := s.enableSentry(); err != nil {
-            return nil
+                return err
-        },
+            }
-        OnStop: func(ctx context.Context) error {
+            s.SetupRoutes()
-            // Server shutdown logic
+            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() {
+func (s *Server) newHTTPServer() *http.Server {
-    listenAddr := fmt.Sprintf(":%d", s.params.Config.Port)
+    return &http.Server{
-    s.httpServer = &http.Server{
+        Addr:           fmt.Sprintf(":%d", s.params.Config.Port),
-        Addr:           listenAddr,
         ReadTimeout:    10 * time.Second,
         WriteTimeout:   10 * time.Second,
         MaxHeaderBytes: 1 << 20,
         Handler:        s,
     }
+}
 
-    s.SetupRoutes()
+// 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
-    s.log.Info("http begin listen", "listenaddr", listenAddr)
+// 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 {
+        if err := s.params.Shutdowner.Shutdown(fx.ExitCode(1)); err != nil {
-            s.cancelFunc()
+            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 {
+// cleanShutdown is the server's stop hook. It fails when requests are still
-    s.ctx, s.cancelFunc = context.WithCancel(context.Background())
+// running after 5 seconds.
-
+func (s *Server) cleanShutdown(ctx context.Context) error {
-    // Signal watcher
+    ctxShutdown, shutdownCancel := context.WithTimeout(ctx, 5*time.Second)
-    go func() {
+    defer shutdownCancel()
-        c := make(chan os.Signal, 1)
+    err := s.httpServer.Shutdown(ctxShutdown)
-        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()
     if s.sentryEnabled {
         sentry.Flush(2 * time.Second)
     }
+    if err != nil {
+        return fmt.Errorf("http server shutdown: %w", err)
+    }
+    return nil
 }
 ```
 
@@ -987,8 +983,10 @@ Use ldflags to inject version information at build time:
 # ?= 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.
+# build stage on the `.git` the build context carries. When it prints
-VERSION ?= $(shell git describe --tags --always)
+# 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
@@ -1158,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{
@@ -1170,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)
+        return fmt.Errorf("sentry init failure: %w", err)
-        os.Exit(1)
-        return
     }
     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
@@ -1190,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-10-02
+last_modified: 2026-10-06
 ---
 
 Use this checklist when creating a new repository from scratch. Follow the steps
@@ -34,14 +34,17 @@ Template files can be fetched from:
 ## Fetch Template Files
 
 - [ ] `.gitignore` — fetch from
-      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore`, extend for
+      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore`, then add
-      language-specific artifacts. Extensions are written to `.gitignore`'s own
+      the repo's own build outputs, such as its binaries, at the end of the
-      semantics, where an unanchored pattern already matches at every depth:
+      file, where a re-vendor keeps them. Extensions are written to
-      never add a `**/` prefix here, which is a `.dockerignore` form. The
+      `.gitignore`'s own semantics, where an unanchored pattern already matches
-      canonical file already carries `.claude/` so agent worktrees cannot be
+      at every depth: never add a `**/` prefix here, which is a `.dockerignore`
-      committed by accident.
+      form. The canonical file already carries `.claude/` so agent worktrees
+      cannot be committed by accident.
 - [ ] `.editorconfig` — fetch from
-      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`
+      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`, then
+      add the repo's own sections, such as one for another language it uses, at
+      the end of the file, where a re-vendor keeps them.
 - [ ] `Makefile` — fetch from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`, adapt
       targets for the project's language and tools
@@ -54,6 +57,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
@@ -68,19 +74,35 @@ Template files can be fetched from:
       will run them in subdirectories, `services/api/.claude/` needs its own
       anchored entry.
     - If the image embeds a version in a binary: `.dockerignore` lets `.git`
-      into the build context. It keeps out `.git/config`, which `git describe`
+      into the build context. It keeps out every git `config` at any depth
-      does not need and which can hold a credential: a password in a remote URL,
+      (`**/.git/config`, `**/.git/modules/**/config`): the repository's own,
-      or the token the CI checkout step stores there. The stage that compiles
+      each submodule's under `.git/modules/`, and that of a submodule keeping
-      has `git` (the Debian Go image has it; an alpine one needs
+      its own `.git` directory. `git describe` does not need them, and each can
-      `apk add --no-cache git`) and takes the version from the `VERSION` build
+      hold a credential: a password in a remote URL, or the token the CI
-      argument when one is given, otherwise from `git describe --tags --always`.
+      checkout step stores there. A submodule whose name has a `config` segment
-      That gives the tag on a tagged commit; on a later commit, the tag, the
+      (`config`, `deploy/config`, `config/lib`) loses its whole git directory to
-      number of commits since it and the short commit (`v1.2.3-4-gabc1234`); and
+      `**/.git/modules/**/config`, and Go's version stamping then fails the
-      the short commit when no tag is reachable. `ARG VERSION` has no default,
+      build: give it a name without that segment (`git submodule add --name`).
-      and the build fails if the context carries `.git` and the version still
+      The stage that compiles has `git` (the Debian Go image has it; an alpine
-      comes out empty, `dev` or `unknown`. A plain `docker build .` with no
+      one needs `apk add --no-cache git`) and takes the version from the
-      build arguments must succeed; a Dockerfile that refuses an empty build
+      `VERSION` build argument when one is given, otherwise from
-      argument drops that refusal and keeps the argument.
+      `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.
+      A checkout whose `.git` is a file (a linked worktree, or a repository
+      checked out as a submodule) is the exception: that file points to a git
+      directory outside the build context, so the build cannot read the version
+      and a plain `docker build .` fails; pass the version with
+      `--build-arg VERSION=...`, as `script/docker` and `script/cibuild` already
+      do.
     - 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
@@ -90,11 +112,15 @@ Template files can be fetched from:
     - Non-server: the final stage brings up the dev environment
     - Image pinned by sha256 hash with version/date comment
 - [ ] Gitea Actions workflow at `.gitea/workflows/check.yml` that runs
-      `script/cibuild` on push — reference
+      `script/cibuild` on push, checks out with `persist-credentials: false`,
+      and carries the `concurrency` block that lets a new push cancel only the
+      same branch's older run — reference
       `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`
 
@@ -109,8 +135,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
+      archive; pinned yarn via corepack); a non-server repo's development
-      installs
+      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-10-02
+last_modified: 2026-10-06
 ---
 
 This document covers repository structure, tooling, and workflow standards. Code
@@ -104,18 +104,23 @@ 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`
+  The gate phases and the build stage start from their pinned base images and
-  rather than duplicating installs inline; COPY `script/` and the dependency
+  install what those images lack either inline, as the canonical Go `Dockerfile`
-  manifests (`package.json` + `yarn.lock`, `go.mod` + `go.sum`, etc.) before
+  below does for `git`, or by running `script/bootstrap`, as the `prompts`
-  running it.
+  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
   and nothing else:
 
     ```sh
-    docker build --no-cache --target lint -t "$(script/projectname)-lint" .
+    tag="$(script/projectname)"
-    docker build --no-cache --target test -t "$(script/projectname)-test" .
+    docker build --no-cache --target lint -t "$tag-lint" .
+    docker build --no-cache --target test -t "$tag-test" .
     ```
 
     **A stage that is not the last one in the file is built only when the final
@@ -128,7 +133,9 @@ style conventions are in separate documents:
     **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.
+    runner; a tagged one replaces the previous image. Each script assigns the
+    tag on its own line before the build, so `set -e` stops it where
+    `script/projectname` fails.
 
     Inside a phase the tool is invoked directly — `golangci-lint`, `go test`,
     `eslint`, `prettier` — never through `make lint` or `script/test`, which are
@@ -156,11 +163,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 +183,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 ./
@@ -192,6 +203,8 @@ style conventions are in separate documents:
     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
@@ -233,31 +246,67 @@ 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.
+    - If the project requires CGO or system libraries for linting, install them
-      `vips-dev`), install them in the lint phase with `apk add`.
+      in the lint phase. The `golangci/golangci-lint` image is Debian-based and
-    - `.dockerignore` lets `.git` into the build context. It keeps out
+      has no `apk`, so install with `apt-get` under the Debian package name
-      `.git/config`, which `git describe` does not need and which can hold a
+      (`libvips-dev`, where alpine says `vips-dev`), and delete the package
-      credential: a password in a remote URL, or the token the CI checkout step
+      lists in the same `RUN`, so the layer does not keep them:
-      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
+        ```dockerfile
-      from the `VERSION` build argument when one is given, otherwise from
+        RUN apt-get update \
-      `git describe --tags --always`. That gives the tag on a tagged commit; on
+            && apt-get install -y --no-install-recommends libvips-dev \
-      a later commit, the tag, the number of commits since it and the short
+            && rm -rf /var/lib/apt/lists/*
-      commit (`v1.2.3-4-gabc1234`); and the short commit when no tag is
+        ```
-      reachable. `ARG VERSION` has no default, and the build fails if the
+
-      context carries `.git` and the version still comes out empty, `dev` or
+    - `.dockerignore` lets `.git` into the build context. It keeps out every git
-      `unknown`. A plain `docker build .` with no build arguments must succeed;
+      `config` at any depth (`**/.git/config`, `**/.git/modules/**/config`): the
-      a Dockerfile that refuses an empty build argument drops that refusal and
+      repository's own, each submodule's under `.git/modules/`, and that of a
-      keeps the argument.
+      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.
+      A checkout whose `.git` is a file (a linked worktree, or a repository
+      checked out as a submodule) is the exception: that file points to a git
+      directory outside the build context, so the build cannot read the version
+      and a plain `docker build .` fails; pass the version with
+      `--build-arg VERSION=...`, as `script/docker` and `script/cibuild` already
+      do.
 
 - 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.
+  runs `script/cibuild` on push, and checks out the repo as its only other step,
-  That script bootstraps, runs the gate phases, and then builds the image, so a
+  with `persist-credentials: false`: `script/cibuild` needs no token, and
-  successful run means every check passed; a bare `docker build .` does not
+  without it the checkout leaves the job's token in `.git/config` for every
+  later step. Its `concurrency` block groups runs by workflow and branch
+  (`${{ github.workflow }}-${{ github.ref }}`) with `cancel-in-progress: true`,
+  so a new push cancels the older run on the same branch, queued or running, and
+  no other: runs for replaced commits do not hold up the shared runner.
+  `script/cibuild` bootstraps, runs the gate phases, and then builds the image,
+  so a 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.
+  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
@@ -310,17 +359,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:
 
@@ -348,9 +399,12 @@ style conventions are in separate documents:
 
 - `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
   editor files (`.swp`, `*~`), in-repo agent scratch directories (`.claude/`),
-  language build artifacts, and `node_modules/`. Fetch the standard `.gitignore`
+  `node_modules/`, and the repo's own build outputs. Fetch the standard
-  from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when
+  `.gitignore` from
-  setting up a new repo. These patterns are written to `.gitignore`'s own
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up
+  a new repo. A repo's `.gitignore` is the standard file followed by the repo's
+  own entries, such as its binaries; a re-vendor replaces the standard part and
+  keeps those entries. 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.
 
@@ -398,13 +452,15 @@ style conventions are in separate documents:
   byte-identically across repos:
 
     ```sh
-    # Own line: a failing command substitution inside an argument does not
+    # The version and the tag each get their own line: a failing command
-    # trip `set -e`, so the inline form degrades to an empty constant.
+    # 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"
+    tag="$(script/projectname)"
     docker build --no-cache \
         --build-arg VERSION="$version" \
-        -t "$(script/projectname)" .
+        -t "$tag" .
     ```
 
     `--always` makes an untagged repo yield an abbreviated commit hash rather
@@ -451,12 +507,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
@@ -480,6 +542,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).
 
@@ -589,13 +656,17 @@ style conventions are in separate documents:
       Never edit existing migrations after release.
 
 - All repos should have an `.editorconfig` enforcing the project's indentation
-  settings.
+  settings: the standard file from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`, which sets
+  tabs for `Makefile` and Go files, followed by the repo's own sections, such as
+  one for another language it uses. A re-vendor replaces the standard part and
+  keeps those sections.
 
 - 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; thin only: one `main.go` per binary whose
       body is a single call into `internal/` or `pkg/`, no project logic in
@@ -626,3 +697,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

@@ -14,15 +14,17 @@ main() {
     cd "$ROOT"
     "$SCRIPT_DIR/bootstrap"
     "$SCRIPT_DIR/check"
-    # Own line: a failing command substitution inside an argument does
+    # The version and the tag each get their own line: a failing
-    # not trip `set -e`, so the inline form degrades silently to an
+    # command substitution inside an argument does not trip `set -e`,
-    # empty constant. The VERSION build argument takes precedence over
+    # so the inline form degrades silently to an empty constant. The
-    # the version a build stage derives from the .git in the context.
+    # 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"
+    tag="$("$SCRIPT_DIR/projectname")"
     docker build --no-cache \
         --build-arg VERSION="$version" \
-        -t "$("$SCRIPT_DIR/projectname")" .
+        -t "$tag" .
 }
 
 main "$@"

script/docker

@@ -10,15 +10,17 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    # Own line: a failing command substitution inside an argument does
+    # The version and the tag each get their own line: a failing
-    # not trip `set -e`, so the inline form degrades silently to an
+    # command substitution inside an argument does not trip `set -e`,
-    # empty constant. The VERSION build argument takes precedence over
+    # so the inline form degrades silently to an empty constant. The
-    # the version a build stage derives from the .git in the context.
+    # 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"
+    tag="$("$SCRIPT_DIR/projectname")"
     docker build --no-cache \
         --build-arg VERSION="$version" \
-        -t "$("$SCRIPT_DIR/projectname")" .
+        -t "$tag" .
 }
 
 main "$@"

script/lint

@@ -15,9 +15,13 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
+    # The tag gets its own line: a failing command substitution inside
+    # an argument does not trip `set -e`, so the inline form degrades
+    # silently to an empty constant.
+    tag="$("$SCRIPT_DIR/projectname")"
     docker build --no-cache \
         --target lint \
-        -t "$("$SCRIPT_DIR/projectname")-lint" .
+        -t "$tag-lint" .
 }
 
 main "$@"

script/test

@@ -11,9 +11,13 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
+    # The tag gets its own line: a failing command substitution inside
+    # an argument does not trip `set -e`, so the inline form degrades
+    # silently to an empty constant.
+    tag="$("$SCRIPT_DIR/projectname")"
     docker build --no-cache \
         --target test \
-        -t "$("$SCRIPT_DIR/projectname")-test" .
+        -t "$tag-test" .
 }
 
 main "$@"