Install node, yarn and python from the distribution (closes #146)

Follows sneak's ruling at
#146 (comment). Runtimes
and the installer tools bundled with python come from the distribution,
with no version and no hash. Third-party packages stay pinned by hash.

script/bootstrap drops nvm and corepack. It installs node, yarn and the
node packages only when yarn.lock is in the tree, and stops there when
yarn's major version is not 1. This repository's Dockerfile starts from
Alpine 3.24. The Python example starts from debian:trixie-slim, keeps
pipenv at $HOME/.pipenv on a host and in an image, and sets
PIP_ONLY_BINARY=:all:, so pip downloads no build tools without a hash
check.

Model: opus-5-5

.dockerignore

@@ -13,9 +13,21 @@
 # `/myapp`, never `**/myapp`, which also matches `cmd/myapp/` and
 # deletes the package directory from the context.
 
-# Excluding .git means `git describe` cannot run in any build stage and
+# .git is sent without its config. Without a VERSION build argument the
-# fails quietly there; pass the version in with --build-arg VERSION.
+# stage that compiles runs `git describe --tags --always` on .git, which
-.git
+# does not need .git/config; that file can hold a credential, such as a
+# password in a remote URL or the token the CI checkout step stores there.
+# Each submodule keeps a config with the same exposure in its git directory
+# under .git/modules/, nested again for a submodule's own submodules, or in
+# its own .git directory when it keeps one.
+# KNOWN GAP: a submodule whose name has a `config` segment (`config`,
+# `deploy/config`, `config/lib`) loses its whole git directory, because
+# `**/.git/modules/**/config` also matches that segment's directory
+# under .git/modules/. Go's version stamping then fails the build;
+# nothing leaks. Name such a submodule without that segment:
+# `git submodule add --name`.
+**/.git/config
+**/.git/modules/**/config
 
 # Agent scratch: one full checkout of the repo per in-flight agent.
 # Anchored because it occurs once where agents run at the repo root.
@@ -39,7 +51,9 @@
 **/[iI][dD]_[rR][sS][aA]
 **/[iI][dD]_[dD][sS][aA]
 **/[iI][dD]_[eE][cC][dD][sS][aA]
+**/[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK]
 **/[iI][dD]_[eE][dD]25519
+**/[iI][dD]_[eE][dD]25519_[sS][kK]
 
 # Dependencies: restored inside the image, never copied in.
 **/node_modules

.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,20 @@
 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
+        # Free the shared runner from a hung build.
+        timeout-minutes: 20
         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
+                  # All history and tags, so git describe finds the version tag.
+                  fetch-depth: 0
             - 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

@@ -3,6 +3,9 @@ version: "2"
 # Config schema uses the golangci-lint v2 layout (settings live under
 # linters.settings, not top-level linters-settings) so that the
 # thresholds below are actually applied by golangci-lint >= v2.
+#
+# This file has no formatters section, so golangci-lint run does not run
+# gofmt. A repository's script/fmt-check runs it, on the host.
 
 run:
   timeout: 5m
@@ -16,12 +19,13 @@ linters:
     - gomodguard_v2
   disable:
     # Genuinely incompatible with project patterns
-    - exhaustruct      # Requires all struct fields
+    - exhaustruct_v5   # Requires all struct fields
     - godot            # Requires comments to end with periods
     - wrapcheck        # Too verbose for internal packages
     - varnamelen       # Short names like db, id are idiomatic Go
     # Deprecated: the warning is attached to the old name, so it is
     # silenced by disabling that name, not by enabling the successor.
+    - exhaustruct      # Deprecated, replaced by exhaustruct_v5
     - wsl              # Deprecated, replaced by wsl_v5
     - gomodguard       # Deprecated, replaced by gomodguard_v2
   settings:
@@ -39,7 +43,10 @@ linters:
       # test-support package exists to hand a test privileges the program
       # itself must never have, so a file that is not a test must not import
       # one. Test files, and the files inside a package whose directory name
-      # ends in `test`, are where that code belongs, and are exempt.
+      # ends in `test`, are where that code belongs, and are exempt. A package
+      # in a subdirectory of that directory is not exempt. `${base-path}` is
+      # the directory holding this file, so the name of the directory a
+      # repository is cloned into does not count.
       #
       # The deny list below is the one part of this file a repository is
       # expected to extend, and the only part it may. depguard matches an
@@ -54,24 +61,25 @@ linters:
           files:
             - "$all"
             - "!$test"
-            - "!**/*test/**"
+            - "!${base-path}**/*test/*"
           deny:
             - pkg: net/http/httptest
               desc: >-
                 Test-support code belongs in test files and in packages whose
                 directory name ends in test, not in the shipped binary.
-    # Only decisions already recorded in the Go package defaults are
+    # Each entry names a module not to use and what to use instead. Every
-    # listed here. Every entry matches the module path exactly.
+    # entry matches the module path exactly.
     gomodguard_v2:
       blocked:
         - module: github.com/rs/zerolog
           recommendations:
             - log/slog
           reason: "Structured logging is stdlib log/slog."
-        # One entry per pre-fork module path, because the later releases
+        # These entries cover only the github.com/go-redis/redis module paths,
-        # are separate paths. A prefix match would be shorter but would
+        # one entry per path, because the later releases are separate paths.
-        # also reach github.com/go-redis/redismock, the test double for
+        # A prefix match would be shorter but would also reach
-        # the successor these entries recommend.
+        # github.com/go-redis/redismock/v9, the test double for the successor
+        # these entries recommend.
         - module: github.com/go-redis/redis
           recommendations:
             - github.com/redis/go-redis/v9
@@ -84,6 +92,10 @@ linters:
           recommendations:
             - github.com/redis/go-redis/v9
           reason: "Pre-fork module; use the maintained go-redis v9."
+        - module: github.com/go-redis/redis/v9
+          recommendations:
+            - github.com/redis/go-redis/v9
+          reason: "Pre-fork module; use the maintained go-redis v9."
         - module: github.com/sergi/go-diff
           recommendations:
             - github.com/aymanbagabas/go-udiff
@@ -92,7 +104,19 @@ linters:
           recommendations:
             - github.com/aymanbagabas/go-udiff
           reason: "Unmaintained fork; use go-udiff."
+  exclusions:
+    rules:
+      # homoicon keeps a local copy of sobek, its JavaScript engine, as sneak
+      # decided in
+      # https://git.eeqj.de/sneak/homoicon/issues/1759#issuecomment-153261.
+      # This is an exclusion because gomoddirectives does not check its
+      # replace-allow-list for a replace that points at a local path.
+      - path: ^go\.mod$
+        linters:
+          - gomoddirectives
+        text: '^local replacement are not allowed: github\.com/grafana/sobek$'
 
 issues:
   max-issues-per-linter: 0
   max-same-issues: 0
+  uniq-by-line: false

Dockerfile

@@ -2,8 +2,16 @@
 # lint` or `script/lint`, which are themselves a docker build and would
 # recurse into a daemon that does not exist in a build step.
 #
-# node 22-alpine, 2026-02-22
+# In every stage, ARG CACHEBUST comes right after the step that installs
-FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS lint
+# system packages. script/ passes a new value on every build. That value
+# reruns every RUN step below the ARG line, and the install step keeps
+# its layer. node and yarn come from the distribution, which is trusted,
+# so they need no version and no hash.
+#
+# alpine 3.24.3, 2026-11-04
+FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS lint
+RUN apk add --no-cache git make nodejs yarn
+ARG CACHEBUST
 
 WORKDIR /app
 
@@ -17,8 +25,10 @@ RUN yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always
 
 # Test phase, same shape and for the same reason.
 #
-# node 22-alpine, 2026-02-22
+# alpine 3.24.3, 2026-11-04
-FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS test
+FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS test
+RUN apk add --no-cache git make nodejs yarn
+ARG CACHEBUST
 
 WORKDIR /app
 
@@ -36,23 +46,26 @@ RUN echo "No tests defined."
 # this image cannot be produced unless lint and test passed. A stage
 # appended after this one would drop all three out of a plain build.
 #
-# node 22-alpine, 2026-02-22
+# alpine 3.24.3, 2026-11-04
-FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34
+FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a
+RUN apk add --no-cache git make nodejs yarn
+ARG CACHEBUST
 
 WORKDIR /app
 
 COPY --from=lint /app/package.json /dev/null
 COPY --from=test /app/package.json /dev/null
 
-# script/bootstrap installs all prerequisites. Manifests are copied
+# script/bootstrap finds the system packages above and installs the node
-# first so that layer stays cached until dependencies change.
+# packages.
 COPY script/ script/
 COPY package.json yarn.lock ./
 RUN script/bootstrap
 
 COPY . .
 
-# The version is computed on the host and passed in, because
+# Nothing here is compiled and a LABEL cannot run git, so the version is
-# .dockerignore excludes .git.
+# the VERSION build argument that script/docker and script/cibuild pass;
-ARG VERSION=dev
+# a plain `docker build .` leaves it empty.
+ARG VERSION
 LABEL org.opencontainers.image.version="${VERSION}"

README.md

@@ -37,9 +37,9 @@ new repo file added, etc.)."
 **Code style and conventions:**
 
 ```bash
-claude "Read $TD/prompts/CODE_STYLEGUIDE.md and whichever
+claude "Read $TD/prompts/CODE_STYLEGUIDE.md and whichever other
-language-specific styleguides in $TD/prompts/ apply to this repo
+documents in $TD/prompts/ apply to this repo (API_POLICIES.md,
-(CODE_STYLEGUIDE_GO.md, CODE_STYLEGUIDE_JS.md, CODE_STYLEGUIDE_PYTHON.md,
+CODE_STYLEGUIDE_GO.md, CODE_STYLEGUIDE_JS.md, CODE_STYLEGUIDE_PYTHON.md,
 GO_HTTP_SERVER_CONVENTIONS.md). Then review the application code in this
 repo and bring it into compliance with those coding standards. Your scope
 is application code structure and style: naming, patterns, error
@@ -79,9 +79,9 @@ one for linter fixes, one for README, one for each new repo file, etc.)."
 **Code style and conventions:**
 
 ```bash
-claude "Read $TD/prompts/CODE_STYLEGUIDE.md and whichever
+claude "Read $TD/prompts/CODE_STYLEGUIDE.md and whichever other
-language-specific styleguides in $TD/prompts/ apply to this repo
+documents in $TD/prompts/ apply to this repo (API_POLICIES.md,
-(CODE_STYLEGUIDE_GO.md, CODE_STYLEGUIDE_JS.md, CODE_STYLEGUIDE_PYTHON.md,
+CODE_STYLEGUIDE_GO.md, CODE_STYLEGUIDE_JS.md, CODE_STYLEGUIDE_PYTHON.md,
 GO_HTTP_SERVER_CONVENTIONS.md). Then review the application code in this
 repo and bring it into compliance with those coding standards. Your scope
 is application code structure and style: naming, patterns, error
@@ -116,24 +116,27 @@ alpine. We provide:
   `script/bootstrap`, then `script/install-precommit`
 - `script/projectname` — output the project name (our own extension); used by
   `script/docker` for the image tag
-- `script/test` — `docker build --no-cache --target test -t prompts-test .`,
+- `script/test` —
-  building the `test` phase of the `Dockerfile` (no tests defined here)
+  `docker build --build-arg CACHEBUST="$(date +%s)-$$" --target test --output type=cacheonly .`,
-- `script/lint` — `docker build --no-cache --target lint -t prompts-lint .`,
+  building the `test` phase of the `Dockerfile` without writing an image (no
-  building the `lint` phase, which runs prettier over the markdown files
+  tests defined here)
+- `script/lint` —
+  `docker build --build-arg CACHEBUST="$(date +%s)-$$" --target lint --output type=cacheonly .`,
+  building the `lint` phase, which runs prettier over the markdown files,
+  without writing an image
 - `script/fmt` — format all markdown files with prettier (writes; native, not in
   a container)
 - `script/fmt-check` — check formatting (read-only; native)
 - `script/check` — run all checks: `test`, `lint`, `fmt-check` (our own
   extension); builds no image of its own
 - `script/docker` —
-  `docker build --no-cache --build-arg VERSION="$version" -t prompts .`, the tag
+  `docker build --build-arg CACHEBUST="$(date +%s)-$$" --build-arg VERSION="$version" -t prompts .`,
-  coming from `script/projectname` (byte-identical across repos)
+  the tag coming from `script/projectname` (byte-identical across repos)
 - `script/cibuild` — cd to the repo root, run `script/bootstrap`, run
   `script/check`, compute `version` from `git describe`, then
-  `docker build --no-cache --build-arg VERSION="$version" -t prompts .` (what CI
+  `docker build --build-arg CACHEBUST="$(date +%s)-$$" --build-arg VERSION="$version" -t prompts .`
-  runs; it bootstraps because CI checks out and runs this alone while
+  (what CI runs; it bootstraps because CI checks out and runs this alone while
-  `script/fmt-check` is native, and the version is computed on the host because
+  `script/fmt-check` is native)
-  `.dockerignore` excludes `.git`)
 - `script/precommit` — run by the git pre-commit hook (our own extension); calls
   `script/check`
 - `script/install-precommit` — installs the git pre-commit hook (our own
@@ -141,6 +144,23 @@ alpine. We provide:
 
 `make hooks` installs the pre-commit hook that runs `script/precommit`.
 
+In every stage of a `Dockerfile`, every step that lints, tests or compiles comes
+after `ARG CACHEBUST`. `ARG CACHEBUST` comes right after these steps:
+
+- the steps that install system packages
+- the steps that download Go's modules
+- the step that runs `script/bootstrap` to install a Python `test` phase's
+  packages from `Pipfile.lock`
+
+A stage with none of these steps declares `ARG CACHEBUST` right after `FROM`.
+The `script/` builds pass a new `CACHEBUST` value on every build, which reruns
+every `RUN` step after that line and leaves the layers above it and the cache
+mounts in place; `--no-cache` would build those layers again and empty the
+mounts. This repo's own `Dockerfile` installs git, make, node and yarn right
+after `FROM` in every stage, above `ARG CACHEBUST`. `script/bootstrap` installs
+the node packages below that line, because check builds keep system packages but
+not node packages.
+
 ## Rationale
 
 LLM prompts, especially development policies, benefit from version control and a

TODO.md

@@ -21,6 +21,329 @@ fmt-check, and commit.
 
 # Completed Steps
 
+- 2026-11-04: node, yarn, npm, python, pip and venv now come from the
+  distribution with no version and no hash
+  (https://git.eeqj.de/sneak/prompts/issues/146), on sneak's ruling at
+  https://git.eeqj.de/sneak/prompts/issues/146#issuecomment-166033. Third-party
+  packages stay pinned by hash. These changed:
+    - `script/bootstrap` no longer uses nvm or corepack, and stops when yarn's
+      major version is not 1.
+    - `script/bootstrap` installs node, yarn and the node packages only when
+      `yarn.lock` is in the tree.
+    - `script/bootstrap`, `script/fmt` and `script/fmt-check` run `yarn` or
+      `yarnpkg`, whichever is present.
+    - This repository's `Dockerfile` starts from Alpine 3.24.
+    - The Python `test` phase example starts from `debian:trixie-slim`.
+    - A Python repository's `script/bootstrap` creates its virtual environment
+      at `$HOME/.pipenv`, so it works on a host and in a `Dockerfile`.
+    - `PIP_ONLY_BINARY=:all:` stops a package with no wheel, so pip downloads no
+      build tools without a hash check.
+- 2026-11-04: Rewrote `prompts/REPO_POLICIES.md` sentence by sentence
+  (https://git.eeqj.de/sneak/prompts/issues/136), on sneak's yes at
+  https://git.eeqj.de/sneak/prompts/issues/136#issuecomment-165193. Every rule
+  keeps its meaning and its place, and `must` and `should` stay as they were.
+  Long sentences are split, comma-chained lists are now bulleted lists, and
+  every reason stays. Code blocks, digests, URLs, file names, commands and
+  quoted strings are unchanged.
+- 2026-11-03: The canonical golangci-lint is now v2.15.0, still built with
+  go1.27.0, so the `go` directive rule is unchanged (issue 142). Repositories
+  pick this up on their next re-vendor. Each item in the canonical
+  `.golangci.yml` was tried on a scratch module. These changed:
+    - `canonicalheader` is enabled again, because v2.15.0 fixes the random
+      misses behind issue 105.
+    - The `depguard` exemption covers only the files directly inside a directory
+      whose name ends in `test`. It used to reach every directory below that one
+      too. The name of the directory a repository is cloned into no longer
+      counts.
+    - `gomodguard_v2` also blocks `github.com/go-redis/redis/v9`, whose
+      pre-releases can still be imported under that path.
+    - `uniq-by-line` is now `false`, so a line that trips two linters reports
+      both findings.
+    - Three comments are corrected:
+        - `exhaustruct` is listed as deprecated.
+        - The test double is named `github.com/go-redis/redismock/v9`.
+        - The claim that every blocked module is in the Go package defaults is
+          gone.
+    - A comment says the file has no `formatters` section, so
+      `golangci-lint run` does not run `gofmt`.
+- 2026-11-03: A package from the distribution's own package index now needs no
+  version and no hash, and pulling that index is allowed
+  (https://git.eeqj.de/sneak/prompts/issues/72), on sneak's answer at
+  https://git.eeqj.de/sneak/prompts/issues/72#issuecomment-165196. The
+  distribution is the pinned base image's in a `Dockerfile` and the host's on a
+  host. It is trusted, and everything else stays pinned by hash. A package
+  source that a `Dockerfile` adds itself does not get the exception. The pinning
+  rule of `REPO_POLICIES.md` and both checklists say so, and the canonical Go
+  `Dockerfile`'s `apk add` line has a comment saying why it is allowed.
+- 2026-11-03: A first test run that timed out now gets no verbose rerun
+  (https://git.eeqj.de/sneak/prompts/issues/61), on sneak's approval at
+  https://git.eeqj.de/sneak/prompts/issues/61#issuecomment-165195. The Go recipe
+  in `REPO_POLICIES.md` looks in the first run's output for
+  `panic: test timed out` or `*** Test killed`, and exits 1 when either is
+  there. The Python `make test` example takes the same `timeout 90 sh -c`
+  wrapper as its `Dockerfile` example. The 60 and 90 second rule and the
+  5-minute rule now say a hung package uses the backstop once. The Go item in
+  both repo checklists now asks for this, so a repository with the old recipe
+  fails it.
+- 2026-10-27: Added `prompts/API_POLICIES.md`
+  (https://git.eeqj.de/sneak/prompts/issues/137). It holds sneak's rule from
+  https://git.eeqj.de/sneak/routewatch/issues/199 that a value in an API
+  response is never a string with a label or unit in it. `REPO_POLICIES.md` and
+  the code style commands in the README name the new file.
+- 2026-10-21: Check builds may now also keep the Python packages a `test` phase
+  installs from `Pipfile.lock` (issue 133), on sneak's ruling in
+  https://git.eeqj.de/sneak/rfscan/issues/80#issuecomment-153437. The install
+  comes before `ARG CACHEBUST`: `COPY script/ script/`,
+  `COPY Pipfile Pipfile.lock ./`, then `RUN script/bootstrap`. In that step
+  `script/bootstrap` installs nothing beyond system packages, pipenv and its
+  dependencies by hash, and the packages from the lockfile. It installs no
+  Python, because the tests use the base image's. `--deploy` installs only what
+  the lockfile names, checks every package against its hashes, and fails when
+  the lockfile is out of date with `Pipfile`. A kept layer holds nothing a new
+  install would refuse. A package built from source and the system packages may
+  differ in a new install. As with Go's modules, the packages are kept in a
+  layer, not a cache mount. The tests still run after `ARG CACHEBUST`, and every
+  other stage still installs its Python packages after it. `REPO_POLICIES.md`
+  gains a short Python `test` phase example, and both checklists and the README
+  state the rule the same way. rfscan picks this up on its next re-vendor.
+- 2026-10-21: The canonical `.golangci.yml` now accepts a local `replace` of
+  `github.com/grafana/sobek` in a repository's root `go.mod` (issue 134), for
+  homoicon, which keeps a local copy of sobek on sneak's decision in
+  https://git.eeqj.de/sneak/homoicon/issues/1759#issuecomment-153261. Every
+  other local `replace` is still refused. It is an exclusion rather than a
+  `replace-allow-list` entry because gomoddirectives does not check that list
+  for a `replace` that points at a local path. homoicon picks this up on its
+  next re-vendor.
+- 2026-10-18: Check builds may now also keep Go's downloaded modules,
+  golangci-lint's cache and the layers that install system packages (issue 130),
+  on sneak's ruling there. In each stage of the canonical Go `Dockerfile`, the
+  system-package install and the module download (`COPY go.mod go.sum ./`,
+  `RUN go mod download`) come before `ARG CACHEBUST`, so Docker keeps them until
+  the base image, the install line, `go.mod` or `go.sum` changes. The modules
+  are kept as a layer, not a cache mount, because Go does not check the files in
+  a cache mount again. `golangci-lint run` also mounts golangci-lint's cache,
+  `/root/.cache/golangci-lint`. Every step that lints, tests or compiles still
+  comes after `ARG CACHEBUST` and runs on every check build, and both `go test`
+  runs keep `-count=1`. `REPO_POLICIES.md`, both checklists, the Go style guide,
+  the README and the script comments state the rule the same way. This repo's
+  own `Dockerfile` is unchanged: its `script/bootstrap` step also installs node
+  packages, which the ruling does not cover. Repositories pick this up on their
+  next re-vendor.
+- 2026-10-15: Check builds now keep Go's build cache between runs (issue 113),
+  on sneak's ruling there that Go's compile cache may survive. `script/lint`,
+  `script/test`, `script/cibuild` and `script/docker` pass a new `CACHEBUST`
+  build argument on every build in place of `--no-cache`, which also emptied the
+  cache mounts. Every `Dockerfile` stage declares `ARG CACHEBUST` first, so
+  every `RUN` step still runs on every check build. The canonical Go
+  `Dockerfile` mounts Go's build cache on the steps that compile and runs both
+  `go test` runs with `-count=1`, so no test result is reused. A stage without
+  the `ARG` line is served from cache, so repositories re-vendor the scripts and
+  the `ARG` lines in one commit. Not yet tried on the shared runner.
+- 2026-10-08: The canonical `script/bootstrap` now uses the installed node only
+  when its major version is the pinned one (issue 118). Otherwise, as when node
+  is missing, it installs the pinned node under nvm and installs yarn and the
+  packages under it. It prints the version of the node it uses either way. The
+  CI runner image ships node 24, under which the pinned yarn 1.22.22 printed the
+  deprecation warning DEP0169 on every bootstrap. Only the major is compared
+  because the `Dockerfile` stages start from a node 22 alpine image whose exact
+  version is not the pin, and nvm cannot install a prebuilt node on alpine; the
+  version-comparison rule in `REPO_POLICIES.md` names node as its exception.
+  `script/fmt` and `script/fmt-check` pick their yarn with the same test: the
+  `yarn` on `PATH` when the installed node is the pinned major, and otherwise
+  yarn under the pinned node through nvm. `REPO_POLICIES.md` and both checklists
+  say so, and the checklists' final `script/cibuild` check names what the CI
+  runner image has: node 24 and no yarn. Not yet tried on the shared runner.
+  Repositories pick this up on their next re-vendor.
+- 2026-10-07: The `script/cibuild` item in `NEW_REPO_CHECKLIST.md` now matches
+  the canonical `script/cibuild` (issue 125). Its image build carries the tag,
+  `-t "$tag"`, and the item says that `$version` comes from
+  `git describe --tags --always --dirty` (`unknown` if empty) and `$tag` from
+  `script/projectname`, each assigned on its own line before the build. A
+  repository written from the checklist got an untagged build, which leaves a
+  dangling image behind on every run, and was never told where `$version` comes
+  from. The other `docker build` commands the checklists and `REPO_POLICIES.md`
+  give for `script/` already matched their scripts.
+- 2026-10-07: `script/lint` and `script/test` now build with
+  `--output type=cacheonly` in place of a tag (issue 123), so they still run
+  their phase uncached and fail on a failing step but write no image. Nothing
+  used those images, and writing one out cost about 16 seconds of a Go
+  repository's test build. `script/cibuild` and `script/docker` keep their tags.
+  `REPO_POLICIES.md`, both checklists and the README no longer say the gate
+  builds are tagged. Not yet tried on the shared runner. Repositories pick this
+  up on their next re-vendor.
+- 2026-10-07: The canonical `.gitea/workflows/check.yml` now sets
+  `timeout-minutes: 20` on its `check` job (issue 120), so a hung build frees
+  the shared runner instead of holding it until the runner's own limit.
+  `script/cibuild` runs three Docker builds, each held to the 5-minute Docker
+  build limit, plus the bootstrap; if that limit changes (issue 113), the value
+  follows it. `REPO_POLICIES.md` and both checklists name the limit among what
+  the workflow sets. Not yet tried on the shared runner. Repositories pick this
+  up on their next re-vendor.
+- 2026-10-07: The canonical `package.json` now has `"private": true` in place of
+  `"license": "MIT"` (issue 119), so a repository that copies it no longer
+  declares MIT whatever its own licence is. yarn does not print "No license
+  field" for a private package. This repository's own licence is unchanged.
+- 2026-10-06: The canonical `.gitea/workflows/check.yml` now sets
+  `fetch-depth: 0` on its checkout step (issue 110), so CI fetches the history
+  and tags that `git describe --tags --always` needs, and a tagged repository
+  stamps the same version in CI as in a local build. `REPO_POLICIES.md` and both
+  checklists name `fetch-depth: 0` among what the workflow does, next to
+  `persist-credentials: false` and the `concurrency` block, instead of asking
+  each tagged repository to add it. 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 `script/bootstrap` now runs `apt-get update` once,
+  before the first `apt-get install` of a run (issue 115). The Gitea runner
+  image starts with empty package lists, so installing anything it lacks, such
+  as Go, failed with `Unable to locate package`. A repository's own section no
+  longer needs a refresh of its own; `sneak/bsfirehose` and `sneak/dnswatcher`
+  drop theirs at their next re-vendor.
+- 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
+  credential. The Dockerfile example in `REPO_POLICIES.md` installs `git`, takes
+  the `VERSION` build argument when one is given and otherwise
+  `git describe --tags --always`, and fails when `.git` exists but the version
+  is empty, `dev` or `unknown`; a plain `docker build .` with no build arguments
+  must succeed. This repo's `script/docker` and `script/cibuild` still pass
+  `--build-arg VERSION`, since its own `Dockerfile` compiles nothing.
 - 2026-09-08: Moved linting and testing into Docker as phases of the main
   `Dockerfile`, per the owner ruling on issue 40. `script/lint` and
   `script/test` build one phase each by name with `--no-cache` — the same answer

package.json

@@ -1,4 +1,5 @@
 {
+  "private": true,
   "devDependencies": {
     "prettier": "3.8.1"
   }

prompts/API_POLICIES.md

@@ -0,0 +1,20 @@
+---
+title: API Policies
+last_modified: 2026-10-27
+---
+
+A value in an API response is never a string with a label or unit in it. A value
+of a native type is sent as that type, and its unit goes in the field name, for
+example `_ms`.
+
+Wrong:
+
+```json
+{ "execution_time": "0 ms" }
+```
+
+Right:
+
+```json
+{ "execution_time_ms": 0 }
+```

prompts/CODE_STYLEGUIDE_GO.md

@@ -1,6 +1,6 @@
 ---
 title: Code Styleguide — Go
-last_modified: 2026-09-08
+last_modified: 2026-10-18
 ---
 
 1.  Try to hard wrap long lines at 77 characters or less.
@@ -24,7 +24,8 @@ last_modified: 2026-09-08
 1.  Embed the git commit hash into the binary and include it in startup logs and
     in health check output. This is to make it easier to correlate running
     instances with their code. Do not include build time or build user, as these
-    will make the build nondeterministic.
+    will make the build nondeterministic. The architecture is not passed in at
+    build time; a program that reports it reads `runtime.GOARCH` at run time.
 
     Example relevant Makefile sections:
 
@@ -35,32 +36,27 @@ last_modified: 2026-09-08
 
     import (
         "fmt"
+        "runtime"
     )
 
-    var (
+    var Version string
-        Version   string
-        Buildarch string
-    )
 
     func main() {
         fmt.Printf("Version: %s\n", Version)
-        fmt.Printf("Buildarch: %s\n", Buildarch)
+        fmt.Printf("Arch: %s\n", runtime.GOARCH)
     }
     ```
 
     ```make
-    # ?= rather than := because this `$(shell git describe ...)` is only
+    # ?= rather than := so that a `VERSION` build argument takes precedence:
-    # correct on the host: `.dockerignore` excludes `.git`, so evaluated
+    # where a build stage invokes make, `ARG VERSION` puts it in the
-    # inside a build stage it expands to the empty string without failing
+    # environment and `?=` defers to it. Otherwise `git describe` runs, in a
-    # and the binary reports no version. The version is computed on the
+    # build stage on the `.git` the build context carries. When it prints
-    # host by `script/docker` / `script/cibuild` and passed with
+    # nothing (outside a git checkout, or where git is missing or refuses the
-    # `--build-arg VERSION=...`; where a build stage invokes make,
+    # checkout), the version falls back to `dev`.
-    # `ARG VERSION` puts it in the environment and `?=` defers to it.
+    VERSION ?= $(or $(shell git describe --tags --always 2>/dev/null),dev)
-    VERSION ?= $(shell git describe --always --dirty)
-    BUILDARCH := $(shell uname -m)
 
     GOLDFLAGS += -X main.Version=$(VERSION)
-    GOLDFLAGS += -X main.Buildarch=$(BUILDARCH)
 
     # osx can't statically link apparently?!
     ifeq ($(UNAME_S),Darwin)
@@ -115,8 +111,11 @@ last_modified: 2026-09-08
     linting. It carries the lint and test phases, and the final stage depends on
     both, so a build makes sure the code is in an able-to-be-compiled state,
     linted, and its tests run. Go through `script/cibuild` or `script/docker`
-    rather than a bare `docker build .`: they pass `--no-cache`, without which
+    rather than a bare `docker build .`: they pass a new `CACHEBUST` value on
-    an unchanged tree serves the gate layers from cache and the build reports a
+    every build, which reruns every step that lints, tests or compiles and keeps
+    the system packages, Go's modules and build cache, and golangci-lint's
+    cache; `--no-cache` would throw all of them away. Without a new value an
+    unchanged tree serves the gate layers from cache and the build reports a
     green it never ran.
 
 1.  Every repo must have a `Makefile`. See
@@ -152,8 +151,9 @@ last_modified: 2026-09-08
     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/CODE_STYLEGUIDE_JS.md

@@ -1,6 +1,6 @@
 ---
 title: Code Styleguide — JavaScript
-last_modified: 2026-02-22
+last_modified: 2026-11-04
 ---
 
 1. Use `const` for everything. If you need to reassign, use `let`. Never use
@@ -8,7 +8,8 @@ last_modified: 2026-02-22
 
 1. Use yarn for package management, avoid using npm.
 
-1. Use LTS node versions.
+1. Install node from the distribution. If its version is too old, use a newer
+   distribution.
 
 1. Use `prettier` for code formatting, with four spaces for indentation.
 

prompts/EXISTING_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: Existing Repo Checklist
-last_modified: 2026-09-08
+last_modified: 2026-11-04
 ---
 
 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
@@ -40,11 +49,57 @@ with your task.
       `--target` names it, so a lost `COPY --from=` edge leaves `docker build .`
       passing while the gate never runs. Confirm by planting a violation, not by
       reading the file.
+- [ ] In every stage, every step that lints, tests or compiles comes after
+      `ARG CACHEBUST`. `ARG CACHEBUST` comes right after these steps:
+    - the steps that install system packages
+    - the steps that download Go's modules
+    - the step that runs `script/bootstrap` to install a Python `test` phase's
+      packages from `Pipfile.lock`
+- [ ] A stage with none of these steps declares `ARG CACHEBUST` right after
+      `FROM`. A step that also installs anything else comes after
+      `ARG CACHEBUST` too. A `script/bootstrap` that also installs node packages
+      is one. The `script/` builds pass a new `CACHEBUST` value on every build,
+      which reruns every `RUN` step after that line and leaves the layers above
+      it and the cache mounts in place; `--no-cache` would build those layers
+      again and empty the mounts. A stage without the `ARG` line is served from
+      cache on an unchanged tree, so the scripts and the `ARG` lines are
+      re-vendored in one commit.
+- [ ] Go: each Go stage downloads the modules (`COPY go.mod go.sum ./`,
+      `RUN go mod download`) above `ARG CACHEBUST`; the steps that compile
+      (`golangci-lint run`, `go test`, `go build`) mount Go's build cache
+      (`--mount=type=cache,target=/root/.cache/go-build`), `golangci-lint run`
+      also mounts golangci-lint's
+      (`--mount=type=cache,target=/root/.cache/golangci-lint`), and no step
+      mounts anything else; both `go test` runs carry `-count=1`; a first run
+      that timed out gets no rerun, as in the canonical Go `Dockerfile` in
+      `REPO_POLICIES.md`
+- [ ] Python: a `test` phase that installs its packages from `Pipfile.lock` does
+      it above `ARG CACHEBUST`, with `COPY script/ script/`,
+      `COPY Pipfile Pipfile.lock ./` and `RUN script/bootstrap`. When
+      `script/bootstrap` runs in that step, it installs nothing beyond these:
+    - system packages
+    - pipenv and its dependencies
+    - the packages from `Pipfile.lock`
+
+    It creates a virtual environment at `$HOME/.pipenv` with `python3 -m venv`
+    when it is missing, then uses that environment's `pip` and `pipenv`. On a
+    host, it first installs the distribution's python and venv packages when
+    they are missing. It installs pipenv and its dependencies by hash, with
+    `pip install --require-hashes`. It installs the packages from `Pipfile.lock`
+    with `pipenv install --deploy`, plus `--dev` when the tests need the
+    development packages. It sets `PIP_ONLY_BINARY=:all:` for both installs, so
+    a package with no wheel for the image stops the install. In that step it
+    installs no Python, because a step above it already did. `Pipfile` names no
+    `python_version`, because `--deploy` stops when the distribution's Python
+    differs from it. The tests run after `ARG CACHEBUST`, and every other stage
+    installs its Python packages after it, as in the Python `test` phase example
+    in `REPO_POLICIES.md`
+
 - [ ] The gate phases invoke their tools directly, never through `make lint` or
       `script/test` — those are themselves a `docker build` and would recurse
       inside a build step
 - [ ] Every depth-independent pattern in `.dockerignore` carries a `**/` prefix,
-      only genuinely root-anchored entries such as `.git` are unprefixed, and
+      only genuinely root-anchored entries such as `.claude` are unprefixed, and
       `.gitignore`'s patterns have not been transplanted unmodified — the
       transplanted form leaves `config/.env` and `certs/server.key` in the build
       context while reading as solved
@@ -58,21 +113,63 @@ with your task.
       can copy another session's unreviewed work into an image layer. If agents
       here run anywhere other than the repo root, the anchored entry misses
       `services/api/.claude/`: add anchored entries for those directories.
-- [ ] If the repo embeds a version in a binary, that version is computed on the
+- [ ] If the repo embeds a version in a binary: `.dockerignore` lets `.git` into
-      host and passed with `--build-arg VERSION=...` by `script/docker` and
+      the build context. It keeps out every git `config` at any depth
-      `script/cibuild`, and no stage calls `git describe`. A tag-derived version
+      (`**/.git/config`, `**/.git/modules/**/config`):
-      additionally needs `fetch-depth: 0` on the CI checkout step, which clones
+    - the repository's own
-      shallow and fetches no tags by default.
+    - each submodule's under `.git/modules/`
+    - that of a submodule keeping its own `.git` directory
+
+    `git describe` does not need them, and each can hold a credential: a
+    password in a remote URL, or the token the CI checkout step stores there.
+    Some submodule names have a `config` segment, as in `config`,
+    `deploy/config` or `config/lib`. Such a submodule 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, and an alpine one needs `apk add --no-cache git`. That
+    stage 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
+    - the tag, the number of commits since it and the short commit
+      (`v1.2.3-4-gabc1234`), on a later commit
+    - 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. 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
+    is the exception: a linked worktree, or a repository checked out as a
+    submodule. 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. The canonical `.gitea/workflows/check.yml` sets `fetch-depth: 0`
+    on its checkout step, which otherwise clones shallow and fetches no tags, so
+    a CI build finds the tag too.
+
 - [ ] Gitea Actions workflow in `.gitea/workflows/` runs `script/cibuild` on
-      push — reference
+      push, checks out with `persist-credentials: false` and with
+      `fetch-depth: 0` (which fetches the tags `git describe` needs), carries
+      the `concurrency` block that lets a new push cancel only the same branch's
+      older run, and sets `timeout-minutes: 20` on the `check` job so a hung
+      build frees the shared runner — 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
-          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.prettierignore`)
+          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.prettierignore`).
+          Make the first `yarn.lock` with yarn 1, from a distribution that
+          packages it, such as Alpine (`apk add nodejs yarn`).
     - [ ] Python: `pyproject.toml`
     - [ ] Docs/writing: `.prettierrc`, `.prettierignore` (same URLs as above)
 
@@ -89,25 +186,35 @@ with your task.
       `script/install-precommit`, shimmed by `make hooks`) runs it
 - [ ] README has an **Entrypoints** section documenting the `script/`
       entrypoints and linking the standard
-- [ ] `script/lint` and `script/test` build their phase by name
+- [ ] `script/lint` and `script/test` each run
-      (`docker build --no-cache --target <phase> -t <name>-<phase> .`), and no
+      `docker build --build-arg CACHEBUST="$(date +%s)-$$" --target <phase> --output type=cacheonly .`,
-      host invocation anywhere in the repo can produce a lint verdict — grep for
+      which builds their phase by name and writes no image, and no host
-      the linter's own name across `script/`, the `Makefile` and CI config, not
+      invocation anywhere in the repo can produce a lint verdict — grep for the
-      just `script/lint`. A second path is likeliest here: a `make lint-fast`,
+      linter's own name across `script/`, the `Makefile` and CI config, not just
-      an older host-versus-container branch, or a CI step calling the binary
+      `script/lint`. A second path is likeliest here: a `make lint-fast`, an
+      older host-versus-container branch, or a CI step calling the binary
       directly. `script/fmt` and `script/fmt-check` are expected hits and stay
       on the host.
-- [ ] Every `docker build` in `script/` is tagged — an untagged one leaves a
+- [ ] No `docker build` in `script/` leaves a dangling image behind:
-      dangling image behind on every run, on every host and CI runner
+      `script/lint` and `script/test` write no image, and `script/docker` and
+      `script/cibuild` tag theirs. A build that writes an untagged image leaves
+      one behind on every run, on every host and CI runner.
 - [ ] `script/cibuild` runs `script/bootstrap` before `script/check`, and builds
-      the image with `--no-cache`. Without the bootstrap the CI run dies in
+      the image with a new `CACHEBUST` value on every build, like every
+      `docker build` in `script/`. Without the bootstrap the CI run dies in
       `script/fmt-check`, which runs the formatter on the host and finds nothing
       installed.
-- [ ] `script/fmt` and `script/fmt-check` source nvm for the pinned node version
+- [ ] `script/bootstrap` installs node, yarn and the node packages only when
-      before invoking `yarn`, as `script/bootstrap`'s own install step does.
+      `yarn.lock` is in the tree. node and yarn come from the distribution when
-      `script/bootstrap` leaves the node and yarn it installs off the `PATH` of
+      they are missing. With `yarn.lock` in the tree, `script/bootstrap` stops
-      the shell that called it, so a bare `yarn` exits 127 on a runner carrying
+      with a one-line message when yarn's major version is not 1.
-      nothing but docker and git.
+- [ ] A `Dockerfile` stage copies `yarn.lock` before it runs `script/bootstrap`
+      only if that stage needs yarn. A stage that needs yarn starts from an
+      image whose distribution packages yarn 1, such as Alpine.
+- [ ] `script/bootstrap`, `script/fmt` and `script/fmt-check` run yarn by
+      whichever name is present: `yarn`, or `yarnpkg` on Debian and Ubuntu. With
+      neither name on `PATH`, `script/fmt` and `script/fmt-check` print one line
+      saying to run `script/bootstrap`, and exit 1.
 - [ ] `script/bootstrap` installs no linter of its own — delete the block, its
       version variables and its call site. A JS repo's `yarn install` stays; it
       brings a linter along with every other dependency, and no verdict is taken
@@ -131,7 +238,16 @@ with your task.
 - [ ] Pre-commit hook is installed (`make hooks`)
 - [ ] No secrets in the repo (`.env`, keys, credentials)
 - [ ] No mutable references in Dockerfiles or scripts (tags, `@latest`) — all
-      pinned by cryptographic hash with version/date comment
+      pinned by cryptographic hash with version/date comment. The one exception
+      is a package from the distribution's own package index, which needs no
+      version and no hash. Pulling that index is also allowed. In a
+      `Dockerfile`, the distribution is the pinned base image's. On a host, it
+      is the host's, and the host's package manager stands for it, nix and brew
+      included. A package source that a `Dockerfile` adds itself does not get
+      this exception
+- [ ] node, yarn, npm, python, pip and venv come from the distribution wherever
+      possible, never from nvm, pyenv, corepack or `npm install -g yarn`. If the
+      distribution's version is too old, use a newer distribution
 - [ ] Using `yarn`, not `npm` (JS projects)
 
 # Directory Structure
@@ -160,10 +276,17 @@ with your task.
 # Final
 
 - [ ] `make check` passes
-- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying nothing but
+- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has.
-      docker and git, with no node or yarn on `PATH`, which is what CI has, and
+      That host is the runner image
-      demonstrably executed the checks — a sub-second build, or `CACHED` on a
+      `docker.gitea.com/runner-images:ubuntu-latest`, which has docker, git and
-      gate layer, means nothing ran
+      node 24. Take any yarn off `PATH` first. The run must show that the checks
+      executed. A sub-second build means nothing ran. So does `CACHED` on a step
+      that lints or tests, one of the `RUN` steps below `ARG CACHEBUST`. Above
+      that line, these steps are expected to show `CACHED`:
+    - the steps that install system packages
+    - the steps that download Go's modules
+    - the step that runs `script/bootstrap` to install a Python `test` phase's
+      packages from `Pipfile.lock`
 - [ ] A planted lint violation fails both `make lint` and a plain
       `docker build .`; revert it afterwards
 - [ ] Commit and merge fixes before starting your actual task

prompts/GO_HTTP_SERVER_CONVENTIONS.md

@@ -1,6 +1,6 @@
 ---
 title: Go HTTP Server Conventions
-last_modified: 2026-09-08
+last_modified: 2026-10-04
 ---
 
 This document defines the architectural patterns, design decisions, and
@@ -106,6 +106,9 @@ project-root/
 package main
 
 import (
+    "os/signal"
+    "syscall"
+
     "yourproject/internal/config"
     "yourproject/internal/database"
     "yourproject/internal/globals"
@@ -120,13 +123,14 @@ import (
 var (
     Appname string = "CHANGEME"
     Version string
-    Buildarch string
 )
 
 func main() {
     globals.Appname = Appname
     globals.Version = Version
-    globals.Buildarch = Buildarch
+
+    // A write to a closed stdout or stderr must not end the process.
+    signal.Ignore(syscall.SIGPIPE)
 
     fx.New(
         fx.Provide(
@@ -200,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)
 
 ---
 
@@ -219,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
@@ -250,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
 }
@@ -266,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)
         }
     }
 }
@@ -294,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
 }
 ```
 
@@ -826,7 +820,7 @@ func (l *Logger) Identify() {
     l.log.Info("starting",
         "appname", l.params.Globals.Appname,
         "version", l.params.Globals.Version,
-        "buildarch", l.params.Globals.Buildarch,
+        "arch", runtime.GOARCH,
     )
 }
 ```
@@ -948,20 +942,17 @@ import "go.uber.org/fx"
 var (
     Appname string
     Version string
-    Buildarch string
 )
 
 // Struct for DI
 type Globals struct {
     Appname string
     Version string
-    Buildarch string
 }
 
 func New(lc fx.Lifecycle) (*Globals, error) {
     n := &Globals{
         Appname: Appname,
-        Buildarch: Buildarch,
         Version: Version,
     }
     return n, nil
@@ -975,13 +966,11 @@ func New(lc fx.Lifecycle) (*Globals, error) {
 var (
     Appname string = "CHANGEME"  // Default, overridden by build
     Version string               // Set at build time
-    Buildarch string               // Set at build time
 )
 
 func main() {
     globals.Appname = Appname
     globals.Version = Version
-    globals.Buildarch = Buildarch
     // ...
 }
 ```
@@ -991,18 +980,16 @@ func main() {
 Use ldflags to inject version information at build time:
 
 ```makefile
-# ?= rather than := because this `$(shell git describe ...)` is only correct
+# ?= rather than := so that a `VERSION` build argument takes precedence:
-# on the host: `.dockerignore` excludes `.git`, so evaluated inside a build
+# where a build stage invokes make, `ARG VERSION` puts it in the
-# stage it expands to the empty string without failing and the binary reports
+# environment and `?=` defers to it. Otherwise `git describe` runs, in a
-# no version. The version is computed on the host by `script/docker` /
+# build stage on the `.git` the build context carries. When it prints
-# `script/cibuild` and passed with `--build-arg VERSION=...`; where the build
+# nothing (outside a git checkout, or where git is missing or refuses the
-# stage invokes make, `ARG VERSION` puts it in the environment and `?=` defers
+# checkout), the version falls back to `dev`.
-# to it.
+VERSION ?= $(or $(shell git describe --tags --always 2>/dev/null),dev)
-VERSION ?= $(shell git describe --tags --always)
-BUILDARCH := $(shell go env GOARCH)
 
 build:
-    go build -ldflags "-X main.Version=$(VERSION) -X main.Buildarch=$(BUILDARCH)" ./cmd/httpd
+    go build -ldflags "-X main.Version=$(VERSION)" ./cmd/httpd
 ```
 
 ---
@@ -1169,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{
@@ -1181,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
@@ -1201,7 +1190,7 @@ if s.sentryEnabled {
 }
 ```
 
-Flush Sentry on shutdown:
+Flush Sentry in the server's stop hook, `cleanShutdown()`:
 
 ```go
 if s.sentryEnabled {

prompts/NEW_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: New Repo Checklist
-last_modified: 2026-09-08
+last_modified: 2026-11-04
 ---
 
 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
@@ -67,26 +73,115 @@ Template files can be fetched from:
       note that it only covers agents running at the repo root — if this repo
       will run them in subdirectories, `services/api/.claude/` needs its own
       anchored entry.
-    - If the image embeds a version in a binary, the version is computed on the
+    - If the image embeds a version in a binary: `.dockerignore` lets `.git`
-      host and passed with `--build-arg VERSION=...`, and `ARG VERSION=dev` is
+      into the build context. It keeps out every git `config` at any depth
-      declared in the stage that compiles. **No stage calls `git describe`** —
+      (`**/.git/config`, `**/.git/modules/**/config`):
-      `.dockerignore` excludes `.git`, so it yields an empty version without
+        - the repository's own
-      failing the build.
+        - each submodule's under `.git/modules/`
+        - that of a submodule keeping its own `.git` directory
+
+        `git describe` does not need them, and each can hold a credential: a
+        password in a remote URL, or the token the CI checkout step stores
+        there. Some submodule names have a `config` segment, as in `config`,
+        `deploy/config` or `config/lib`. Such a submodule 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, and an alpine one needs
+        `apk add --no-cache git`. That stage 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
+        - the tag, the number of commits since it and the short commit
+          (`v1.2.3-4-gabc1234`), on a later commit
+        - 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. 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 is the exception:
+        a linked worktree, or a repository checked out as a submodule. 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
       cannot be built unless both passed. Keep the final stage last: a stage
       nothing depends on is built only when `--target` names it.
+    - In every stage, every step that lints, tests or compiles comes after
+      `ARG CACHEBUST`. `ARG CACHEBUST` comes right after these steps:
+        - the steps that install system packages
+        - the steps that download Go's modules
+        - the step that runs `script/bootstrap` to install a Python `test`
+          phase's packages from `Pipfile.lock`
+    - A stage with none of these steps declares `ARG CACHEBUST` right after
+      `FROM`. A step that also installs anything else comes after
+      `ARG CACHEBUST` too. A `script/bootstrap` that also installs node packages
+      is one. The `script/` builds pass a new `CACHEBUST` value on every build,
+      which reruns every `RUN` step after that line and leaves the layers above
+      it and the cache mounts in place; `--no-cache` would build those layers
+      again and empty the mounts. A stage without the `ARG` line is served from
+      cache on an unchanged tree, so the scripts and every stage's
+      `ARG CACHEBUST` line are added in the same commit.
+    - Go: each Go stage downloads the modules (`COPY go.mod go.sum ./`,
+      `RUN go mod download`) above `ARG CACHEBUST`; the steps that compile
+      (`golangci-lint run`, `go test`, `go build`) mount Go's build cache
+      (`--mount=type=cache,target=/root/.cache/go-build`), `golangci-lint run`
+      also mounts golangci-lint's
+      (`--mount=type=cache,target=/root/.cache/golangci-lint`), and no step
+      mounts anything else; both `go test` runs carry `-count=1`; a first run
+      that timed out gets no rerun, as in the canonical Go `Dockerfile` in
+      `REPO_POLICIES.md`
+    - Python: a `test` phase that installs its packages from `Pipfile.lock` does
+      it above `ARG CACHEBUST`, with `COPY script/ script/`,
+      `COPY Pipfile Pipfile.lock ./` and `RUN script/bootstrap`. When
+      `script/bootstrap` runs in that step, it installs nothing beyond these:
+        - system packages
+        - pipenv and its dependencies
+        - the packages from `Pipfile.lock`
+
+        It creates a virtual environment at `$HOME/.pipenv` with
+        `python3 -m venv` when it is missing, then uses that environment's `pip`
+        and `pipenv`. On a host, it first installs the distribution's python and
+        venv packages when they are missing. It installs pipenv and its
+        dependencies by hash, with `pip install --require-hashes`. It installs
+        the packages from `Pipfile.lock` with `pipenv install --deploy`, plus
+        `--dev` when the tests need the development packages. It sets
+        `PIP_ONLY_BINARY=:all:` for both installs, so a package with no wheel
+        for the image stops the install. In that step it installs no Python,
+        because a step above it already did. `Pipfile` names no
+        `python_version`, because `--deploy` stops when the distribution's
+        Python differs from it. The tests run after `ARG CACHEBUST`, and every
+        other stage installs its Python packages after it, as in the Python
+        `test` phase example in `REPO_POLICIES.md`
+
     - Server: the final stage builds and runs the application
     - 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
+      with `fetch-depth: 0` (which fetches the tags `git describe` needs),
+      carries the `concurrency` block that lets a new push cancel only the same
+      branch's older run, and sets `timeout-minutes: 20` on the `check` job so a
+      hung build frees the shared runner — 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,
-    - [ ] JS: `yarn init`, `yarn add --dev prettier`
+          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`. `script/bootstrap`
+          installs no yarn until `yarn.lock` exists, so use yarn 1 from a
+          distribution that packages it, such as Alpine (`apk add nodejs yarn`).
     - [ ] Python: `pyproject.toml`
 
 ## Configure script/ Entrypoints and Makefile
@@ -97,18 +192,31 @@ are thin shims calling them. Model scripts:
 
 - [ ] scripts are POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they run on
       alpine images without bash
-- [ ] `script/bootstrap` / `make bootstrap` — installs all dependencies,
+- [ ] `script/bootstrap` / `make bootstrap` installs all dependencies,
-      idempotently, assuming nothing (pkg manager detection nix/apt/brew/apk;
+      idempotently, and assumes nothing is present:
-      node used if present, else pinned version via nvm from a hash-verified
+    - It detects the package manager: nix, apt, brew or apk.
-      archive; pinned yarn via corepack); Dockerfile runs it instead of inline
+    - It installs node, yarn and the node packages only when `yarn.lock` is in
-      installs
+      the tree. node and yarn come from that package manager when they are
+      missing.
+    - With `yarn.lock` in the tree, it stops with a one-line message when yarn's
+      major version is not 1.
+    - A non-server repo's development environment stage runs it, with only
+      system packages installed inline above it.
+    - A gate phase or the build stage installs what its base image lacks, either
+      inline or by running it.
+- [ ] A `Dockerfile` stage copies `yarn.lock` before it runs `script/bootstrap`
+      only if that stage needs yarn. A stage that needs yarn starts from an
+      image whose distribution packages yarn 1, such as Alpine.
 - [ ] `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 .`,
+- [ ] `script/test` / `make test` —
-      tagged; the phase runs real tests, not a no-op (90-second timeout,
+      `docker build --build-arg CACHEBUST="$(date +%s)-$$" --target test --output type=cacheonly .`,
-      60-second hard cap on wall time)
+      which writes no image; the phase runs real tests, not a no-op (90-second
-- [ ] `script/lint` / `make lint` — `docker build --no-cache --target lint .`,
+      timeout, 60-second hard cap on wall time)
-      tagged. No lint verdict may come from a host invocation of the linter.
+- [ ] `script/lint` / `make lint` —
+      `docker build --build-arg CACHEBUST="$(date +%s)-$$" --target lint --output type=cacheonly .`,
+      which writes no image. No lint verdict may come from a host invocation of
+      the linter.
 - [ ] `script/fmt` / `make fmt` — formats code (writes; native, never in a
       container)
 - [ ] `script/fmt-check` / `make fmt-check` — checks formatting (read-only;
@@ -118,20 +226,23 @@ are thin shims calling them. Model scripts:
 - [ ] `script/projectname` — outputs the project name (used by `script/docker`
       for the image tag)
 - [ ] `script/docker` / `make docker` — builds Docker image, tagged via
-      `script/projectname` (byte-identical across repos); `--no-cache`, plus the
+      `script/projectname` (byte-identical across repos); a new `CACHEBUST`
-      version as a build arg
+      value on every build, plus the version as a build arg
 - [ ] `script/cibuild` — cd to repo root, run `script/bootstrap`, run
       `script/check`, then
-      `docker build --no-cache --build-arg VERSION="$version" .` (what CI runs).
+      `docker build --build-arg CACHEBUST="$(date +%s)-$$" --build-arg VERSION="$version" -t "$tag" .`
+      (what CI runs), with `$version` from
+      `git describe --tags --always --dirty` (`unknown` if empty) and `$tag`
+      from `script/projectname`, each assigned on its own line before the build.
       The bootstrap is required: CI checks out and runs this alone, and
       `script/fmt-check` runs the formatter on the host.
-- [ ] `script/fmt` and `script/fmt-check` source nvm for the pinned node version
+- [ ] `script/bootstrap`, `script/fmt` and `script/fmt-check` run yarn by
-      before invoking `yarn`, as `script/bootstrap`'s own install step does.
+      whichever name is present: `yarn`, or `yarnpkg` on Debian and Ubuntu. With
-      `script/bootstrap` leaves the node and yarn it installs off the `PATH` of
+      neither name on `PATH`, `script/fmt` and `script/fmt-check` print one line
-      the shell that called it, so a bare `yarn` exits 127 on a runner carrying
+      saying to run `script/bootstrap`, and exit 1.
-      nothing but docker and git.
+- [ ] No `docker build` in `script/` leaves a dangling image behind:
-- [ ] Every `docker build` in `script/` is tagged, so no invocation leaves a
+      `script/lint` and `script/test` write no image, and `script/docker` and
-      dangling image behind
+      `script/cibuild` tag theirs
 - [ ] `script/precommit` — called by the pre-commit hook; runs `script/check`
 - [ ] `script/install-precommit` — installs the pre-commit hook that runs
       `script/precommit`
@@ -143,16 +254,31 @@ are thin shims calling them. Model scripts:
 
 - [ ] `make check` passes
 - [ ] `make docker` succeeds
-- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying nothing but
+- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has.
-      docker and git, with no node or yarn on `PATH`, which is what CI has, and
+      That host is the runner image
-      demonstrably executed the checks — a sub-second build, or `CACHED` on a
+      `docker.gitea.com/runner-images:ubuntu-latest`, which has docker, git and
-      gate layer, means nothing ran
+      node 24. Take any yarn off `PATH` first. The run must show that the checks
+      executed. A sub-second build means nothing ran. So does `CACHED` on a step
+      that lints or tests, one of the `RUN` steps below `ARG CACHEBUST`. Above
+      that line, these steps are expected to show `CACHED`:
+    - the steps that install system packages
+    - the steps that download Go's modules
+    - the step that runs `script/bootstrap` to install a Python `test` phase's
+      packages from `Pipfile.lock`
 - [ ] Plant a lint violation and confirm both `make lint` and a plain
       `docker build .` fail on it; revert. A plain build that passes proves the
       final stage is missing its `COPY --from=` edge to the gate phases.
 - [ ] No secrets in repo, and none in the build context: enumerate a probe image
       rather than reading `.dockerignore`
-- [ ] No mutable image/package references
+- [ ] No mutable image/package references. The one exception is a package from
+      the distribution's own package index, which needs no version and no hash.
+      Pulling that index is also allowed. In a `Dockerfile`, the distribution is
+      the pinned base image's. On a host, it is the host's, and the host's
+      package manager stands for it, nix and brew included. A package source
+      that a `Dockerfile` adds itself does not get this exception
+- [ ] node, yarn, npm, python, pip and venv come from the distribution wherever
+      possible, never from nvm, pyenv, corepack or `npm install -g yarn`. If the
+      distribution's version is too old, use a newer distribution
 - [ ] No unnecessary files in repo root
 - [ ] All dates written as YYYY-MM-DD
 

script/bootstrap

@@ -1,24 +1,18 @@
 #!/bin/sh
 # script/bootstrap: install all dependencies needed to build and develop
 # this repo. Idempotent: every install is guarded by a check so already
-# installed tools are skipped. Base tooling comes from nix, apt, brew,
+# installed tools are skipped. Base tools, node and yarn come from nix,
-# or apk (detected in that order); assumes nothing is present. Node is
+# apt, brew, or apk (detected in that order), with no version and no
-# used directly if installed; otherwise it is installed at a pinned
+# hash, because the distribution is trusted. It installs node, yarn and
-# version via nvm (installing nvm itself first, from a hash-verified
+# the node packages only when yarn.lock is in the tree. Assumes nothing
-# release archive, never curl | sh).
+# is present.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
-# Pinned versions, 2026-07-06
-NODE_VERSION="22.17.0"
-NVM_VERSION="0.40.3"
-# sha256 of https://github.com/nvm-sh/nvm/archive/refs/tags/v0.40.3.tar.gz
-NVM_SHA256="5f4d6aaa04a177dc93c985e31dbc411ab6b8c6e1e21d8015dbc1372625fcd1d0"
-YARN_VERSION="1.22.22"
-
 PKGMGR=""
 SUDO=""
+APT_UPDATED=""
 
 detect_pkgmgr() {
     [ -n "$PKGMGR" ] && return 0
@@ -47,7 +41,14 @@ pkg_install() {
     detect_pkgmgr
     case "$PKGMGR" in
         nix) nix-env -iA "nixpkgs.$1" ;;
-        apt) $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y "$2" ;;
+        apt)
+            # Package lists may be empty (fresh images); refresh once per run.
+            if [ -z "$APT_UPDATED" ]; then
+                $SUDO env DEBIAN_FRONTEND=noninteractive apt-get update
+                APT_UPDATED=1
+            fi
+            $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y "$2"
+            ;;
         brew) brew install "$3" ;;
         apk) apk add --no-cache "$4" ;;
     esac
@@ -57,78 +58,42 @@ missing() {
     ! command -v "$1" >/dev/null 2>&1
 }
 
-# verify_sha256 <file> <expected-hash>
+# Debian and Ubuntu name the yarn command yarnpkg.
-verify_sha256() {
+run_yarn() {
-    if command -v sha256sum >/dev/null 2>&1; then
+    if command -v yarn >/dev/null 2>&1; then
-        actual="$(sha256sum "$1" | cut -d' ' -f1)"
+        yarn "$@"
+    elif command -v yarnpkg >/dev/null 2>&1; then
+        yarnpkg "$@"
     else
-        actual="$(shasum -a 256 "$1" | cut -d' ' -f1)"
+        echo "no yarn; run script/bootstrap first" >&2
-    fi
-    if [ "$actual" != "$2" ]; then
-        echo "bootstrap: sha256 mismatch for $1" >&2
-        echo "  expected: $2" >&2
-        echo "  actual:   $actual" >&2
         exit 1
     fi
 }
 
-# nvm is a bash script; run a command in a bash with nvm loaded
-nvm_sh() {
-    bash -c ". \"\$HOME/.nvm/nvm.sh\" && $*"
-}
-
-ensure_nvm() {
-    [ -s "$HOME/.nvm/nvm.sh" ] && return 0
-    # nvm prerequisites; nvm itself requires bash
-    if missing bash; then pkg_install bash bash bash bash; fi
-    if missing curl; then pkg_install curl curl curl curl; fi
-    if missing git; then pkg_install git git git git; fi
-    tmp="$(mktemp -d)"
-    curl -fsSL -o "$tmp/nvm.tar.gz" \
-        "https://github.com/nvm-sh/nvm/archive/refs/tags/v${NVM_VERSION}.tar.gz"
-    verify_sha256 "$tmp/nvm.tar.gz" "$NVM_SHA256"
-    mkdir -p "$HOME/.nvm"
-    tar -xzf "$tmp/nvm.tar.gz" -C "$HOME/.nvm" --strip-components=1
-    rm -rf "$tmp"
-}
-
-ensure_node() {
-    if ! missing node; then return 0; fi
-    ensure_nvm
-    nvm_sh "nvm install $NODE_VERSION"
-}
-
-ensure_yarn() {
-    if ! missing yarn; then return 0; fi
-    if ! missing corepack; then
-        corepack enable
-        corepack prepare "yarn@$YARN_VERSION" --activate
-    elif [ -s "$HOME/.nvm/nvm.sh" ]; then
-        nvm_sh "nvm use $NODE_VERSION >/dev/null && corepack enable && \
-            corepack prepare yarn@$YARN_VERSION --activate"
-    else
-        npm install -g "yarn@$YARN_VERSION"
-    fi
-}
-
-install_js_deps() {
-    if missing yarn && [ -s "$HOME/.nvm/nvm.sh" ]; then
-        nvm_sh "nvm use $NODE_VERSION >/dev/null && cd \"$ROOT\" && \
-            yarn install --frozen-lockfile"
-    else
-        yarn install --frozen-lockfile
-    fi
-}
-
 main() {
     cd "$ROOT"
 
     if missing make; then pkg_install gnumake make make make; fi
     if missing git; then pkg_install git git git git; fi
 
-    ensure_node
+    # A Dockerfile stage that needs no yarn copies no yarn.lock.
-    ensure_yarn
+    if [ -f yarn.lock ]; then
-    install_js_deps
+        if missing node; then pkg_install nodejs nodejs node nodejs; fi
+        if missing yarn && missing yarnpkg; then
+            pkg_install yarn yarnpkg yarn yarn
+        fi
+
+        # Debian 13 and Ubuntu 26.04 package yarn 4, which refuses a yarn 1
+        # yarn.lock, or rewrites it in its own format.
+        yarn_version="$(run_yarn --version)"
+        if [ "${yarn_version%%.*}" != "1" ]; then
+            echo "bootstrap: yarn $yarn_version refuses this yarn 1 yarn.lock;" \
+                "use a distribution that packages yarn 1" >&2
+            exit 1
+        fi
+
+        run_yarn install --frozen-lockfile
+    fi
 
     echo "bootstrap complete"
 }

script/cibuild

@@ -2,9 +2,12 @@
 # script/cibuild: run the CI build. It bootstraps first: a CI runner
 # checks out and runs this and nothing else, and script/fmt-check runs
 # the formatter on the host, which a pristine checkout cannot do.
-# --no-cache for the same reason as script/docker: the gate phases the
+# A new CACHEBUST value reruns every RUN step after the ARG CACHEBUST
-# final stage depends on are RUN steps, and a cached one is a check that
+# line, since a cached gate phase is a check that did not run; unlike
-# did not run.
+# --no-cache, it keeps the layers above that line and the cache mounts.
+# This relies on every stage of the Dockerfile declaring ARG CACHEBUST
+# before every step that lints, tests or compiles; a stage without that
+# line is served from cache on an unchanged tree, with no warning.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -14,16 +17,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. VERSION is computed here because .dockerignore
+    # so the inline form degrades silently to an empty constant. The
-    # excludes .git, so `git describe` in a build stage yields an empty
+    # VERSION build argument takes precedence over the version a build
-    # version without failing.
+    # stage derives from the .git in the context.
     version="$(git describe --tags --always --dirty 2>/dev/null || true)"
     [ -n "$version" ] || version="unknown"
-    docker build --no-cache \
+    tag="$("$SCRIPT_DIR/projectname")"
+    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
         --build-arg VERSION="$version" \
-        -t "$("$SCRIPT_DIR/projectname")" .
+        -t "$tag" .
 }
 
 main "$@"

script/docker

@@ -1,8 +1,12 @@
 #!/bin/sh
 # script/docker: build the Docker image tagged with the project name.
 # Identical in all repos; the tag comes from script/projectname.
-# --no-cache because the gate phases the final stage depends on are RUN
+# A new CACHEBUST value reruns every RUN step after the ARG CACHEBUST
-# steps, and a cached one is a check that did not run.
+# line, since a cached gate phase is a check that did not run; unlike
+# --no-cache, it keeps the layers above that line and the cache mounts.
+# This relies on every stage of the Dockerfile declaring ARG CACHEBUST
+# before every step that lints, tests or compiles; a stage without that
+# line is served from cache on an unchanged tree, with no warning.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -10,16 +14,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. VERSION is computed here because .dockerignore
+    # so the inline form degrades silently to an empty constant. The
-    # excludes .git, so `git describe` in a build stage yields an empty
+    # VERSION build argument takes precedence over the version a build
-    # version without failing.
+    # stage derives from the .git in the context.
     version="$(git describe --tags --always --dirty 2>/dev/null || true)"
     [ -n "$version" ] || version="unknown"
-    docker build --no-cache \
+    tag="$("$SCRIPT_DIR/projectname")"
+    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
         --build-arg VERSION="$version" \
-        -t "$("$SCRIPT_DIR/projectname")" .
+        -t "$tag" .
 }
 
 main "$@"

script/fmt

@@ -4,23 +4,16 @@ set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
-# Must match the pin in script/bootstrap.
+# Debian and Ubuntu name the yarn command yarnpkg.
-NODE_VERSION="22.17.0"
-
-# script/bootstrap installs node and yarn under nvm and leaves neither
-# on the PATH of the shell that called it, so resolve the pinned
-# toolchain here the way bootstrap's own install step does. nvm is a
-# bash script, hence the subshell.
 run_yarn() {
     if command -v yarn >/dev/null 2>&1; then
-        exec yarn "$@"
+        yarn "$@"
-    fi
+    elif command -v yarnpkg >/dev/null 2>&1; then
-    if [ ! -s "$HOME/.nvm/nvm.sh" ]; then
+        yarnpkg "$@"
-        echo "fmt: no yarn; run script/bootstrap first" >&2
+    else
+        echo "no yarn; run script/bootstrap first" >&2
         exit 1
     fi
-    exec bash -c '. "$HOME/.nvm/nvm.sh" && nvm use "$1" >/dev/null &&
-        shift && exec yarn "$@"' bash "$NODE_VERSION" "$@"
 }
 
 main() {

script/fmt-check

@@ -4,23 +4,16 @@ set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
-# Must match the pin in script/bootstrap.
+# Debian and Ubuntu name the yarn command yarnpkg.
-NODE_VERSION="22.17.0"
-
-# script/bootstrap installs node and yarn under nvm and leaves neither
-# on the PATH of the shell that called it, so resolve the pinned
-# toolchain here the way bootstrap's own install step does. nvm is a
-# bash script, hence the subshell.
 run_yarn() {
     if command -v yarn >/dev/null 2>&1; then
-        exec yarn "$@"
+        yarn "$@"
-    fi
+    elif command -v yarnpkg >/dev/null 2>&1; then
-    if [ ! -s "$HOME/.nvm/nvm.sh" ]; then
+        yarnpkg "$@"
-        echo "fmt-check: no yarn; run script/bootstrap first" >&2
+    else
+        echo "no yarn; run script/bootstrap first" >&2
         exit 1
     fi
-    exec bash -c '. "$HOME/.nvm/nvm.sh" && nvm use "$1" >/dev/null &&
-        shift && exec yarn "$@"' bash "$NODE_VERSION" "$@"
 }
 
 main() {

script/lint

@@ -5,9 +5,14 @@
 # make its answer untrustworthy.
 #
 # The phase is not the last stage in the file, so it is built only when
-# --target names it. --no-cache because a cached lint layer is a lint
+# --target names it. A new CACHEBUST value reruns every RUN step after
-# that did not run. The tag makes each build replace the previous image
+# the ARG CACHEBUST line, since a cached lint layer is a lint that did
-# instead of leaving a dangling one behind.
+# not run; unlike --no-cache, it keeps the layers above that line and
+# the cache mounts. This relies on every stage of the Dockerfile
+# declaring ARG CACHEBUST before every step that lints, tests or
+# compiles; a stage without that line is served from cache on an
+# unchanged tree, with no warning.
+# --output type=cacheonly writes no image, since nothing uses one.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -15,9 +20,9 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build --no-cache \
+    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
         --target lint \
-        -t "$("$SCRIPT_DIR/projectname")-lint" .
+        --output type=cacheonly .
 }
 
 main "$@"

script/test

@@ -2,8 +2,13 @@
 # script/test: run the test suite. Testing is a phase of the Dockerfile
 # and this builds that phase alone, on the same terms as script/lint:
 # --target because a phase that is not the last stage is built only when
-# named, --no-cache because a cached test layer is a test that did not
+# named, and a new CACHEBUST value because a cached test layer is a test
-# run, and a tag so each build replaces the previous image.
+# that did not run; unlike --no-cache, it keeps the layers above the ARG
+# CACHEBUST line and the cache mounts. This relies on every stage of the
+# Dockerfile declaring ARG CACHEBUST before every step that lints, tests
+# or compiles; a stage without that line is served from cache on an
+# unchanged tree, with no warning. --output type=cacheonly writes no
+# image, since nothing uses one.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -11,9 +16,9 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build --no-cache \
+    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
         --target test \
-        -t "$("$SCRIPT_DIR/projectname")-test" .
+        --output type=cacheonly .
 }
 
 main "$@"