Set the lint digest and .golangci.yml together; state the Go version rule

The canonical .golangci.yml now names exhaustruct_v5, which v2.12.2
rejects, so a repo that re-vendors the file on the old digest gets a
lint phase that fails before checking any code. REPO_POLICIES now says
a repo sets the lint phase digest and re-vendors .golangci.yml in one
commit, whichever prompted the change, and both repo checklists point
to that rule. It also replaces "a new Go version needs a golangci-lint
built with it" with the rule golangci-lint applies: the go directive
must not name a newer Go minor version than the one it was built with.

Model: opus-5-5

.dockerignore

@@ -17,10 +17,7 @@
 # stage that compiles runs `git describe --tags --always` on .git, which
 # does not need .git/config; that file can hold a credential, such as a
 # password in a remote URL or the token the CI checkout step stores there.
-# Each submodule keeps a config with the same exposure in its git directory
-# under .git/modules/, nested again for a submodule's own submodules.
 .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.
@@ -44,9 +41,7 @@
 **/[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

.gitignore

@@ -42,6 +42,4 @@ node_modules/
 [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]

TODO.md

@@ -21,62 +21,6 @@ fmt-check, and commit.
 
 # Completed Steps
 
-- 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

package.json

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

prompts/CODE_STYLEGUIDE_GO.md

@@ -1,6 +1,6 @@
 ---
 title: Code Styleguide — Go
-last_modified: 2026-10-04
+last_modified: 2026-10-02
 ---
 
 1.  Try to hard wrap long lines at 77 characters or less.
@@ -51,10 +51,8 @@ last_modified: 2026-10-04
     # ?= rather than := so that a `VERSION` build argument takes precedence:
     # where a build stage invokes make, `ARG VERSION` puts it in the
     # environment and `?=` defers to it. Otherwise `git describe` runs, in a
-    # build stage on the `.git` the build context carries. When it prints
-    # nothing (outside a git checkout, or where git is missing or refuses the
-    # checkout), the version falls back to `dev`.
-    VERSION ?= $(or $(shell git describe --tags --always 2>/dev/null),dev)
+    # build stage on the `.git` the build context carries.
+    VERSION ?= $(shell git describe --tags --always)
 
     GOLDFLAGS += -X main.Version=$(VERSION)
 

prompts/EXISTING_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: Existing Repo Checklist
-last_modified: 2026-10-04
+last_modified: 2026-10-03
 ---
 
 Use this checklist when beginning work in a repo that may not yet conform to our
@@ -24,10 +24,6 @@ with your task.
 - [ ] `LICENSE` file exists and matches the README
 - [ ] `REPO_POLICIES.md` exists and version date is current — fetch from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md`
-- [ ] Guidance for coding agents, if the repo has any, is one `AGENTS.md` at the
-      root — never a file or directory named after one agent tool, such as
-      `CLAUDE.md` or `.claude/`, and never separate memory files. Move what any
-      such committed file says into `AGENTS.md` and delete it.
 - [ ] `.gitignore` is comprehensive (OS, editor, agent scratch, language
       artifacts, secrets) — fetch from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` if missing.
@@ -63,28 +59,22 @@ 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` and each submodule's
-      `config` under `.git/modules/` at any depth (`.git/modules/**/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.
-      `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.
+      the build context. It keeps out `.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. `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`

prompts/GO_HTTP_SERVER_CONVENTIONS.md

@@ -1,6 +1,6 @@
 ---
 title: Go HTTP Server Conventions
-last_modified: 2026-10-04
+last_modified: 2026-10-02
 ---
 
 This document defines the architectural patterns, design decisions, and
@@ -106,9 +106,6 @@ project-root/
 package main
 
 import (
-    "os/signal"
-    "syscall"
-
     "yourproject/internal/config"
     "yourproject/internal/database"
     "yourproject/internal/globals"
@@ -129,9 +126,6 @@ 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,
@@ -204,8 +198,7 @@ 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, and on `fx.Shutdowner`, which fx
-   provides itself)
+8. `server.New` - Server (depends on all above)
 
 ---
 
@@ -224,14 +217,16 @@ 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
@@ -253,15 +248,13 @@ func New(lc fx.Lifecycle, params ServerParams) (*Server, error) {
     lc.Append(fx.Hook{
         OnStart: func(ctx context.Context) error {
             s.startupTime = time.Now()
-            if err := s.enableSentry(); err != nil {
-                return err
-            }
-            s.SetupRoutes()
-            s.httpServer = s.newHTTPServer()
-            go s.serveUntilShutdown()
+            go s.Run()
+            return nil
+        },
+        OnStop: func(ctx context.Context) error {
+            // Server shutdown logic
             return nil
         },
-        OnStop: s.cleanShutdown,
     })
     return s, nil
 }
@@ -271,25 +264,23 @@ func New(lc fx.Lifecycle, params ServerParams) (*Server, error) {
 
 ```go
 // internal/server/http.go
-func (s *Server) newHTTPServer() *http.Server {
-    return &http.Server{
-        Addr:           fmt.Sprintf(":%d", s.params.Config.Port),
+func (s *Server) serveUntilShutdown() {
+    listenAddr := fmt.Sprintf(":%d", s.params.Config.Port)
+    s.httpServer = &http.Server{
+        Addr:           listenAddr,
         ReadTimeout:    10 * time.Second,
         WriteTimeout:   10 * time.Second,
         MaxHeaderBytes: 1 << 20,
         Handler:        s,
     }
-}
 
-// serveUntilShutdown returns when the stop hook shuts the HTTP server down.
-// If it stops for any other reason, such as its port being taken, it asks fx
-// to shut down with exit code 1.
-func (s *Server) serveUntilShutdown() {
-    s.log.Info("http begin listen", "listenaddr", s.httpServer.Addr)
+    s.SetupRoutes()
+
+    s.log.Info("http begin listen", "listenaddr", listenAddr)
     if err := s.httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed {
         s.log.Error("listen error", "error", err)
-        if err := s.params.Shutdowner.Shutdown(fx.ExitCode(1)); err != nil {
-            s.log.Error("shutdown request failed", "error", err)
+        if s.cancelFunc != nil {
+            s.cancelFunc()
         }
     }
 }
@@ -301,30 +292,43 @@ 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
-// cleanShutdown is the server's stop hook. It fails when requests are still
-// running after 5 seconds.
-func (s *Server) cleanShutdown(ctx context.Context) error {
-    ctxShutdown, shutdownCancel := context.WithTimeout(ctx, 5*time.Second)
-    defer shutdownCancel()
-    err := s.httpServer.Shutdown(ctxShutdown)
+func (s *Server) serve() int {
+    s.ctx, s.cancelFunc = context.WithCancel(context.Background())
+
+    // Signal watcher
+    go func() {
+        c := make(chan os.Signal, 1)
+        signal.Ignore(syscall.SIGPIPE)
+        signal.Notify(c, os.Interrupt, syscall.SIGTERM)
+        sig := <-c
+        s.log.Info("signal received", "signal", sig)
+        if s.cancelFunc != nil {
+            s.cancelFunc()
+        }
+    }()
+
+    go s.serveUntilShutdown()
+
+    for range s.ctx.Done() {
+    }
+    s.cleanShutdown()
+    return s.exitCode
+}
+
+func (s *Server) cleanShutdown() {
+    s.exitCode = 0
+    ctxShutdown, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second)
+    if err := s.httpServer.Shutdown(ctxShutdown); err != nil {
+        s.log.Error("server clean shutdown failed", "error", err)
+    }
+    if shutdownCancel != nil {
+        shutdownCancel()
+    }
+    s.cleanupForExit()
     if s.sentryEnabled {
         sentry.Flush(2 * time.Second)
     }
-    if err != nil {
-        return fmt.Errorf("http server shutdown: %w", err)
-    }
-    return nil
 }
 ```
 
@@ -983,10 +987,8 @@ 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. When it prints
-# nothing (outside a git checkout, or where git is missing or refuses the
-# checkout), the version falls back to `dev`.
-VERSION ?= $(or $(shell git describe --tags --always 2>/dev/null),dev)
+# build stage on the `.git` the build context carries.
+VERSION ?= $(shell git describe --tags --always)
 
 build:
     go build -ldflags "-X main.Version=$(VERSION)" ./cmd/httpd
@@ -1156,11 +1158,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() error {
+func (s *Server) enableSentry() {
     s.sentryEnabled = false
 
     if s.params.Config.SentryDSN == "" {
-        return nil
+        return
     }
 
     err := sentry.Init(sentry.ClientOptions{
@@ -1168,17 +1170,15 @@ func (s *Server) enableSentry() error {
         Release: fmt.Sprintf("%s-%s", s.params.Globals.Appname, s.params.Globals.Version),
     })
     if err != nil {
-        return fmt.Errorf("sentry init failure: %w", err)
+        s.log.Error("sentry init failure", "error", 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 in the server's stop hook, `cleanShutdown()`:
+Flush Sentry on shutdown:
 
 ```go
 if s.sentryEnabled {

prompts/NEW_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: New Repo Checklist
-last_modified: 2026-10-04
+last_modified: 2026-10-03
 ---
 
 Use this checklist when creating a new repository from scratch. Follow the steps
@@ -54,9 +54,6 @@ 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
@@ -71,24 +68,19 @@ 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` and each submodule's
-      `config` under `.git/modules/` at any depth (`.git/modules/**/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.
+      into the build context. It keeps out `.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. `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

prompts/REPO_POLICIES.md

@@ -1,6 +1,6 @@
 ---
 title: Repository Policies
-last_modified: 2026-10-04
+last_modified: 2026-10-03
 ---
 
 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 Debian Go image. The canonical Go repo
+  and the test phase is based on the Go image. The canonical Go repo
   `Dockerfile`:
 
     ```dockerfile
@@ -173,9 +173,8 @@ style conventions are in separate documents:
     COPY . .
     RUN golangci-lint run --config .golangci.yml ./...
 
-    # Test phase. -race needs cgo and so a C compiler, which the Debian Go
-    # image ships and the alpine one does not.
-    # golang:1.x, YYYY-MM-DD
+    # Test phase
+    # golang:1.x-alpine, YYYY-MM-DD
     FROM golang@sha256:... AS test
     WORKDIR /src
     COPY go.mod go.sum ./
@@ -193,8 +192,6 @@ 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
@@ -236,36 +233,22 @@ 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, install them
-      in the lint phase. The `golangci/golangci-lint` image is Debian-based and
-      has no `apk`, so install with `apt-get` under the Debian package name
-      (`libvips-dev`, where alpine says `vips-dev`), and delete the package
-      lists in the same `RUN`, so the layer does not keep them:
-
-        ```dockerfile
-        RUN apt-get update \
-            && apt-get install -y --no-install-recommends libvips-dev \
-            && rm -rf /var/lib/apt/lists/*
-        ```
-
+    - If the project requires CGO or system libraries for linting (e.g.
+      `vips-dev`), install them in the lint phase with `apk add`.
     - `.dockerignore` lets `.git` into the build context. It keeps out
-      `.git/config` and each submodule's `config` under `.git/modules/` at any
-      depth (`.git/modules/**/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.
+      `.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. `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.
@@ -327,19 +310,17 @@ style conventions are in separate documents:
     ```
 
     `-count=1` is required on both invocations: it defeats Go's test _result_
-    cache, so neither run can report a stored pass in place of running the
-    tests. It leaves the build cache alone, so it costs the runtime of the suite
-    and no recompilation.
+    cache, so the target cannot report a pass it did not earn, and the rerun
+    reproduces a failure instead of replaying it. It leaves the build cache
+    alone, so it costs the runtime of the suite and no recompilation.
 
-    That cache is Go's own, separate from Docker's layer cache. Go stores a
-    passing result in its cache directory (`GOCACHE`), and when the same tests
-    run again on unchanged code it prints that result, marked `(cached)`,
-    without running them. That matters on a developer's machine, where this
-    target runs and the directory lasts from one run to the next. The `test`
-    phase of the `Dockerfile` needs no `-count=1`: its base image holds no
-    result for this repo's tests and nothing before its `go test` step runs a
-    test, so there is nothing to replay. `--no-cache` (above) is what makes that
-    step run on an unchanged tree.
+    Note that this is a second, independent cache, stacked below the Docker
+    layer cache that [issue #26](https://git.eeqj.de/sneak/prompts/issues/26)
+    addresses. `CHECK_EPOCH` guarantees the `RUN make test` _step_ re-executes;
+    it does not guarantee `go test` inside that step does any work, because the
+    `GOCACHE` baked into earlier image layers survives into the re-executed
+    step. They are two separate defects requiring two separate fixes, and a fix
+    for one must not be recorded as covering the other.
 
     Python example:
 
@@ -505,11 +486,6 @@ 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).
 
@@ -622,10 +598,10 @@ style conventions are in separate documents:
   settings.
 
 - Avoid putting files in the repo root unless necessary. Root should contain
-  only project-level config files (`README.md`, `AGENTS.md`, `Makefile`,
-  `Dockerfile`, `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`,
-  and language-specific config). Everything else goes in a subdirectory.
-  Canonical subdirectory names:
+  only project-level config files (`README.md`, `Makefile`, `Dockerfile`,
+  `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, and
+  language-specific config). Everything else goes in a subdirectory. Canonical
+  subdirectory names:
     - `bin/` — executable scripts and tools
     - `cmd/` — Go command entrypoints; thin only: one `main.go` per binary whose
       body is a single call into `internal/` or `pkg/`, no project logic in
@@ -656,7 +632,3 @@ 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.