Merge TODO.md with git's union merge (closes #98)

Every PR adds an entry at the top of Completed Steps in TODO.md, so each
merge to next left every other open PR conflicting there. A root
.gitattributes now marks TODO.md merge=union, so two branches inserting
at the same place merge without a conflict.

Git now never reports a conflict in TODO.md: a real conflict elsewhere
keeps both versions of the line, and two new entries that share an
identical line end up one inside the other. The .gitattributes comment
and the TODO.md entry say to read the merged entries after every merge
or rebase.

This applies to this repository only; nothing canonical changes.

Model: opus-5-5

.dockerignore

@@ -18,16 +18,9 @@
 # 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
+# under .git/modules/, nested again for a submodule's own submodules.
+.git/config
+.git/modules/**/config
 
 # Agent scratch: one full checkout of the repo per in-flight agent.
 # Anchored because it occurs once where agents run at the repo root.

.editorconfig

@@ -10,9 +10,3 @@ 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

@@ -1,4 +1,3 @@
-# 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.
+# Git never reports a conflict in TODO.md: read the merged entries after every
+# merge or rebase, because an entry can land in the middle of another.
 TODO.md merge=union

.gitea/workflows/check.yml

@@ -1,20 +1,9 @@
 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

@@ -27,7 +27,7 @@ node_modules/
 # 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`.
+# its own negation after these lines, for example `!.env.example`.
 *.[eE][nN][vV]
 .[eE][nN][vV].*
 .[eE][nN][vV][rR][cC]
@@ -45,7 +45,3 @@ node_modules/
 [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,9 +3,6 @@ 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
@@ -19,13 +16,13 @@ linters:
     - gomodguard_v2
   disable:
     # Genuinely incompatible with project patterns
-    - exhaustruct_v5   # Requires all struct fields
+    - exhaustruct      # Requires all struct fields
+    - exhaustruct_v5   # Requires all struct fields (successor to exhaustruct)
     - godot            # Requires comments to end with periods
     - wrapcheck        # Too verbose for internal packages
     - varnamelen       # Short names like db, id are idiomatic Go
     # 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:
@@ -43,10 +40,7 @@ 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. 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.
+      # ends in `test`, are where that code belongs, and are exempt.
       #
       # 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
@@ -61,25 +55,24 @@ linters:
           files:
             - "$all"
             - "!$test"
-            - "!${base-path}**/*test/*"
+            - "!**/*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.
-    # Each entry names a module not to use and what to use instead. Every
-    # entry matches the module path exactly.
+    # Only decisions already recorded in the Go package defaults are
+    # listed here. Every entry matches the module path exactly.
     gomodguard_v2:
       blocked:
         - module: github.com/rs/zerolog
           recommendations:
             - log/slog
           reason: "Structured logging is stdlib log/slog."
-        # These entries cover only the github.com/go-redis/redis module paths,
-        # one entry per path, because the later releases are separate paths.
-        # A prefix match would be shorter but would also reach
-        # github.com/go-redis/redismock/v9, the test double for the successor
-        # these entries recommend.
+        # One entry per pre-fork module path, because the later releases
+        # are separate paths. A prefix match would be shorter but would
+        # also reach github.com/go-redis/redismock, the test double for
+        # the successor these entries recommend.
         - module: github.com/go-redis/redis
           recommendations:
             - github.com/redis/go-redis/v9
@@ -92,10 +85,6 @@ 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
@@ -104,19 +93,7 @@ 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,16 +2,8 @@
 # lint` or `script/lint`, which are themselves a docker build and would
 # recurse into a daemon that does not exist in a build step.
 #
-# In every stage, ARG CACHEBUST comes right after the step that installs
-# 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
+# node 22-alpine, 2026-02-22
+FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS lint
 
 WORKDIR /app
 
@@ -25,10 +17,8 @@ RUN yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always
 
 # Test phase, same shape and for the same reason.
 #
-# alpine 3.24.3, 2026-11-04
-FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS test
-RUN apk add --no-cache git make nodejs yarn
-ARG CACHEBUST
+# node 22-alpine, 2026-02-22
+FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS test
 
 WORKDIR /app
 
@@ -46,18 +36,16 @@ 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.
 #
-# alpine 3.24.3, 2026-11-04
-FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a
-RUN apk add --no-cache git make nodejs yarn
-ARG CACHEBUST
+# node 22-alpine, 2026-02-22
+FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34
 
 WORKDIR /app
 
 COPY --from=lint /app/package.json /dev/null
 COPY --from=test /app/package.json /dev/null
 
-# script/bootstrap finds the system packages above and installs the node
-# packages.
+# script/bootstrap installs all prerequisites. Manifests are copied
+# first so that layer stays cached until dependencies change.
 COPY script/ script/
 COPY package.json yarn.lock ./
 RUN script/bootstrap

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 other
-documents in $TD/prompts/ apply to this repo (API_POLICIES.md,
-CODE_STYLEGUIDE_GO.md, CODE_STYLEGUIDE_JS.md, CODE_STYLEGUIDE_PYTHON.md,
+claude "Read $TD/prompts/CODE_STYLEGUIDE.md and whichever
+language-specific styleguides in $TD/prompts/ apply to this repo
+(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 other
-documents in $TD/prompts/ apply to this repo (API_POLICIES.md,
-CODE_STYLEGUIDE_GO.md, CODE_STYLEGUIDE_JS.md, CODE_STYLEGUIDE_PYTHON.md,
+claude "Read $TD/prompts/CODE_STYLEGUIDE.md and whichever
+language-specific styleguides in $TD/prompts/ apply to this repo
+(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,26 +116,22 @@ 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 --build-arg CACHEBUST="$(date +%s)-$$" --target test --output type=cacheonly .`,
-  building the `test` phase of the `Dockerfile` without writing an image (no
-  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/test` — `docker build --no-cache --target test -t prompts-test .`,
+  building the `test` phase of the `Dockerfile` (no tests defined here)
+- `script/lint` — `docker build --no-cache --target lint -t prompts-lint .`,
+  building the `lint` phase, which runs prettier over the markdown files
 - `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 --build-arg CACHEBUST="$(date +%s)-$$" --build-arg VERSION="$version" -t prompts .`,
-  the tag coming from `script/projectname` (byte-identical across repos)
+  `docker build --no-cache --build-arg VERSION="$version" -t prompts .`, 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 --build-arg CACHEBUST="$(date +%s)-$$" --build-arg VERSION="$version" -t prompts .`
-  (what CI runs; it bootstraps because CI checks out and runs this alone while
+  `docker build --no-cache --build-arg VERSION="$version" -t prompts .` (what CI
+  runs; it bootstraps because CI checks out and runs this alone while
   `script/fmt-check` is native)
 - `script/precommit` — run by the git pre-commit hook (our own extension); calls
   `script/check`
@@ -144,23 +140,6 @@ 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,235 +21,6 @@ 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
@@ -258,15 +29,6 @@ fmt-check, and commit.
   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`

package.json

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

prompts/API_POLICIES.md

@@ -1,20 +0,0 @@
----
-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-10-18
+last_modified: 2026-10-04
 ---
 
 1.  Try to hard wrap long lines at 77 characters or less.
@@ -111,11 +111,8 @@ last_modified: 2026-10-18
     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 a new `CACHEBUST` value on
-    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
+    rather than a bare `docker build .`: they pass `--no-cache`, without which
+    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
@@ -151,9 +148,8 @@ last_modified: 2026-10-18
     handle HTTP requests. Don't use methods or your top level functions as
     handlers.
 
-1.  The repository's own entries at the end of `.gitignore`, which a re-vendor
-    keeps, ignore at least `*.log`, `*.out`, and `*.test` files, as well as any
-    binaries.
+1.  Provide a .gitignore file that ignores 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-11-04
+last_modified: 2026-02-22
 ---
 
 1. Use `const` for everything. If you need to reassign, use `let`. Never use
@@ -8,8 +8,7 @@ last_modified: 2026-11-04
 
 1. Use yarn for package management, avoid using npm.
 
-1. Install node from the distribution. If its version is too old, use a newer
-   distribution.
+1. Use LTS node versions.
 
 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-11-04
+last_modified: 2026-10-04
 ---
 
 Use this checklist when beginning work in a repo that may not yet conform to our
@@ -28,18 +28,13 @@ with your task.
       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
+- [ ] `.gitignore` is comprehensive (OS, editor, agent scratch, language
+      artifacts, secrets) — 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. 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.
+      so check the entries rather than the file's presence.
 - [ ] `.editorconfig` exists — fetch from
-      `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.
+      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`
 - [ ] `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
@@ -49,52 +44,6 @@ 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
@@ -114,50 +63,30 @@ with your task.
       here run anywhere other than the repo root, the anchored entry misses
       `services/api/.claude/`: add anchored entries for those directories.
 - [ ] If the repo embeds a version in a binary: `.dockerignore` lets `.git` into
-      the build context. It keeps out every git `config` at any depth
-      (`**/.git/config`, `**/.git/modules/**/config`):
-    - the repository's own
-    - 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.
-
+      the build context. It keeps out `.git/config` and each submodule's
+      `config` under `.git/modules/` at any depth (`.git/modules/**/config`),
+      which `git describe` does not need and which can hold a credential: a
+      password in a remote URL, or the token the CI checkout step stores there.
+      The stage that compiles has `git` (the Debian Go image has it; an alpine
+      one needs `apk add --no-cache git`) and takes the version from the
+      `VERSION` build argument when one is given, otherwise from
+      `git describe --tags --always`. That gives the tag on a tagged commit; on
+      a later commit, the tag, the number of commits since it and the short
+      commit (`v1.2.3-4-gabc1234`); and the short commit when no tag is
+      reachable. The stage that compiles also marks its working directory safe
+      for git (`git config --system --add safe.directory /src`): a context sent
+      as a tar stream keeps the sender's file owners, and git refuses a checkout
+      owned by another user, so the version would come out empty. `ARG VERSION`
+      has no default, and the build fails if the context carries `.git` and the
+      version still comes out empty, `dev` or `unknown`. A plain
+      `docker build .` with no build arguments must succeed; a Dockerfile that
+      refuses an empty build argument drops that refusal and keeps the argument.
+      `script/docker` and `script/cibuild` pass the version they compute on the
+      host; it takes precedence. A tag-derived version additionally needs
+      `fetch-depth: 0` on the CI checkout step, which clones shallow and fetches
+      no tags by default.
 - [ ] Gitea Actions workflow in `.gitea/workflows/` runs `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
+      push — reference
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitea/workflows/check.yml`
 - [ ] Language-specific config:
     - [ ] Go: `go.mod`, `go.sum`, `.golangci.yml` (fetch from
@@ -184,35 +113,25 @@ 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` each run
-      `docker build --build-arg CACHEBUST="$(date +%s)-$$" --target <phase> --output type=cacheonly .`,
-      which builds their phase by name and writes no image, and no host
-      invocation anywhere in the repo can produce a lint verdict — grep for the
-      linter's own name across `script/`, the `Makefile` and CI config, not just
-      `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
+- [ ] `script/lint` and `script/test` build their phase by name
+      (`docker build --no-cache --target <phase> -t <name>-<phase> .`), and no
+      host invocation anywhere in the repo can produce a lint verdict — grep for
+      the linter's own name across `script/`, the `Makefile` and CI config, not
+      just `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.
-- [ ] No `docker build` in `script/` leaves a dangling image behind:
-      `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.
+- [ ] Every `docker build` in `script/` is tagged — an untagged one leaves a
+      dangling image behind on every run, on every host and CI runner
 - [ ] `script/cibuild` runs `script/bootstrap` before `script/check`, and builds
-      the image with a new `CACHEBUST` value on every build, like every
-      `docker build` in `script/`. Without the bootstrap the CI run dies in
+      the image with `--no-cache`. Without the bootstrap the CI run dies in
       `script/fmt-check`, which runs the formatter on the host and finds nothing
       installed.
-- [ ] `script/bootstrap` installs node, yarn and the node packages only when
-      `yarn.lock` is in the tree. node and yarn come from the distribution when
-      they are missing. With `yarn.lock` in the tree, `script/bootstrap` stops
-      with a one-line message when yarn's major version is not 1.
-- [ ] 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`, they print one line saying to run
-      `script/bootstrap`, and exit 1.
+- [ ] `script/fmt` and `script/fmt-check` source nvm for the pinned node version
+      before invoking `yarn`, as `script/bootstrap`'s own install step does.
+      `script/bootstrap` leaves the node and yarn it installs off the `PATH` of
+      the shell that called it, so a bare `yarn` exits 127 on a runner carrying
+      nothing but docker and git.
 - [ ] `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
@@ -236,16 +155,7 @@ 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. 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
+      pinned by cryptographic hash with version/date comment
 - [ ] Using `yarn`, not `npm` (JS projects)
 
 # Directory Structure
@@ -274,17 +184,10 @@ with your task.
 # Final
 
 - [ ] `make check` passes
-- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has.
-      That host is the runner image
-      `docker.gitea.com/runner-images:ubuntu-latest`, which has docker, git and
-      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`
+- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying nothing but
+      docker and git, with no node or yarn on `PATH`, which is what CI has, and
+      demonstrably executed the checks — a sub-second build, or `CACHED` on a
+      gate layer, means nothing ran
 - [ ] 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/NEW_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: New Repo Checklist
-last_modified: 2026-11-04
+last_modified: 2026-10-04
 ---
 
 Use this checklist when creating a new repository from scratch. Follow the steps
@@ -34,17 +34,14 @@ Template files can be fetched from:
 ## Fetch Template Files
 
 - [ ] `.gitignore` — fetch from
-      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore`, then add
-      the repo's own build outputs, such as its binaries, at the end of the
-      file, where a re-vendor keeps them. Extensions are written to
-      `.gitignore`'s own semantics, where an unanchored pattern already matches
-      at every depth: never add a `**/` prefix here, which is a `.dockerignore`
-      form. The canonical file already carries `.claude/` so agent worktrees
-      cannot be committed by accident.
+      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore`, extend for
+      language-specific artifacts. Extensions are written to `.gitignore`'s own
+      semantics, where an unanchored pattern already matches at every depth:
+      never add a `**/` prefix here, which is a `.dockerignore` 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`, 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.
+      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`
 - [ ] `Makefile` — fetch from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`, adapt
       targets for the project's language and tools
@@ -74,105 +71,34 @@ Template files can be fetched from:
       will run them in subdirectories, `services/api/.claude/` needs its own
       anchored entry.
     - If the image embeds a version in a binary: `.dockerignore` lets `.git`
-      into the build context. It keeps out every git `config` at any depth
-      (`**/.git/config`, `**/.git/modules/**/config`):
-        - the repository's own
-        - 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.
-
+      into the build context. It keeps out `.git/config` and each submodule's
+      `config` under `.git/modules/` at any depth (`.git/modules/**/config`),
+      which `git describe` does not need and which can hold a credential: a
+      password in a remote URL, or the token the CI checkout step stores there.
+      The stage that compiles has `git` (the Debian Go image has it; an alpine
+      one needs `apk add --no-cache git`) and takes the version from the
+      `VERSION` build argument when one is given, otherwise from
+      `git describe --tags --always`. That gives the tag on a tagged commit; on
+      a later commit, the tag, the number of commits since it and the short
+      commit (`v1.2.3-4-gabc1234`); and the short commit when no tag is
+      reachable. The stage that compiles also marks its working directory safe
+      for git (`git config --system --add safe.directory /src`): a context sent
+      as a tar stream keeps the sender's file owners, and git refuses a checkout
+      owned by another user, so the version would come out empty. `ARG VERSION`
+      has no default, and the build fails if the context carries `.git` and the
+      version still comes out empty, `dev` or `unknown`. A plain
+      `docker build .` with no build arguments must succeed; a Dockerfile that
+      refuses an empty build argument drops that refusal and keeps the argument.
     - 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, 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
+      `script/cibuild` on push — 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
@@ -190,31 +116,18 @@ 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,
-      idempotently, and assumes nothing is present:
-    - It detects the package manager: nix, apt, brew or apk.
-    - It installs node, yarn and the node packages only when `yarn.lock` is in
-      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/bootstrap` / `make bootstrap` — installs all dependencies,
+      idempotently, assuming nothing (pkg manager detection nix/apt/brew/apk;
+      node used if present, else pinned version via nvm from a hash-verified
+      archive; pinned yarn via corepack); Dockerfile runs it instead of inline
+      installs
 - [ ] `script/setup` / `make setup` — readies a fresh clone: runs `bootstrap`,
       then `install-precommit`, plus repo-specific init
-- [ ] `script/test` / `make test` —
-      `docker build --build-arg CACHEBUST="$(date +%s)-$$" --target test --output type=cacheonly .`,
-      which writes no image; the phase runs real tests, not a no-op (90-second
-      timeout, 60-second hard cap on wall time)
-- [ ] `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/test` / `make test` — `docker build --no-cache --target test .`,
+      tagged; the phase runs real tests, not a no-op (90-second timeout,
+      60-second hard cap on wall time)
+- [ ] `script/lint` / `make lint` — `docker build --no-cache --target lint .`,
+      tagged. 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;
@@ -224,23 +137,20 @@ 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); a new `CACHEBUST`
-      value on every build, plus the version as a build arg
+      `script/projectname` (byte-identical across repos); `--no-cache`, plus the
+      version as a build arg
 - [ ] `script/cibuild` — cd to repo root, run `script/bootstrap`, run
       `script/check`, then
-      `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.
+      `docker build --no-cache --build-arg VERSION="$version" .` (what CI runs).
       The bootstrap is required: CI checks out and runs this alone, and
       `script/fmt-check` runs the formatter on the host.
-- [ ] `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`, they print one line saying to run
-      `script/bootstrap`, and exit 1.
-- [ ] No `docker build` in `script/` leaves a dangling image behind:
-      `script/lint` and `script/test` write no image, and `script/docker` and
-      `script/cibuild` tag theirs
+- [ ] `script/fmt` and `script/fmt-check` source nvm for the pinned node version
+      before invoking `yarn`, as `script/bootstrap`'s own install step does.
+      `script/bootstrap` leaves the node and yarn it installs off the `PATH` of
+      the shell that called it, so a bare `yarn` exits 127 on a runner carrying
+      nothing but docker and git.
+- [ ] Every `docker build` in `script/` is tagged, so no invocation leaves a
+      dangling image behind
 - [ ] `script/precommit` — called by the pre-commit hook; runs `script/check`
 - [ ] `script/install-precommit` — installs the pre-commit hook that runs
       `script/precommit`
@@ -252,31 +162,16 @@ are thin shims calling them. Model scripts:
 
 - [ ] `make check` passes
 - [ ] `make docker` succeeds
-- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has.
-      That host is the runner image
-      `docker.gitea.com/runner-images:ubuntu-latest`, which has docker, git and
-      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`
+- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying nothing but
+      docker and git, with no node or yarn on `PATH`, which is what CI has, and
+      demonstrably executed the checks — a sub-second build, or `CACHED` on a
+      gate layer, means nothing ran
 - [ ] 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. 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 mutable image/package references
 - [ ] No unnecessary files in repo root
 - [ ] All dates written as YYYY-MM-DD
 

script/bootstrap

@@ -1,18 +1,24 @@
 #!/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 tools, node and yarn come from nix,
-# apt, brew, or apk (detected in that order), with no version and no
-# hash, because the distribution is trusted. It installs node, yarn and
-# the node packages only when yarn.lock is in the tree. Assumes nothing
-# is present.
+# installed tools are skipped. Base tooling comes from nix, apt, brew,
+# or apk (detected in that order); assumes nothing is present. Node is
+# used directly if installed; otherwise it is installed at a pinned
+# version via nvm (installing nvm itself first, from a hash-verified
+# release archive, never curl | sh).
 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
@@ -41,14 +47,7 @@ pkg_install() {
     detect_pkgmgr
     case "$PKGMGR" in
         nix) nix-env -iA "nixpkgs.$1" ;;
-        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"
-            ;;
+        apt) $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y "$2" ;;
         brew) brew install "$3" ;;
         apk) apk add --no-cache "$4" ;;
     esac
@@ -58,42 +57,78 @@ missing() {
     ! command -v "$1" >/dev/null 2>&1
 }
 
-# Debian and Ubuntu name the yarn command yarnpkg.
-run_yarn() {
-    if command -v yarn >/dev/null 2>&1; then
-        yarn "$@"
-    elif command -v yarnpkg >/dev/null 2>&1; then
-        yarnpkg "$@"
+# verify_sha256 <file> <expected-hash>
+verify_sha256() {
+    if command -v sha256sum >/dev/null 2>&1; then
+        actual="$(sha256sum "$1" | cut -d' ' -f1)"
     else
-        echo "no yarn; run script/bootstrap first" >&2
+        actual="$(shasum -a 256 "$1" | cut -d' ' -f1)"
+    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
 
-    # A Dockerfile stage that needs no yarn copies no yarn.lock.
-    if [ -f yarn.lock ]; then
-        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
+    ensure_node
+    ensure_yarn
+    install_js_deps
 
     echo "bootstrap complete"
 }

script/cibuild

@@ -2,12 +2,9 @@
 # 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.
-# A new CACHEBUST value reruns every RUN step after the ARG CACHEBUST
-# 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.
+# --no-cache for the same reason as script/docker: the gate phases the
+# final stage depends on are RUN steps, and a cached one is a check that
+# did not run.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -17,17 +14,15 @@ main() {
     cd "$ROOT"
     "$SCRIPT_DIR/bootstrap"
     "$SCRIPT_DIR/check"
-    # The version and the tag each get their own line: a failing
-    # command substitution inside an argument does not trip `set -e`,
-    # so the inline form degrades silently to an empty constant. The
-    # VERSION build argument takes precedence over the version a build
-    # stage derives from the .git in the context.
+    # Own line: a failing command substitution inside an argument does
+    # not trip `set -e`, so the inline form degrades silently to an
+    # empty constant. The VERSION build argument takes precedence over
+    # the version a build stage derives from the .git in the context.
     version="$(git describe --tags --always --dirty 2>/dev/null || true)"
     [ -n "$version" ] || version="unknown"
-    tag="$("$SCRIPT_DIR/projectname")"
-    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
+    docker build --no-cache \
         --build-arg VERSION="$version" \
-        -t "$tag" .
+        -t "$("$SCRIPT_DIR/projectname")" .
 }
 
 main "$@"

script/docker

@@ -1,12 +1,8 @@
 #!/bin/sh
 # script/docker: build the Docker image tagged with the project name.
 # Identical in all repos; the tag comes from script/projectname.
-# A new CACHEBUST value reruns every RUN step after the ARG CACHEBUST
-# 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.
+# --no-cache because the gate phases the final stage depends on are RUN
+# steps, and a cached one is a check that did not run.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -14,17 +10,15 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    # The version and the tag each get their own line: a failing
-    # command substitution inside an argument does not trip `set -e`,
-    # so the inline form degrades silently to an empty constant. The
-    # VERSION build argument takes precedence over the version a build
-    # stage derives from the .git in the context.
+    # Own line: a failing command substitution inside an argument does
+    # not trip `set -e`, so the inline form degrades silently to an
+    # empty constant. The VERSION build argument takes precedence over
+    # the version a build stage derives from the .git in the context.
     version="$(git describe --tags --always --dirty 2>/dev/null || true)"
     [ -n "$version" ] || version="unknown"
-    tag="$("$SCRIPT_DIR/projectname")"
-    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
+    docker build --no-cache \
         --build-arg VERSION="$version" \
-        -t "$tag" .
+        -t "$("$SCRIPT_DIR/projectname")" .
 }
 
 main "$@"

script/fmt

@@ -4,16 +4,23 @@ set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
-# Debian and Ubuntu name the yarn command yarnpkg.
+# Must match the pin in script/bootstrap.
+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
-        yarn "$@"
-    elif command -v yarnpkg >/dev/null 2>&1; then
-        yarnpkg "$@"
-    else
-        echo "no yarn; run script/bootstrap first" >&2
+        exec yarn "$@"
+    fi
+    if [ ! -s "$HOME/.nvm/nvm.sh" ]; then
+        echo "fmt: 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,16 +4,23 @@ set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
-# Debian and Ubuntu name the yarn command yarnpkg.
+# Must match the pin in script/bootstrap.
+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
-        yarn "$@"
-    elif command -v yarnpkg >/dev/null 2>&1; then
-        yarnpkg "$@"
-    else
-        echo "no yarn; run script/bootstrap first" >&2
+        exec yarn "$@"
+    fi
+    if [ ! -s "$HOME/.nvm/nvm.sh" ]; then
+        echo "fmt-check: 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,14 +5,9 @@
 # make its answer untrustworthy.
 #
 # The phase is not the last stage in the file, so it is built only when
-# --target names it. A new CACHEBUST value reruns every RUN step after
-# the ARG CACHEBUST line, since a cached lint layer is a lint 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.
-# --output type=cacheonly writes no image, since nothing uses one.
+# --target names it. --no-cache because a cached lint layer is a lint
+# that did not run. The tag makes each build replace the previous image
+# instead of leaving a dangling one behind.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -20,9 +15,9 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
+    docker build --no-cache \
         --target lint \
-        --output type=cacheonly .
+        -t "$("$SCRIPT_DIR/projectname")-lint" .
 }
 
 main "$@"

script/test

@@ -2,13 +2,8 @@
 # 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, and a new CACHEBUST value because a cached test layer is a test
-# 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.
+# named, --no-cache because a cached test layer is a test that did not
+# run, and a tag so each build replaces the previous image.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -16,9 +11,9 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
+    docker build --no-cache \
         --target test \
-        --output type=cacheonly .
+        -t "$("$SCRIPT_DIR/projectname")-test" .
 }
 
 main "$@"