Re-vendor the canonical files from sneak/prompts at dd4027b (closes #95)

The shared files are the copies at sneak/prompts commit dd4027b, with this
repository's own entries kept after them. golangci-lint is v2.14.0 and
raises no findings. Lint and test are phases of the Dockerfile, built by
script/lint and script/test; the tests run under the race detector as
nobody, so Dockerfile.lint, script/verify-lint-image-pin and make
test-race are gone. Every docker build in script/ passes --no-cache in
place of the old cache-busting build argument, and script/cibuild runs
script/bootstrap and script/check before the image build.
.claude/settings.json is deleted.

Deviation: the workflow keeps fetch-depth: 0 for the tag-derived version.
Deviation: .gitignore keeps the scan database patterns.
Deviation: prettier still runs in Docker, not on the host.
Over the cap: make test takes about 60 seconds on this host.

Model: opus-5-5

.claude/settings.json

@@ -1,5 +0,0 @@
-{
-    "worktree": {
-        "bgIsolation": "none"
-    }
-}

.dockerignore

@@ -1,12 +1,79 @@
+# .dockerignore does NOT use .gitignore semantics. Docker matches with
+# moby/patternmatcher: filepath.Match plus `**`, so `*` does not cross
+# `/` and an unprefixed pattern is anchored at the context root. Every
+# depth-independent pattern therefore needs `**/`, or `config/.env` and
+# `certs/server.key` still ship while this file reads as solved. Only
+# genuinely root-anchored entries go unprefixed. Never transplant these
+# into .gitignore, where `**/` is wrong.
+#
+# Matching is case-sensitive, so secrets use character ranges rather
+# than an ALL-CAPS twin, which would still miss `Server.Key`.
+#
+# Extend with this repo's own host-built artifacts, written anchored:
+# `/myapp`, never `**/myapp`, which also matches `cmd/myapp/` and
+# deletes the package directory from the context.
+
 # .git is sent without its config. Without a VERSION build argument the
 # stage that compiles runs `git describe --tags --always` on .git, which
 # does not need .git/config; that file can hold a credential, such as a
 # password in a remote URL or the token the CI checkout step stores there.
-.git/config
+# Each submodule keeps a config with the same exposure in its git directory
+# under .git/modules/, nested again for a submodule's own submodules, or in
+# its own .git directory when it keeps one.
+# KNOWN GAP: a submodule whose name has a `config` segment (`config`,
+# `deploy/config`, `config/lib`) loses its whole git directory, because
+# `**/.git/modules/**/config` also matches that segment's directory
+# under .git/modules/. Go's version stamping then fails the build;
+# nothing leaks. Name such a submodule without that segment:
+# `git submodule add --name`.
+**/.git/config
+**/.git/modules/**/config
 
+# Agent scratch: one full checkout of the repo per in-flight agent.
+# Anchored because it occurs once where agents run at the repo root.
+# KNOWN GAP: a repo running agents in subdirectories still ships
+# `services/api/.claude/` and must add its own anchored entry.
 .claude
-.DS_Store
-sfdupes
-*.log
-*.out
-*.test
+
+# Environment files. `*.env` covers bare `.env` and the `prod.env`
+# convention. Re-include a committed template with a negation if the
+# build needs one: `!docs/example.env`.
+**/*.[eE][nN][vV]
+**/.[eE][nN][vV].*
+**/.[eE][nN][vV][rR][cC]
+
+# Private keys and the bundles carrying them. Public certificates
+# (*.crt, *.cer) are deliberately absent: they are legitimate inputs.
+**/*.[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]
+
+# Dependencies: restored inside the image, never copied in.
+**/node_modules
+
+# OS metadata.
+**/.DS_Store
+**/Thumbs.db
+
+# Editor state: never a build input, and it churns COPY.
+**/*.swp
+**/*.swo
+**/*~
+**/*.bak
+**/.idea
+**/.vscode
+**/*.sublime-*
+
+# This repository's host-built artifacts: the binary `make build` writes,
+# and test binaries, coverage output and logs.
+/sfdupes
+/*.test
+/*.out
+/*.log

.gitignore

@@ -11,25 +11,48 @@ Thumbs.db
 .vscode/
 *.sublime-*
 
+# Agent scratch (worktrees of this repo, created and destroyed by
+# in-flight tooling). Unanchored: .gitignore patterns already match at
+# every depth, so no prefix is wanted here. This is not a .dockerignore
+# entry and must not be given a `**/` prefix on the way into one.
+.claude/
+
 # Node
 node_modules/
 
-# Environment / secrets
-.env
-.env.*
-*.pem
-*.key
+# Secrets. Unanchored like every entry above, so each matches at every
+# depth. Matching is case-sensitive on Linux, so names use character
+# ranges rather than a lowercase form that misses `Server.Key`.
 
-# Go build artifacts
-/sfdupes
-*.test
-*.out
+# Environment files. `*.env` covers bare `.env` and the `prod.env`
+# convention. Only the templates `example.env` and `sample.env` are
+# re-included below. A repository that commits any other template adds
+# its own negation after these lines, for example `!.env.example`.
+*.[eE][nN][vV]
+.[eE][nN][vV].*
+.[eE][nN][vV][rR][cC]
+!example.env
+!sample.env
+
+# Private keys and the bundles carrying them.
+*.[pP][eE][mM]
+*.[kK][eE][yY]
+*.[pP]12
+*.[pP][fF][xX]
+[iI][dD]_[rR][sS][aA]
+[iI][dD]_[dD][sS][aA]
+[iI][dD]_[eE][cC][dD][sS][aA]
+[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK]
+[iI][dD]_[eE][dD]25519
+[iI][dD]_[eE][dD]25519_[sS][kK]
+
+# This repository's own entries, kept after the canonical content above.
 *.log
+*.out
+*.test
+/sfdupes
 
-# Local scan data
+# A scan database lists every path it scanned.
 *.sqlite
 *.sqlite-shm
 *.sqlite-wal
-
-# Agent worktrees
-.claude/worktrees/

.golangci.yml

@@ -10,14 +10,21 @@ run:
 
 linters:
   default: all
+  enable:
+    # Successor to the deprecated gomodguard. Named explicitly, rather than
+    # left to `default: all`, because it carries the module policy below.
+    - gomodguard_v2
   disable:
     # Genuinely incompatible with project patterns
     - exhaustruct      # Requires all struct fields
-    - depguard         # Dependency allow/block lists
+    - exhaustruct_v5   # Requires all struct fields (successor to exhaustruct)
     - godot            # Requires comments to end with periods
-    - wsl              # Deprecated, replaced by wsl_v5
     - 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.
+    - wsl              # Deprecated, replaced by wsl_v5
+    - gomodguard       # Deprecated, replaced by gomodguard_v2
   settings:
     lll:
       line-length: 88
@@ -28,6 +35,64 @@ linters:
       max-complexity: 15
     dupl:
       threshold: 100
+    depguard:
+      # Test-support code must not be compiled into the shipped binary. A
+      # 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.
+      #
+      # 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
+      # import path against a list of prefixes, so it cannot be told "any path
+      # whose last segment ends in test"; a repository's own test-support
+      # packages have to be named here one at a time, by full import path,
+      # under a module path that differs from repository to repository. Add
+      # them; change nothing else.
+      rules:
+        test-support:
+          list-mode: lax
+          files:
+            - "$all"
+            - "!$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.
+    # 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."
+        # 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
+          reason: "Pre-fork module; use the maintained go-redis v9."
+        - module: github.com/go-redis/redis/v7
+          recommendations:
+            - github.com/redis/go-redis/v9
+          reason: "Pre-fork module; use the maintained go-redis v9."
+        - module: github.com/go-redis/redis/v8
+          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
+          reason: "No unified diff output; use go-udiff."
+        - module: github.com/hexops/gotextdiff
+          recommendations:
+            - github.com/aymanbagabas/go-udiff
+          reason: "Unmaintained fork; use go-udiff."
 
 issues:
   max-issues-per-linter: 0

.prettierignore

@@ -0,0 +1,2 @@
+node_modules/
+yarn.lock

.prettierrc

@@ -0,0 +1,4 @@
+{
+    "tabWidth": 4,
+    "proseWrap": "always"
+}

Dockerfile

@@ -1,136 +1,88 @@
-# Lint stage — fast feedback on formatting and lint issues
-# golangci/golangci-lint:v2.12.2, 2026-08-07
-FROM golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240 AS lint
+# Lint phase, built alone by script/lint. The tools are invoked directly
+# rather than through `make lint` or `make fmt-check`, which run docker
+# themselves and so cannot run inside a build step.
+# golangci/golangci-lint:v2.14.0, 2026-10-07
+FROM golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f AS lint
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
 COPY . .
 
-# Cache-buster for the gate layers, and only for them. Docker
-# invalidates COPY only when the copied content changes, so on an
-# unchanged tree the gates below would be served from cache and the
-# build would exit 0 having run nothing. script/cibuild and
-# script/docker pass a fresh CHECK_EPOCH on every invocation.
+# The gofmt half of `make fmt-check`; the markdown stage is its prettier
+# half. gofmt's output is assigned to a variable first so that its own
+# exit status, as when it cannot parse a file, still fails the step.
+RUN files="$(gofmt -s -l .)" && \
+    if [ -n "$files" ]; then \
+        echo "gofmt: files not formatted:" >&2; echo "$files" >&2; exit 1; \
+    fi
+
+# Validates .golangci.yml against the schema the pinned binary embeds.
+RUN golangci-lint config verify --config .golangci.yml
+RUN golangci-lint run --config .golangci.yml ./...
+
+# Test phase, built alone by script/test. -race needs cgo and so a C
+# compiler, which the Debian Go image ships and the alpine one does not.
 #
-# Two properties this depends on. ARG is per-stage, so the build stage
-# below declares it again; one declaration here would leave that
-# stage's gate cacheable. And each gate RUN must reference the value,
-# because BuildKit hashes the expanded command: a declared but
-# unreferenced ARG invalidates nothing.
-#
-# It sits below the dependency layers deliberately. Everything above it
-# (the pinned base image, go mod download) keeps its cache; only the
-# gates go cold.
-ARG CHECK_EPOCH
-
-# The linter is invoked directly here, not through `make lint`. That
-# target now runs `docker build -f Dockerfile.lint`, and a docker build
-# cannot run a docker build: routing the gate through make would mean
-# nesting docker inside this image. Same reason `make check` is gone
-# from the build stage below. `make fmt-check` stays as it is — it is a
-# gate, not the aggregate, and it shells out to nothing.
-RUN echo "gate fmt-check, epoch ${CHECK_EPOCH}" && make fmt-check
-
-# The FROM above and the one in Dockerfile.lint pin the same linter
-# twice, and nothing else keeps them in sync; this fails the build when
-# they disagree. See the script for why it restates neither pin.
-RUN echo "gate lint-image-pin, epoch ${CHECK_EPOCH}" && \
-    script/verify-lint-image-pin
-
-# Same config-schema check Dockerfile.lint runs, kept here so this build
-# gates on exactly what script/lint gates on. It validates against a
-# schema the pinned binary embeds, so it needs no network.
-RUN echo "gate config verify, epoch ${CHECK_EPOCH}" && \
-    golangci-lint config verify --config .golangci.yml
-
-RUN echo "gate lint, epoch ${CHECK_EPOCH}" && \
-    golangci-lint run --config .golangci.yml ./...
-
-# Build stage
-# golang:1.25-alpine, 2026-07-23
-FROM golang@sha256:56961d79ea8129efddcc0b8643fd8a5416b4e6228cfd477e3fd61deb2672c587 AS builder
-
-# We never build or run as root. Create an unprivileged user and point
-# HOME and the build cache at its home so go build and go test can write
-# it when we drop to it below. $GOPATH/bin is deliberately not on PATH:
-# script/bootstrap no longer `go install`s anything (the linter runs
-# from a pinned image, never from a host install), so nothing lands
-# there and adding it would only widen what this image resolves.
-#
-# The module cache is kept outside that home, at the base image's
-# default /go/pkg/mod, and belongs to root: script/bootstrap fills it as
-# root. Do not move it into the home and hand it over with `chown -R`:
-# that walks every file in it, which took from about 80 s to over ten
-# minutes on a shared host, depending on load.
-RUN adduser -D -u 1000 builder
-ENV HOME=/home/builder
-ENV GOPATH=/home/builder/go
-ENV GOMODCACHE=/go/pkg/mod
-ENV GOCACHE=/home/builder/.cache/go-build
+# The tests run as nobody: several of them make a file unreadable and
+# expect reading it to fail, and root reads it anyway. nobody has no home
+# directory, so HOME is /tmp, where Go puts its build cache.
+# golang:1.25-trixie, 2026-10-04
+FROM golang@sha256:2c4c60ef415fbfa5e90300722293bef36c5e63fae17570ce18f580af933dbd73 AS test
+USER nobody
+ENV HOME=/tmp
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN go test -timeout 90s -race -cover ./... || \
+    { echo "--- Rerunning with -v for details ---"; \
+      go test -timeout 90s -race -v ./...; exit 1; }
 
+# Prettier stage: the prettier that formats this repository's Markdown,
+# never installed on a host. script/fmt and script/fmt-check build this
+# stage alone and run it with the repository mounted on /src. prettier
+# is installed in /tools so that the repository, mounted or copied onto
+# /src, cannot hide it.
+# node:22-alpine, 2026-02-22
+FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS prettier
+WORKDIR /tools
+# yarn.lock pins prettier by hash, and --frozen-lockfile fails rather
+# than install anything yarn.lock does not name.
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile
+ENV PATH=/tools/node_modules/.bin:$PATH
 WORKDIR /src
 
-# No-op file copy whose only purpose is the build-graph edge: it is what
-# makes this stage depend on the lint stage, and so what forces BuildKit
-# to finish fmt-check, the pin guard and lint before compilation and
-# tests start. Remove it and the fail-fast design dies silently — the
-# build stops gating on lint and still exits 0. It replaces a copy of
-# the linter binary itself, which is no longer wanted here: nothing in
-# this stage runs the linter, because `make lint` is now a docker build
-# and a docker build cannot run inside one.
-COPY --from=lint /src/go.sum /dev/null
+# Markdown stage: the Markdown half of `make fmt-check`, as a gate.
+FROM prettier AS markdown
+COPY . .
+RUN prettier --check '**/*.md' --tab-width 4 --prose-wrap always
 
-# Install development prerequisites the same way a developer does,
-# rather than duplicating the installs inline. Only script/ and the
-# dependency manifests are copied first, nothing else, so this layer
-# stays cached until the scripts or the dependencies change — bootstrap
-# ends in `go mod download`, which is why there is no separate
-# invocation of it here.
+# Build stage. Nothing is wanted from the lint, test and markdown stages;
+# the copies are what make BuildKit build them first, so this stage
+# cannot run unless all three passed.
+# golang:1.25-alpine, 2026-07-23
+FROM golang@sha256:56961d79ea8129efddcc0b8643fd8a5416b4e6228cfd477e3fd61deb2672c587 AS builder
+COPY --from=lint /src/go.sum /dev/null
+COPY --from=test /src/go.sum /dev/null
+COPY --from=markdown /src/go.sum /dev/null
+WORKDIR /src
+
+# script/bootstrap installs the git and make this image lacks, and ends
+# in `go mod download`.
 COPY script/ script/
 COPY go.mod go.sum ./
 RUN script/bootstrap
-
-# Hand builder only what it writes to, without walking the module cache.
-# This layer stays cached with bootstrap.
-# - /src itself: make build writes the binary into it, and git refuses
-#   a repository whose top directory belongs to another user.
-# - the module cache's cache/download directory itself, not what is in
-#   it: Go only reads the downloaded modules, but make build saves its
-#   lookup of this module's own version from git there, in a new
-#   directory named after the module path.
-# - builder's home: the go commands bootstrap ran as root left Go's
-#   telemetry files there, a few small files.
-RUN chown builder:builder /src /go/pkg/mod/cache/download && \
-    chown -R builder:builder /home/builder
-
-# The sources are handed to builder as they are copied, so no layer has
-# to walk them. Then drop root before running any checks or builds.
-COPY --chown=builder:builder . .
-USER builder
-
-# Fail the build unless the branch is green. Runs as non-root so the
-# permission-denied test paths are exercised legitimately (root would
-# bypass the chmod(0) the tests rely on).
-#
-# The gates are the individual targets, not `make check`: that aggregate
-# runs `script/lint`, which is now a docker build, and nothing inside an
-# image build may shell out to docker. Lint is not skipped by this — it
-# ran in the lint stage above, which this stage's COPY --from makes a
-# prerequisite. `make`, not the scripts directly, because the Makefile's
-# `export CGO_ENABLED = 0` applies only to what it invokes.
-#
-# Second per-stage declaration of the gate cache-buster; see the lint
-# stage above for why one is not enough. It is placed after USER so the
-# drop to the unprivileged user still happens before the checks run.
-ARG CHECK_EPOCH
-RUN echo "gate test, epoch ${CHECK_EPOCH}" && make test
-RUN echo "gate fmt-check, epoch ${CHECK_EPOCH}" && make fmt-check
+# A tar-stream context keeps the sender's file owners, which git refuses.
+RUN git config --system --add safe.directory /src
+COPY . .
 
 # The version stamped into the binary: the VERSION build argument when
 # one is given, otherwise `git describe --tags --always` of the .git in
-# the build context (git is installed by script/bootstrap above). A
-# context that carries .git and still yields no version fails the build;
-# with neither, as from a source tarball, it is "dev".
+# the build context. A context that carries .git and still yields no
+# version fails the build; with neither, as from a source tarball, it is
+# "dev". `make build` rather than `go build`, so the image and a host
+# build share one compile recipe, cgo disabled included.
 ARG VERSION
 RUN version="${VERSION:-$(git describe --tags --always || echo dev)}"; \
     if [ -e .git ] && { [ -z "$version" ] || [ "$version" = dev ] || \
@@ -140,7 +92,8 @@ RUN version="${VERSION:-$(git describe --tags --always || echo dev)}"; \
     fi; \
     make build VERSION="$version"
 
-# Runtime stage
+# Runtime stage, and the last one: a plain `docker build .` builds this
+# stage's chain and nothing else.
 # alpine:3.22, 2026-07-23
 FROM alpine@sha256:14358309a308569c32bdc37e2e0e9694be33a9d99e68afb0f5ff33cc1f695dce
 

Dockerfile.lint

@@ -1,59 +0,0 @@
-# Lint-only image: this is how the linter runs, everywhere. The repo is
-# COPYed into the pinned golangci-lint image and the linter runs as a
-# build step, so a successful build IS a clean lint. golangci-lint is
-# never installed on a host — one toolchain, pinned by digest, identical
-# on a laptop and in CI — and this works even when the docker daemon is
-# remote and bind mounts are impossible.
-#
-# script/lint builds this file. It is a separate image from the lint
-# stage of the main Dockerfile because script/lint must not depend on
-# the rest of that build; the two FROM lines are kept identical by
-# script/verify-lint-image-pin, run as a gate below.
-# golangci/golangci-lint:v2.12.2, 2026-08-07
-FROM golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240
-
-WORKDIR /src
-
-# Dependency layers first, so they stay cached across lint runs.
-COPY go.mod go.sum ./
-RUN go mod download
-
-COPY . .
-
-# Cache-buster for the gate layers, and only for them. Caching of the
-# lint run is waived by ruling: COPY is invalidated only by changed
-# content, so on an unchanged tree the gates below would be served from
-# cache and this build would exit 0 in under a second having run no
-# linter at all. That exact false green has bitten this repo twice
-# already (#32, #39). script/lint passes a fresh value on every
-# invocation.
-#
-# Each gate RUN must reference the value, because BuildKit hashes the
-# expanded command and not the ARG declaration: a declared but
-# unreferenced ARG invalidates nothing. The ARG sits below the
-# dependency layers deliberately — everything above it keeps its cache,
-# only the gates go cold.
-ARG CHECK_EPOCH
-
-# The linter version is pinned in two places, here and in the main
-# Dockerfile's lint stage. Nothing else keeps them in sync, so a
-# half-applied bump is a build failure; see the script.
-RUN echo "gate lint-image-pin, epoch ${CHECK_EPOCH}" && \
-    script/verify-lint-image-pin
-
-# Validates .golangci.yml against golangci-lint's JSON schema. The
-# concern about this step was that it fetches that schema over a live,
-# unpinned HTTPS call; measured on the pinned image, it does not. The
-# binary carries the schema for its own version, so under
-# `--network none` this both passes on a valid config and still rejects
-# an invalid one with the jsonschema error. That holds for the gate
-# steps generally — none of them makes a network call — but not for
-# this build as a whole: `go mod download` above needs the network on a
-# cold cache, and under `--network none` a first build fails there
-# before reaching any gate. That layer stays cached, so only a warm
-# cache lints offline, until go.mod or go.sum changes.
-RUN echo "gate config verify, epoch ${CHECK_EPOCH}" && \
-    golangci-lint config verify --config .golangci.yml
-
-RUN echo "gate lint, epoch ${CHECK_EPOCH}" && \
-    golangci-lint run --config .golangci.yml ./...

REPO_POLICIES.md

@@ -1,6 +1,6 @@
 ---
 title: Repository Policies
-last_modified: 2026-07-06
+last_modified: 2026-10-04
 ---
 
 This document covers repository structure, tooling, and workflow standards. Code
@@ -60,17 +60,28 @@ style conventions are in separate documents:
   prerequisite since nvm requires bash. yarn is then pinned via
   `corepack prepare yarn@<version> --activate`. Never install "latest" or "lts";
   always exact versions. `script/cibuild` runs the CI build: it changes to the
-  repo root and runs `docker build .`; the Gitea workflow calls it. Four further
-  scripts are our own extensions to the standard: `script/check` runs
-  `script/test`, `script/lint`, and `script/fmt-check`; `script/precommit` is
-  what the git pre-commit hook runs, and it calls `script/check`;
-  `script/install-precommit` installs the git pre-commit hook (the `make hooks`
-  target shims to it); and `script/projectname` (literally that filename) simply
-  outputs the project's name. Scripts that need the name call
-  `script/projectname` — e.g. `script/docker` assembles its image tag from it —
-  so those scripts stay byte-identical across all repos. Repo-type-specific
-  pre-commit extras (e.g. `go mod tidy` verification in Go repos) belong in
-  `script/precommit`, not in the hook itself. Model scripts are at
+  repo root, runs `script/bootstrap`, runs `script/check`, and builds the image
+  with the version; the Gitea workflow calls it. **`script/cibuild` runs
+  `script/bootstrap` first**, because the workflow checks out the repo and runs
+  nothing else, while `script/fmt-check` runs the formatter on the host: on a
+  pristine checkout with nothing installed the run dies there, after the
+  containerised gates have passed. **The bootstrap alone is not enough**:
+  `script/bootstrap` installs node and yarn under nvm and leaves neither on the
+  `PATH` of the shell that called it, so a bare `yarn` still exits 127. The host
+  entrypoints that need yarn — `script/fmt` and `script/fmt-check` — therefore
+  source nvm for the pinned node version before invoking it, exactly as
+  `script/bootstrap`'s own install step does. A runner carrying nothing but
+  docker and git then gets through `script/check`. Four further scripts are our
+  own extensions to the standard: `script/check` runs `script/test`,
+  `script/lint` and `script/fmt-check`; `script/precommit` is what the git
+  pre-commit hook runs, and it calls `script/check`; `script/install-precommit`
+  installs the git pre-commit hook (the `make hooks` target shims to it); and
+  `script/projectname` (literally that filename) simply outputs the project's
+  name. Scripts that need the name call `script/projectname` — e.g.
+  `script/docker` assembles its image tag from it — so those scripts stay
+  byte-identical across all repos. Repo-type-specific pre-commit extras (e.g.
+  `go mod tidy` verification in Go repos) belong in `script/precommit`, not in
+  the hook itself. Model scripts are at
   `https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`. The README
   must document the provided scripts in an **Entrypoints** section (see the
   README requirements below).
@@ -89,87 +100,198 @@ style conventions are in separate documents:
   contributor should be able to understand the entire development workflow by
   reading the Makefile.
 
-- Every repo should have a `Dockerfile`. All Dockerfiles must run `make check`
-  as a build step so the build fails if the branch is not green. For non-server
-  repos, the Dockerfile should bring up a development environment and run
-  `make check`. For server repos, `make check` should run as an early build
-  stage before the final image is assembled. Dockerfiles install development
-  prerequisites by running `script/bootstrap` rather than duplicating installs
-  inline; COPY `script/` and the dependency manifests (`package.json` +
-  `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it so the bootstrap
-  layer stays cached until dependencies change.
+- Every repo should have a `Dockerfile`, and it carries the repo's gates: a
+  `lint` phase and a `test` phase, with the final stage depending on both so the
+  image cannot be built unless they pass. For non-server repos the final stage
+  brings up a development environment; for server repos it is the runtime image.
+  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`
+  below does for `git`, or by running `script/bootstrap`, as the `prompts`
+  repo's own `Dockerfile` does for its yarn packages. The development
+  environment stage installs development prerequisites by running
+  `script/bootstrap` rather than duplicating its installs inline. A stage that
+  runs `script/bootstrap` COPYs `script/` and the dependency manifests
+  (`package.json` + `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it.
 
-- **Dockerfiles must use a separate lint stage for fail-fast feedback.** Go
-  repos use a multistage build where linting runs in an independent stage based
-  on the `golangci/golangci-lint` image (pinned by hash). This stage runs
-  `make fmt-check` and `make lint` before the full build begins. The build stage
-  then declares an explicit dependency on the lint stage via
-  `COPY --from=lint /src/go.sum /dev/null`, which forces BuildKit to complete
-  linting before proceeding to compilation and tests. This ensures lint failures
-  surface in seconds rather than minutes, without blocking on dependency
-  download or compilation in the build stage.
+- **Linting and testing run in Docker, as phases of the `Dockerfile`.** There is
+  no separate lint file. `script/lint` and `script/test` each build one phase
+  and nothing else:
 
-    The standard pattern for a Go repo Dockerfile is:
+    ```sh
+    docker build --no-cache --target lint -t "$(script/projectname)-lint" .
+    docker build --no-cache --target test -t "$(script/projectname)-test" .
+    ```
+
+    **A stage that is not the last one in the file is built only when the final
+    stage's chain depends on it, or when `--target` names it.** That is why the
+    two gates are always invoked by name here, and why the final stage carries a
+    `COPY --from=` of a harmless file from each of them: without that edge a
+    plain `docker build .` builds the last stage alone and exits 0 having linted
+    and tested nothing.
+
+    **Every `docker build` in `script/` is tagged**, here and in
+    `script/cibuild` and `script/docker`. An untagged build leaves a dangling
+    image behind on every invocation, on every developer host and every CI
+    runner; a tagged one replaces the previous image.
+
+    Inside a phase the tool is invoked directly — `golangci-lint`, `go test`,
+    `eslint`, `prettier` — never through `make lint` or `script/test`, which are
+    themselves a `docker build` and would recurse into a daemon that does not
+    exist in a build step. Formatting is the exception and stays on the host:
+    `script/fmt` writes the working tree, and `script/fmt-check` is its
+    read-only twin.
+
+    **No lint verdict may come from a host invocation of the linter.** On a
+    shared host golangci-lint reads a result cache keyed on file content rather
+    than location, so a second checkout of the same content is served the first
+    one's findings, and a host-global lock in `$TMPDIR` makes concurrent runs
+    exit non-zero with `parallel golangci-lint is running` — a status a caller
+    cannot tell from real findings. Both have produced wrong verdicts in this
+    org, in both directions. A container has its own cache, its own `TMPDIR` and
+    a digest-pinned binary, so neither is reachable.
+
+- **Any build that runs checks is built with `--no-cache`.** Docker invalidates
+  a `COPY` layer only when the copied content changes, so on an unchanged tree
+  the check `RUN` is served from cache, nothing executes, and the build still
+  exits 0. Every `docker build` in `script/` therefore passes `--no-cache`:
+  `script/lint`, `script/test`, `script/cibuild` and `script/docker` are the
+  four, and there is no fifth — `script/check` runs the two gate phases and
+  `script/fmt-check`, and builds no image of its own. A bare `docker build .` is
+  not evidence that anything ran: a sub-second build reporting success is a
+  cache hit, not a result. Never invalidate by pruning — `docker builder prune`
+  and friends destroy a build cache shared with every other build on the host.
+  When a check is added or changed, prove it works by planting a defect it must
+  catch and watching the run fail on it, then revert the defect. A green run
+  alone shows neither that the check ran nor that it covers what it should.
+
+- **The gate phases are separate stages, and the build stage depends on both.**
+  The lint phase is based on the `golangci/golangci-lint` image (pinned by
+  hash), so lint failures surface in seconds rather than after a full compile,
+  and the test phase is based on the Debian Go image. The canonical Go repo
+  `Dockerfile`:
 
     ```dockerfile
-    # Lint stage — fast feedback on formatting and lint issues
+    # Lint phase
     # golangci/golangci-lint:v2.x.x, YYYY-MM-DD
     FROM golangci/golangci-lint@sha256:... AS lint
     WORKDIR /src
     COPY go.mod go.sum ./
     RUN go mod download
     COPY . .
-    RUN make fmt-check
-    RUN make lint
+    RUN golangci-lint run --config .golangci.yml ./...
 
-    # Build stage
-    # golang:1.x-alpine, YYYY-MM-DD
-    FROM golang@sha256:... AS builder
+    # Test phase. -race needs cgo and so a C compiler, which the Debian Go
+    # image ships and the alpine one does not.
+    # golang:1.x, YYYY-MM-DD
+    FROM golang@sha256:... AS test
     WORKDIR /src
-
-    # Force BuildKit to run the lint stage before proceeding
-    COPY --from=lint /src/go.sum /dev/null
-
     COPY go.mod go.sum ./
     RUN go mod download
     COPY . .
-    RUN make test
+    RUN go test -timeout 90s -race -cover ./... || \
+        { echo "--- Rerunning with -v for details ---"; \
+          go test -timeout 90s -race -v ./...; exit 1; }
 
-    ARG VERSION=dev
-    RUN CGO_ENABLED=0 go build -trimpath \
-        -ldflags="-s -w -X main.Version=${VERSION}" \
-        -o /app ./cmd/app/
+    # Build stage. Nothing is wanted from either phase above; the copies
+    # are what make BuildKit build them first, so this stage cannot run
+    # unless lint and test passed.
+    # golang:1.x-alpine, YYYY-MM-DD
+    FROM golang@sha256:... AS builder
+    COPY --from=lint /src/go.sum /dev/null
+    COPY --from=test /src/go.sum /dev/null
+    RUN apk add --no-cache git
+    # A tar-stream context keeps the sender's file owners, which git refuses.
+    RUN git config --system --add safe.directory /src
+    WORKDIR /src
+    COPY go.mod go.sum ./
+    RUN go mod download
+    COPY . .
 
-    # Runtime stage
+    # The VERSION build arg when one is given, otherwise
+    # `git describe --tags --always` on the .git in the build context. With
+    # .git present, a version that is still empty, dev or unknown fails the
+    # build: git is missing or could not read the checkout.
+    ARG VERSION
+    RUN VERSION="${VERSION:-$(git describe --tags --always)}"; \
+        if [ -e .git ]; then \
+            case "$VERSION" in ""|dev|unknown) \
+                echo "version is '$VERSION' although .git is present" >&2; \
+                exit 1 ;; \
+            esac; \
+        fi; \
+        CGO_ENABLED=0 go build -trimpath \
+            -ldflags="-s -w -X main.Version=${VERSION}" \
+            -o /app ./cmd/app/
+
+    # Runtime stage, and the last one
     FROM alpine@sha256:...
     COPY --from=builder /app /usr/local/bin/app
     ENTRYPOINT ["app"]
     ```
 
     Key points:
-    - The lint stage uses the `golangci/golangci-lint` image directly (it
-      includes both Go and the linter), so there is no need to install the
-      linter separately.
-    - `COPY --from=lint /src/go.sum /dev/null` is a no-op file copy that creates
-      a stage dependency. BuildKit runs stages in parallel by default; without
-      this line, the build stage would not wait for lint to finish and a lint
-      failure might not fail the overall build.
+    - The lint phase uses the `golangci/golangci-lint` image directly (it has
+      both Go and the linter), so nothing needs installing.
+    - `COPY --from=<phase> /src/go.sum /dev/null` is a no-op copy whose only
+      purpose is the ordering edge. BuildKit runs stages in parallel by default,
+      and a stage nothing depends on is not built at all, so without these two
+      lines a red gate would not fail the build.
+    - Keep the runtime stage last, and if you add a stage after it, give it the
+      same two copies. A plain `docker build .` builds the last stage's chain
+      and nothing else.
     - If the project uses `//go:embed` directives that reference build artifacts
-      (e.g. a web frontend compiled in a separate stage), the lint stage must
+      (e.g. a web frontend compiled in a separate stage), the lint phase must
       create placeholder files so the embed directives resolve. Example:
       `RUN mkdir -p web/dist && touch web/dist/index.html web/dist/style.css`.
-      The lint stage should not depend on the actual build output — it exists to
-      fail fast.
-    - If the project requires CGO or system libraries for linting (e.g.
-      `vips-dev`), install them in the lint stage with `apk add`.
-    - The build stage runs `make test` after compilation setup. Tests run in the
-      build stage, not the lint stage, because they may require compiled
-      artifacts or heavier dependencies.
+    - If the project requires CGO or system libraries for linting, install them
+      in the lint phase. The `golangci/golangci-lint` image is Debian-based and
+      has no `apk`, so install with `apt-get` under the Debian package name
+      (`libvips-dev`, where alpine says `vips-dev`), and delete the package
+      lists in the same `RUN`, so the layer does not keep them:
+
+        ```dockerfile
+        RUN apt-get update \
+            && apt-get install -y --no-install-recommends libvips-dev \
+            && rm -rf /var/lib/apt/lists/*
+        ```
+
+    - `.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/`, and 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. A submodule whose name has a
+      `config` segment (`config`, `deploy/config`, `config/lib`) loses its whole
+      git directory to `**/.git/modules/**/config`, and Go's version stamping
+      then fails the build: give it a name without that segment
+      (`git submodule add --name`). The stage that compiles has `git` (the
+      Debian Go image has it; an alpine one needs `apk add --no-cache git`) and
+      takes the version from the `VERSION` build argument when one is given,
+      otherwise from `git describe --tags --always`. That gives the tag on a
+      tagged commit; on a later commit, the tag, the number of commits since it
+      and the short commit (`v1.2.3-4-gabc1234`); and the short commit when no
+      tag is reachable. The stage that compiles also marks its working directory
+      safe for git (`git config --system --add safe.directory /src`): a context
+      sent as a tar stream keeps the sender's file owners, and git refuses a
+      checkout owned by another user, so the version would come out empty.
+      `ARG VERSION` has no default, and the build fails if the context carries
+      `.git` and the version still comes out empty, `dev` or `unknown`. A plain
+      `docker build .` with no build arguments must succeed; a Dockerfile that
+      refuses an empty build argument drops that refusal and keeps the argument.
 
 - Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
-  runs `script/cibuild` (which runs `docker build .`) on push. Since the
-  Dockerfile already runs `make check`, a successful build implies all checks
-  pass.
+  runs `script/cibuild` on push, and checks out the repo as its only other step.
+  That script bootstraps, runs the gate phases, and then builds the image, so a
+  successful run means every check passed; a bare `docker build .` does not
+  carry the same guarantee, because its gate phases may come from the cache. The
+  image build is uncached and so runs the gate phases a second time. That is the
+  price of the rule above, and it is worth paying: the image that ships is built
+  from a run of its own gates rather than from a cache entry. A separate
+  workflow limited to `main` by a `branches` list under `on: push` cannot be
+  checked by review: to try a change to it, add the feature branch to that list
+  and push, then remove the branch from the list again before merging. Keep any
+  job in it that publishes behind `if: github.ref_name == 'main'`, so the run
+  from the feature branch publishes nothing.
 
 - Use platform-standard formatters: `black` for Python, `prettier` for
   JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
@@ -189,14 +311,21 @@ style conventions are in separate documents:
   module under test to verify it compiles/parses. There is no excuse for
   `make test` to be a no-op.
 
-- `make test` must complete in under 20 seconds. Add a 30-second timeout in the
-  Makefile.
+- `make test` must complete in under 60 seconds. That is the hard cap, and a
+  suite that exceeds it fails. Under 20 seconds is the target. A suite between
+  20 and 60 seconds is still green, but the overage must be filed as an
+  improvement bug against that repo. Add a 90-second timeout to the test
+  invocation (`go test -timeout 90s`). The backstop deliberately sits above the
+  hard cap so that it catches a genuinely hung test rather than a merely slow
+  one.
 
-- **`make test` should use the conditional verbose rerun pattern.** Run tests
-  without `-v` (verbose) first. If tests fail, automatically rerun with `-v` to
-  show full output. This keeps CI logs and `docker build` output clean on
-  success (just package/suite summaries) while providing full diagnostic detail
-  on failure (every test case, every assertion). The general shell pattern:
+- **The test command should use the conditional verbose rerun pattern.** Run
+  tests without `-v` (verbose) first. If tests fail, automatically rerun with
+  `-v` to show full output. This keeps CI logs and `docker build` output clean
+  on success (just package/suite summaries) while providing full diagnostic
+  detail on failure (every test case, every assertion). The command lives in the
+  `test` phase of the `Dockerfile`, since `script/test` builds that phase; the
+  Makefile form below is the same pattern for any repo-local invocation:
 
     ```makefile
     test:
@@ -209,11 +338,26 @@ style conventions are in separate documents:
 
     ```makefile
     test:
-    	@go test -timeout 30s -race -cover ./... || \
+    	@go test -count=1 -timeout 90s -race -cover ./... || \
     		{ echo "--- Rerunning with -v for details ---"; \
-    		  go test -timeout 30s -race -v ./...; exit 1; }
+    		  go test -count=1 -timeout 90s -race -v ./...; exit 1; }
     ```
 
+    `-count=1` is required on both invocations: it defeats Go's test _result_
+    cache, so neither run can report a stored pass in place of running the
+    tests. It leaves the build cache alone, so it costs the runtime of the suite
+    and no recompilation.
+
+    That cache is Go's own, separate from Docker's layer cache. Go stores a
+    passing result in its cache directory (`GOCACHE`), and when the same tests
+    run again on unchanged code it prints that result, marked `(cached)`,
+    without running them. That matters on a developer's machine, where this
+    target runs and the directory lasts from one run to the next. The `test`
+    phase of the `Dockerfile` needs no `-count=1`: its base image holds no
+    result for this repo's tests and nothing before its `go test` step runs a
+    test, so there is nothing to replay. `--no-cache` (above) is what makes that
+    step run on an unchanged tree.
+
     Python example:
 
     ```makefile
@@ -239,10 +383,84 @@ style conventions are in separate documents:
   must be in `.gitignore`. No exceptions.
 
 - `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
-  editor files (`.swp`, `*~`), language build artifacts, and `node_modules/`.
-  Fetch the standard `.gitignore` from
-  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up
-  a new repo.
+  editor files (`.swp`, `*~`), in-repo agent scratch directories (`.claude/`),
+  language build artifacts, and `node_modules/`. Fetch the standard `.gitignore`
+  from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when
+  setting up a new repo. These patterns are written to `.gitignore`'s own
+  semantics, in which an unanchored pattern already matches at every depth; they
+  are not a `.dockerignore` and must not be transplanted into one unmodified.
+
+- **`.dockerignore` does not use `.gitignore` semantics, and copying patterns
+  across unmodified leaves secrets in the build context.** Docker matches with
+  `moby/patternmatcher`: `filepath.Match` semantics plus a `**` extension, so
+  `*` does not cross `/` and a pattern without a leading `**/` is anchored at
+  the build-context root. A `.dockerignore` listing `.env`, `*.pem` and `*.key`
+  therefore excludes only the copies at the repository root, while `config/.env`
+  and `certs/server.key` still reach the context and can land in an image layer
+  — which is more dangerous than a short file with no secret patterns at all,
+  because it reads as solved and stops anyone looking. Give every
+  depth-independent pattern the `**/` prefix and leave only genuinely
+  root-anchored entries unprefixed: `.claude`, and the repo's own host-built
+  binary, written `/myapp` and never `**/myapp`, which would also match
+  `cmd/myapp/` and delete the package directory from the context. Matching is
+  case-sensitive, and an ALL-CAPS twin per pattern still misses `Server.Key`, so
+  secret names use character ranges — `**/*.[kK][eE][yY]`, `**/*.[pP][eE][mM]`,
+  and likewise for `.envrc` and the extensionless SSH keys. Where such a pattern
+  also catches something the build needs, re-include it with a negation
+  (`!docs/example.env`); deleting the pattern reopens the exposure for every
+  other file it covers. Fetch the standard `.dockerignore` from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` and extend
+  it with the repo's own artifacts.
+
+- **In-repo agent scratch belongs in both files, written to each file's own
+  semantics.** `.claude/` holds one worktree per in-flight agent — an entire
+  additional checkout of the repo — so under `COPY . .` the build context
+  inflates by a multiple of the repo and another session's unreviewed work can
+  be copied into an image layer. In `.gitignore` the entry is `.claude/`,
+  unanchored. In `.dockerignore` it is `.claude`, anchored and with **no** `**/`
+  prefix, because the prefixed form would also delete any nested directory of
+  that name from the build. Anchoring carries a known gap that the canonical
+  `.dockerignore` states in its own comment, since consuming repos receive the
+  file and not the tracker: the directory is created in the agent's working
+  directory, so a repo running agents in subdirectories still ships
+  `services/api/.claude/` and must add its own anchored entry there.
+
+- **A plain `docker build .` of a clone stamps the version that
+  `git describe --tags --always` gives**, derived from the `.git` in the build
+  context as the canonical `Dockerfile` above shows. Without its failure check,
+  a missing `git` or an unreadable checkout would leave `-X main.Version=` empty
+  and the build would still exit 0. `script/docker` and `script/cibuild` pass
+  the version they compute on the host; it takes precedence. They do this
+  byte-identically across repos:
+
+    ```sh
+    # Own line: a failing command substitution inside an argument does not
+    # trip `set -e`, so the inline form degrades to an empty constant.
+    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    [ -n "$version" ] || version="unknown"
+    docker build --no-cache \
+        --build-arg VERSION="$version" \
+        -t "$(script/projectname)" .
+    ```
+
+    `--always` makes an untagged repo yield an abbreviated commit hash rather
+    than failing, and the `[ -n "$version" ]` line is the single place the
+    fallback is applied — a live check that fires on a build from an export with
+    no `.git` and on a repository with no commits yet. Do not fold it into the
+    substitution as `|| echo unknown`, which makes the guard unreachable. The
+    Dockerfile's side is `ARG VERSION` in the stage that compiles, declared
+    there because `ARG` is stage-scoped; passing `VERSION` to a repo whose
+    Dockerfile declares no such `ARG` is ignored and costs nothing, which is why
+    the scripts stay byte-identical. One consequence for CI: the standard
+    checkout action clones shallow and fetches no tags, so a repo that embeds a
+    tag-derived version must set `fetch-depth: 0` on its checkout step.
+
+- **Verify `.dockerignore` by enumerating the image, not by reading the
+  patterns.** Plant files at the root _and_ at least two directories deep, build
+  a probe image that does `COPY . .`, and list what actually landed
+  (`docker run --rm --entrypoint find IMAGE /app`). The `transferring context`
+  size is not a substitute: a nested secret is a few bytes, and BuildKit
+  transfers only the delta from the previous build.
 
 - **No build artifacts in version control.** Code-derived data (compiled
   bundles, minified output, generated assets) must never be committed to the
@@ -258,9 +476,56 @@ style conventions are in separate documents:
 - Make all changes on a feature branch. You can do whatever you want on a
   feature branch.
 
-- `.golangci.yml` is standardized and must _NEVER_ be modified by an agent, only
-  manually by the user. Fetch from
-  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`.
+- `.golangci.yml` is standardized. The vendored copy in a consuming repo must
+  _NEVER_ be modified by an agent: fetch it from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml` and keep it
+  byte-identical, so that no repo can quietly loosen its own linting. Linter
+  configuration changes are made to the canonical copy in the `prompts` repo and
+  reach consuming repos by re-vendoring; an agent may open a PR against
+  canonical, which only the user merges. One list is exempt from byte-identity,
+  because it cannot be written once for every repo: the `deny` list of the
+  `test-support` depguard rule, where a repo names its own test-support packages
+  by full import path. A repo adds entries there and changes nothing else, and a
+  re-vendor carries its entries forward. The canonical golangci-lint version is
+  v2.14.0 (released 2026-09-24), pinned as the digest of the lint phase's base
+  image
+  (`golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f`,
+  which reports `2.14.0 built with go1.27.0 from 114493f9`). A module's `go`
+  directive must not name a newer Go minor version than the one golangci-lint
+  was built with, or golangci-lint refuses to lint it: this release lints
+  `go 1.27.1` but not `go 1.28`. That digest is the only pin, since no repo
+  installs golangci-lint on the host. A repo sets the lint phase digest to the
+  one named here and re-vendors `.golangci.yml` in the same commit, whichever of
+  the two prompted the change: the canonical copy can name linters that an older
+  golangci-lint rejects, and a newer golangci-lint can add linters that
+  `default: all` switches on until the canonical copy disables them.
+
+- **`script/bootstrap` installs a pinned tool by comparing versions, never by
+  testing presence.** An `if ! command -v <tool>; then install; fi` guard tests
+  `PATH` only, so on an already-provisioned machine the pin is inert and a
+  version bump is a silent no-op — while the Dockerfile, installing into a clean
+  image, gets the pinned version, so a local `make check` and `make docker` can
+  disagree about what the tool even is. The canonical form:
+    - compares the installed version against the pin over the **whole** version
+      token; a parser that stops at the first `-` reports `2.12.2` for a host
+      running `2.12.2-rc1` and skips the install;
+    - treats absent, non-zero, empty or unrecognised `--version` output as a
+      mismatch, so the failure direction is a redundant install and never a
+      skipped one;
+    - after installing, re-resolves the binary the way callers do — `hash -r`,
+      then through `PATH`, not through the directory the installer wrote to —
+      and fails naming the resolved path, since an install that a shadowing
+      binary hides succeeds while changing nothing any caller sees;
+    - is actually called, and prints the version on both success paths: a
+      function defined and never invoked has the same exit status and the same
+      empty output as one that worked.
+
+    Keep it POSIX sh: no arrays, no `[[`, no `grep -P`.
+
+    A Go tool a repo needs on the host is installed with `go install` pinned to
+    a commit hash (`go install <package>@<commit hash>`). It is never tracked as
+    a `go.mod` tool dependency or through a `tools.go` file, either of which
+    pulls the tool's own dependencies into the repo's `go.mod` and `go.sum`.
 
 - When pinning images or packages by hash, add a comment above the reference
   with the version and date (YYYY-MM-DD).
@@ -374,12 +639,14 @@ style conventions are in separate documents:
   settings.
 
 - Avoid putting files in the repo root unless necessary. Root should contain
-  only project-level config files (`README.md`, `Makefile`, `Dockerfile`,
-  `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, and
-  language-specific config). Everything else goes in a subdirectory. Canonical
-  subdirectory names:
+  only project-level config files (`README.md`, `AGENTS.md`, `Makefile`,
+  `Dockerfile`, `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`,
+  and language-specific config). Everything else goes in a subdirectory.
+  Canonical subdirectory names:
     - `bin/` — executable scripts and tools
-    - `cmd/` — Go command entrypoints
+    - `cmd/` — Go command entrypoints; thin only: one `main.go` per binary whose
+      body is a single call into `internal/` or `pkg/`, no project logic in
+      `cmd/`
     - `configs/` — configuration templates and examples
     - `deploy/` — deployment manifests (k8s, compose, terraform)
     - `docs/` — documentation and markdown (README.md stays in root)
@@ -406,3 +673,7 @@ style conventions are in separate documents:
     - Go: `go.mod`, `go.sum`, `.golangci.yml`
     - JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
     - Python: `pyproject.toml`
+
+- Guidance for coding agents lives in one `AGENTS.md` at the repository root. It
+  is never committed under a file or directory named after one agent tool, such
+  as `CLAUDE.md` or `.claude/`, and never split into separate memory files.

TODO.md

@@ -1,36 +1,82 @@
 # Workflow
 
-- take an issue from the `1.0.0` milestone on the tracker; work not
-  yet on the tracker gets filed as an issue first
-- branch (from `main`)
+- take an issue from the `1.0.0` milestone on the tracker; work not yet on the
+  tracker gets filed as an issue first
+- branch from `next`
 - do the work, with tests, in small focused commits
-- record it at the top of Completed Steps (`TODO.md` changes in the
-  same commit as the work)
-- push the branch and open a PR whose title ends with
+- record it at the top of Completed Steps (`TODO.md` changes in the same commit
+  as the work)
+- push the branch and open a PR against `next` whose title ends with
   ` (closes #N)`
-- an independent review gates the merge; every finding is addressed
+- an independent review gates each merge to `next`; every finding is addressed
   or explicitly rebutted on the PR
-- merge to `main` once the review passes
+- only the owner merges `next` to `main`
 
 # Status
 
 - pre-1.0
-- the Gitea tracker is authoritative for the pre-1.0 backlog: the
-  open issues under the `1.0.0` milestone are what remains before
-  the tag, and this file records history and process, not the queue
+- the Gitea tracker is authoritative for the pre-1.0 backlog: the open issues
+  under the `1.0.0` milestone are what remains before the tag, and this file
+  records history and process, not the queue
 
 # Next Step
 
 - take the next issue from the `1.0.0` milestone on the tracker:
-  https://git.eeqj.de/sneak/sfdupes/milestone/17 — the milestone is
-  the source of truth for what is left before 1.0.0. Individual
-  issues are deliberately not restated here; a copy in this file
-  drifts out of date the moment the tracker moves
+  https://git.eeqj.de/sneak/sfdupes/milestone/17 — the milestone is the source
+  of truth for what is left before 1.0.0. Individual issues are deliberately not
+  restated here; a copy in this file drifts out of date the moment the tracker
+  moves
 
 # Completed Steps
 
-- test that `scan` refuses a database with another schema version
-  (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/64)
+- re-vendor the canonical files from `sneak/prompts` commit `dd4027b`:
+  golangci-lint v2.14.0; lint and test are phases of the `Dockerfile`, and
+  `make test` runs the suite under the race detector, so `Dockerfile.lint`,
+  `script/verify-lint-image-pin` and `make test-race` are gone; every
+  `docker build` in `script/` passes `--no-cache`; `.claude/settings.json` is
+  deleted (2026-10-07, https://git.eeqj.de/sneak/sfdupes/issues/95)
+
+- cut the narration from `TODO.md` Completed Steps and from the comments in
+  `script/` and both Dockerfiles; §Workflow now branches from and merges to
+  `next` (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/49)
+
+- `make test-race` runs the test suite under the race detector in a cgo-enabled
+  container, outside `make check` (2026-10-04,
+  https://git.eeqj.de/sneak/sfdupes/issues/18)
+
+- a bare `docker build .` fails with a message naming `script/cibuild` and
+  `script/docker` instead of serving the gates from cache (2026-10-04,
+  https://git.eeqj.de/sneak/sfdupes/issues/39)
+
+- `make fmt` and `make fmt-check` run prettier over all Markdown, in Docker, and
+  CI checks it; all Markdown reformatted (2026-10-04,
+  https://git.eeqj.de/sneak/sfdupes/issues/19)
+
+- `script/lint` writes no image, so a run no longer leaves an untagged one
+  behind (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/48)
+
+- tests cover a missing database, `scan` keeping stdout empty, its skip warning,
+  the `report` and `trees` summary lines, and every subcommand going through
+  `runE` (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/16)
+
+- `.golangci.yml` replaced with the current canonical copy, which uses
+  `gomodguard_v2`, so lint no longer prints a deprecation warning (2026-10-04,
+  https://git.eeqj.de/sneak/sfdupes/issues/26)
+
+- a test fails when either `hashWorker` cancellation check in `scan.go` is
+  removed (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/83)
+
+- a database path holding `?`, `#` or `%` opens exactly the file it names
+  (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/55)
+
+- `scan` rejects `--workers` below 1 as a usage error instead of running
+  single-threaded (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/10)
+
+- a test fails when either walk cancellation check in `scan.go` is removed
+  (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/81)
+
+- test that `scan` refuses a database with another schema version (2026-10-04,
+  https://git.eeqj.de/sneak/sfdupes/issues/64)
 
 - correct four inaccurate comments in `cancel_test.go` and rename
   `walkCancelInFlightDirs` to `walkCancelInFlightFiles` (2026-10-04,
@@ -43,479 +89,303 @@
   `files` table is refused with a clear schema-version error (2026-10-04,
   https://git.eeqj.de/sneak/sfdupes/issues/11)
 
-- README documents install, Docker, a daily cron scan and how to read
-  and check the reports (2026-10-04,
-  https://git.eeqj.de/sneak/sfdupes/issues/54)
+- README documents install, Docker, a daily cron scan and how to read and check
+  the reports (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/54)
 
-- the `Dockerfile` build stage keeps the Go module cache out of `builder`'s
-  home and copies the sources with `--chown`, so no `chown -R` walks them
+- the `Dockerfile` build stage keeps the Go module cache out of `builder`'s home
+  and copies the sources with `--chown`, so no `chown -R` walks them
   (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/43)
 
 - `--version` prints `sfdupes VERSION` to stdout; README documents it and
   `--help` (2026-10-04, https://git.eeqj.de/sneak/sfdupes/issues/15)
 
-- `scan` stops cleanly on `SIGINT` or `SIGTERM`: commits what it has
-  hashed, deletes nothing more, exits 1 (2026-10-04,
+- `scan` stops cleanly on `SIGINT` or `SIGTERM`: commits what it has hashed,
+  deletes nothing more, exits 1 (2026-10-04,
   https://git.eeqj.de/sneak/sfdupes/issues/5)
 
-- `report` and `trees` stream the records instead of holding them all in
-  memory; the schema gains the `files_signature` index (2026-10-04,
+- `report` and `trees` stream the records instead of holding them all in memory;
+  the schema gains the `files_signature` index (2026-10-04,
   https://git.eeqj.de/sneak/sfdupes/issues/14)
 
-- progress prints at once on a non-terminal, uses a real terminal test,
-  and prints warnings through a spinner instead of racing its redraw
-  (2026-10-03, https://git.eeqj.de/sneak/sfdupes/issues/13)
+- progress prints at once on a non-terminal, uses a real terminal test, and
+  prints warnings through a spinner instead of racing its redraw (2026-10-03,
+  https://git.eeqj.de/sneak/sfdupes/issues/13)
 
-- warn about and skip symlink, socket, FIFO, device and `.zfs`
-  operands, keeping the records beneath them (2026-10-03,
+- warn about and skip symlink, socket, FIFO, device and `.zfs` operands, keeping
+  the records beneath them (2026-10-03,
   https://git.eeqj.de/sneak/sfdupes/issues/9)
 
-- `scan` holds a lock on a lock file beside the database for its whole run,
-  so a second `scan` fails at once with exit 1 (2026-10-03,
+- `scan` holds a lock on a lock file beside the database for its whole run, so a
+  second `scan` fails at once with exit 1 (2026-10-03,
   https://git.eeqj.de/sneak/sfdupes/issues/53)
 
 - test stdout write failures in `report` and `trees`; README states that
   `| head` ends sfdupes by `SIGPIPE` and `>&-` writes to `/dev/null`
   (2026-10-03, https://git.eeqj.de/sneak/sfdupes/issues/30)
 
-- `report` and `trees` open the database read-only, and `scan` leaves it
-  out of WAL mode, so reading needs only read access (2026-10-03, closes
+- `report` and `trees` open the database read-only, and `scan` leaves it out of
+  WAL mode, so reading needs only read access (2026-10-03, closes
   https://git.eeqj.de/sneak/sfdupes/issues/8)
 
-- escape tabs, newlines, carriage returns and backslashes in report,
-  trees and warning paths; the root directory's path is `/`
-  (2026-10-03, https://git.eeqj.de/sneak/sfdupes/issues/7)
+- escape tabs, newlines, carriage returns and backslashes in report, trees and
+  warning paths; the root directory's path is `/` (2026-10-03,
+  https://git.eeqj.de/sneak/sfdupes/issues/7)
 
-- stamp the git tag or short commit in a plain `docker build .`
-  instead of `dev` (2026-10-02, branch `next`, closes
-  https://git.eeqj.de/sneak/sfdupes/issues/67): `.dockerignore` now
-  sends `.git`, without `.git/config`, and the `Dockerfile` build
-  stage takes the `VERSION` build argument when one is given,
-  otherwise `git describe --tags --always` of that `.git`. The build
-  fails if the context carries `.git` and the version still comes out
-  empty, `dev` or `unknown`. The CI checkout step fetches the full
-  history (`fetch-depth: 0`) so CI sees the tag and stamps the same
-  value as `make build`.
+- stamp the git tag or short commit in a plain `docker build .` instead of `dev`
+  (2026-10-02, branch `next`, closes
+  https://git.eeqj.de/sneak/sfdupes/issues/67): `.dockerignore` sends `.git`
+  without `.git/config`; the build stage stamps the `VERSION` build argument,
+  else `git describe --tags --always`, and fails if the context carries `.git`
+  and the version is still empty, `dev` or `unknown`. CI checks out the full
+  history (`fetch-depth: 0`) so it stamps the same value as `make build`.
 
-- replace the 1 KiB end-window sampling with the head/tail plus
-  content-hash ladder (2026-09-22, branch `next`, closes
-  https://git.eeqj.de/sneak/sfdupes/issues/61): a file under 10 MiB is
-  hashed in full and compared directly, with no end-window step — its
-  `head`, `tail`, and `content` all hold the whole-file hash. A file at
-  10 MiB or above gets only the 64 KiB `head` and `tail` in the hash
-  phase; a new content phase, after the update phase, reads it for its
-  `content` hash — the whole file below 50 MiB, gigabyte-spaced 1 MiB
-  samples at or above — only when its size, `head`, and `tail` match
-  another record's, from the same scan or stored by an earlier one, so
-  a stored file gains its content hash when it gains a match. A file
-  that is gone or has changed since its record was written is not
-  read. The `content` column is part of the version 1 schema. `report`
-  and `trees` group by the extended signature and leave out any record
-  without a `content` hash, so the ladder is applied across the whole
-  database. README "Duplicate detection" documents every rung including
-  the probabilistic large-file path.
+- replace the 1 KiB end-window sampling with the head/tail plus content-hash
+  ladder (2026-09-22, branch `next`, closes
+  https://git.eeqj.de/sneak/sfdupes/issues/61); README "Duplicate detection"
+  documents every rung. A file under 10 MiB is hashed in full, and its `head`,
+  `tail` and `content` all hold that hash. A larger file gets only its 64 KiB
+  `head` and `tail` in the hash phase; the content phase, after the update
+  phase, reads it for `content` (the whole file below 50 MiB, gigabyte-spaced 1
+  MiB samples at or above) only when its size, `head` and `tail` match another
+  record's from this scan or an earlier one, and never reads a file gone or
+  changed since its record was written. `report` and `trees` leave out any
+  record without a `content` hash. The `content` column is part of the version 1
+  schema.
 
-- remove the dead `files.dat` references from `Makefile`, `.gitignore`
-  and `.dockerignore` (2026-09-21, branch `next`, closes
+- remove the dead `files.dat` references from `Makefile`, `.gitignore` and
+  `.dockerignore` (2026-09-21, branch `next`, closes
   https://git.eeqj.de/sneak/sfdupes/issues/22)
 
 - fix the lint-image pin comments and `FROM` form in `Dockerfile` and
   `Dockerfile.lint` (2026-08-10, branch `next`, closes
-  https://git.eeqj.de/sneak/sfdupes/issues/25): dropped the false
-  `(Debian-based)` parenthetical (v2.12.1 was Debian too) and the
-  redundant tag, so both pins are the policy `# image:vX.Y.Z,
-  YYYY-MM-DD` comment over a bare `FROM image@sha256:...`. Digest
-  unchanged. `script/verify-lint-image-pin` parses those `FROM` lines
-  and still matches the tagless form; its advice line lost the now
-  meaningless "tag and digest". With no tag in either reference, a
-  tag-only disagreement no longer exists — a one-sided tag is caught as
-  a plain mismatch.
+  https://git.eeqj.de/sneak/sfdupes/issues/25): both pins are now the policy
+  `# image:vX.Y.Z, YYYY-MM-DD` comment over a bare `FROM image@sha256:...`,
+  without the false `(Debian-based)` note or the tag; digest unchanged.
+  `script/verify-lint-image-pin` still matches the tagless form, and a tag on
+  one side only is caught as a plain mismatch.
 
-- run all linting in Docker via `Dockerfile.lint` and `script/lint`
-  (2026-08-10, branch `next`, closes
-  https://git.eeqj.de/sneak/sfdupes/issues/46): per the owner ruling, the
-  linter runs inside a container invoked through the `script/`
-  entrypoint and is never installed on a host. New root
-  `Dockerfile.lint` COPYs the repo into the digest-pinned
-  `golangci/golangci-lint:v2.12.2` image and runs
-  `golangci-lint config verify` and `golangci-lint run` as build
-  steps, so a successful build IS a clean lint; `script/lint` is
-  reduced to building it. `script/bootstrap` loses the `go install`,
-  the pin constants, the version parser and `verify_golangci_lint`
-  outright rather than hardening them — with nothing linting on the
-  host, the `$GOPATH/bin` versus `PATH` problem that motivated them has
-  no subject — and now warns rather than fails when `docker` is absent.
-  Two traps handled. A lint build on an unchanged tree returns success
-  in well under a second having run no linter, which is
-  https://git.eeqj.de/sneak/sfdupes/issues/32 and
-  https://git.eeqj.de/sneak/sfdupes/issues/39 again, so
-  `Dockerfile.lint` carries `ARG CHECK_EPOCH` referenced
-  inside every gate `RUN` (BuildKit hashes the expanded command, not
-  the declaration) and `script/lint` passes `"$(date +%s)-$$"` — the
-  PID matters because two lint runs land inside the same second easily.
-  And nothing inside an image build may shell out to docker, so the
-  main `Dockerfile`'s lint stage now invokes `golangci-lint` directly
-  instead of `make lint`, and its build stage runs `make test` and
-  `make fmt-check` instead of the `make check` aggregate (`make`, not
-  the scripts bare, because the Makefile's `export CGO_ENABLED = 0`
-  only reaches what it invokes). `COPY --from=lint`
-  `/usr/bin/golangci-lint` is replaced by
-  `COPY --from=lint /src/go.sum /dev/null`: the copied binary was the
-  only edge forcing BuildKit to finish linting before the build stage
-  starts, and dropping it without replacing the edge would have ended
-  fail-fast linting silently under a still-green build. That is
-  canonical `REPO_POLICIES.md:107`'s ordering edge, restored.
-  `ENV PATH=/home/builder/go/bin:$PATH` is gone with the `go install`
-  that justified it. `script/verify-linter-pin` is retired, deleted
-  along with its README entry, because both of its subjects ceased to
-  exist in the same change: it compared a linter binary against
-  `GOLANGCI_LINT_VERSION` in `script/bootstrap`, and there is now
-  neither a binary crossing between stages nor a version pin in
-  bootstrap. The drift it guarded has not gone away, it has moved — the
-  linter is still pinned twice, now as the `FROM` line of
-  `Dockerfile.lint` and the `FROM` line of the `Dockerfile` lint stage,
-  with nothing syncing them, which is exactly what
-  https://git.eeqj.de/sneak/sfdupes/issues/42 made a build failure. Its
-  replacement is one new `script/verify-lint-image-pin`,
-  run as a gate in both files, which compares the two references to
-  each other and deliberately restates neither: a hardcoded expected
-  digest would be a third copy and the same drift one file further out.
-  `golangci-lint config verify` is included per the ruling, and the
-  concern about its unpinned live HTTPS schema fetch was measured
-  rather than assumed — under `--network none` the pinned binary both
-  passes a valid config and rejects an invalid one with the jsonschema
-  error, so it validates from an embedded schema and makes no network
-  call of its own. The README scopes that to the gate steps rather
-  than to linting as a whole: `Dockerfile.lint` runs `go mod download`
-  above them, so a cold cache still needs the network and only a warm
-  one lints offline. Verified: `make lint` green with every `PATH`
-  directory containing a `golangci-lint` removed
-  (`/home/user/go/bin`, `/home/user/.local/bin`, `/usr/local/bin`;
-  `command -v golangci-lint` empty); two consecutive `script/lint` runs
-  on an untouched tree both executed the linter, 27.7s and 28.7s in the
-  lint step under distinct epochs with the `COPY . .` layer `CACHED`
-  above them, at 42.2s and 41.8s wall clock — the no-cache rule was not
-  weakened to shorten that. Negative control: a planted
-  `var unusedIssue46Sentinel = 1` failed `script/lint` with
-  `report.go:173:5: var unusedIssue46Sentinel is unused (unused)`, and
-  failed `make docker` at `[lint 9/9]` with the build stage stopped at
-  `[builder 3/12]` — `COPY --from=lint`, `script/bootstrap`, the test
-  gate and `make build` all zero occurrences — then reverted clean. The
-  drift guard fails on a tag-only disagreement, on a digest-only
-  disagreement, and on an unreadable reference, naming both sides.
-  `make docker` green in 5m35s with all six gates executing under one
-  epoch (lint 37.6s, test 25.2s reporting
-  `ok sneak.berlin/go/sfdupes 1.938s coverage: 88.5%`, not `(cached)`).
-  The non-root quirk still holds: in the builder image with the Go test
-  cache off, `--user 0:0` fails `TestScanHardlinkRunFailsTogether`
-  (exit 1) where the unprivileged user passes (exit 0). Noted for
-  follow-up, not fixed here: `golangci-lint` warns that the
-  `gomodguard` linter is deprecated since v2.12.0 in favour of
-  `gomodguard_v2`.
+- run all linting in Docker via `Dockerfile.lint` and `script/lint` (2026-08-10,
+  branch `next`, closes https://git.eeqj.de/sneak/sfdupes/issues/46): per the
+  owner ruling the linter is never installed on a host. `Dockerfile.lint` copies
+  the repo into the digest-pinned `golangci/golangci-lint:v2.12.2` image and
+  runs `golangci-lint config verify` and `golangci-lint run` as build steps;
+  `script/lint` builds it. `script/bootstrap` no longer installs or pins the
+  linter, and warns rather than fails when `docker` is absent;
+  `ENV PATH=/home/builder/go/bin:$PATH` went with its `go install`.
+  `script/verify-linter-pin` is retired; `script/verify-lint-image-pin`, a gate
+  in both files, compares their two `FROM` lines and restates neither pin.
+  Traps: nothing inside an image build may shell out to docker, so the
+  `Dockerfile` lint stage calls `golangci-lint` directly and the build stage
+  runs `make test` and `make fmt-check` instead of `make check`, through `make`
+  because the Makefile's `export CGO_ENABLED = 0` only reaches what it invokes.
+  `COPY --from=lint /src/go.sum /dev/null` replaces the copied linter binary as
+  the only edge making the build stage wait for lint; dropping it would end
+  fail-fast linting under a still-green build. `golangci-lint config verify`,
+  included per the ruling, validates from an embedded schema with no network
+  call, but `go mod download` above the gates still needs the network on a cold
+  cache. Verified: `make lint` green with no `golangci-lint` on `PATH`; two
+  back-to-back `script/lint` runs on an untouched tree both ran the linter
+  (27.7s and 28.7s in the lint step, `COPY . .` `CACHED` above); a planted
+  unused variable failed `script/lint`, and failed `make docker` at `[lint 9/9]`
+  with the build stage stopped at `[builder 3/12]`; the drift guard fails on a
+  tag-only, a digest-only and an unreadable reference, naming both sides; under
+  `--network none` config verify passes a valid config and rejects an invalid
+  one; `make docker` green in 5m35s with all six gates run (lint 37.6s, test
+  25.2s reporting `ok sneak.berlin/go/sfdupes 1.938s coverage: 88.5%`, not
+  `(cached)`); in the builder image with the Go test cache off, `--user 0:0`
+  still fails `TestScanHardlinkRunFailsTogether` where the unprivileged user
+  passes. Noted for follow-up, not fixed here: `golangci-lint` warns that
+  `gomodguard` is deprecated since v2.12.0 in favour of `gomodguard_v2`.
 
-- install the Docker build stage's prerequisites by running
-  `script/bootstrap` instead of `apk add --no-cache make` inline
-  (2026-08-09, branch `dockerfile-bootstrap`, closes #42): canonical
-  `REPO_POLICIES.md:97` requires it, and the inline install left the
-  build stage maintaining its own notion of the toolchain — exactly
-  the divergence #24 exists to close, one layer down. The stage now
-  copies `script/` plus `go.mod`/`go.sum` and runs `script/bootstrap`,
-  which ends in `go mod download`, so the separate invocation of that
-  is gone. `COPY --from=lint /usr/bin/golangci-lint` stays, and moves
-  above the bootstrap layer. It is the only edge making this stage
-  depend on the lint stage, so deleting it as redundant would end
-  fail-fast linting silently. Letting bootstrap install its own linter
-  here would have reintroduced the second toolchain and paid for a
-  from-source build of it. What makes the two stages provably one
-  toolchain rather than two that happen to agree is a new
-  `script/verify-linter-pin`, run in the build stage on the binary
-  that arrives from the lint stage, before bootstrap: it fails the
-  build naming both versions unless that binary is the version
-  `script/bootstrap` pins. Bootstrap's own check could not serve that
-  purpose — it reinstalls its pin from source and then verifies
-  whatever `PATH` resolves, so drift self-heals silently and a lint
-  stage image bumped on its own would lint at the new version while
-  `make check` ran at the old one, green. The linter version is pinned
-  in two independent places (the lint stage image digest and
-  `GOLANGCI_LINT_VERSION`) and nothing else keeps them in sync, so a
-  half-applied bump is now a build failure. The pin is read out of
-  `script/bootstrap`, which stays the single source of truth; a pin
-  that cannot be read is a hard failure, not a skip. The check needs
-  no `CHECK_EPOCH`: its only inputs are the copied binary and
-  `script/`, so Docker invalidates the layer exactly when a cached
-  result would stop being true, and it is documented with the other
-  entrypoints in the README. `$GOPATH/bin` joins `PATH` because
-  that is where bootstrap's `go install` lands and bootstrap verifies
-  its installs against what `PATH` resolves — nothing in the image is
-  shadowed by it, the directory does not exist until bootstrap runs.
-  Everything added sits above `ARG CHECK_EPOCH`, and the `chown` and
-  `USER builder` still precede `make check`. Verified: the guard fails
-  the build with both versions named when the lint stage's linter is
-  faked to a different version, and an unmodified build still passes
-  it; bootstrap runs clean under Alpine's `sh` and its `apk` branch,
-  installing `git` and `make` and finding the copied
-  linter already at the pin; a second build served the bootstrap and
-  dependency layers `CACHED` while both gates ran with a fresh epoch;
-  a planted `unused` finding failed the build at the lint gate in
-  48.9s with the build stage's `make check` never starting; and the
-  suite run in the image as `--user 0:0` fails
-  `TestScanHardlinkRunFailsTogether`, so the drop to the unprivileged
-  user is still load-bearing. That last check needs the Go test cache
-  disabled — the first attempt reported `ok ... (cached)` as root,
-  reusing the result the build-time run had left in the shared cache,
-  which would have read as a pass. Build wall time, on a shared host
-  running many concurrent builds and so noisy: 2m13s on an unchanged
-  tree, 2m17s and 4m29s for two builds after a source change, 5m14s
-  cold. Only the cold one breaches the policy ceiling, and not because
-  of this change — `chown -R builder:builder /src /home/builder` walks
-  the module cache and re-runs on every source change, and it alone
-  varied between 77s and 210s across those four builds, which is also
-  the whole spread in the totals. The same cold measurement against
-  `main` is 5m03s with a 209s `chown`. Filed as #43
-- bust the Docker layer cache for the gate steps, so `script/cibuild`
-  and `script/docker` cannot report a green they did not earn
-  (2026-08-09, branch `cibuild-cache-bust`, closes #32): both scripts
-  were bare `docker build` invocations with no cache control, and the
-  `Dockerfile` copies the tree before running its gates, so on an
-  unchanged tree Docker served those layers from cache and the build
-  exited 0 having executed nothing. That is not hypothetical here —
-  every merge this repo has done is a non-fast-forward merge of an
-  undiverged branch, so each merge commit's tree is byte-identical to
-  the branch head's and each merge CI run was almost certainly a full
-  cache hit; and PR #31's reviewer found `make docker` returning
-  success as a 17-layer cache hit, catching it only by being
-  suspicious. The fix is `ARG CHECK_EPOCH` with the scripts passing
-  `--build-arg CHECK_EPOCH="$(date +%s)"`. Two details make or break
-  it. `ARG` is scoped per stage and this `Dockerfile` has three gates
-  across two — `make fmt-check` and `make lint` in the lint stage,
-  `make check` in the build stage — so a single declaration would have
-  left one stage silently cacheable; it is declared in both. And
-  BuildKit hashes the expanded command, not the declaration, so a
-  declared-but-unreferenced `ARG` invalidates nothing: each gate `RUN`
-  echoes the epoch, which also puts the value in the build log as
-  evidence the layer really ran. Placement is below the dependency
-  layers on purpose — a build that goes cold every time would be a
-  different bug, not a fix. Verified by running each script twice back
-  to back on an unchanged tree under `BUILDKIT_PROGRESS=plain`: all
-  three gates executed on all four runs, each with a fresh epoch in
-  the log (`script/cibuild` 78.8s then 61.1s; `script/docker` 61.1s
-  then 53.4s), and twelve steps were still served `CACHED` in the
-  steady state — both `go mod download`s, `apk add`, `adduser`, the
-  `chown`, every `go.mod`/`go.sum` and source copy, the linter copy
-  out of the lint stage, and the binary copy into the runtime stage.
-  The lint stage still gates the build stage: with a deliberate
-  `unused` finding planted in the tree, the build failed at
-  `make lint` in 36.1s and the build-stage `make check` never started.
-  The build stage also still drops to the unprivileged `builder` user
-  before `make check`, which the suite depends on rather than merely
-  prefers: forcing the same image to run the tests as root fails
-  `TestScanHardlinkRunFailsTogether`, because root reads straight
-  through the `chmod(0)` the test uses to prove hard links are read
-  once. This is the local fix only; propagating it to the canonical
-  templates is `prompts` #26
-- check the installed golangci-lint version in `script/bootstrap`
-  instead of only its presence (2026-08-09, branch
-  `bootstrap-version-check`, closes #24): `missing golangci-lint` meant
-  any linter already on `PATH` satisfied the check, so the pin was never
-  consulted and the v2.12.2 bump from #3 was inert on every host that
-  already had one — this host ran v2.10.1 against a v2.12.2 pin,
-  `make check` went green, and `make docker` then rejected the same
-  commit with findings the local gate never saw. The version now lives
-  in one place, `GOLANGCI_LINT_VERSION`, with the `go install` module
-  ref derived from it so a bump cannot half-apply; a
-  `golangci_lint_version` helper parses `golangci-lint --version`
-  (taking the field after the word `version` and tolerating an optional
-  leading `v`, which the module ref carries and the binary's output does
-  not), and any version that is not the pin — older, newer, absent or
-  unparseable — is reinstalled. The install is then verified against the
-  binary `PATH` actually resolves: `go install` writes into `GOBIN` (or
-  `GOPATH/bin`) while `make lint` runs whichever `golangci-lint` comes
-  first on `PATH`, so a wrong-version one sitting ahead of it — nix,
-  apt, brew, apk, or the `/usr/local/bin` copy the `Dockerfile` builder
-  stage makes — would swallow the install and leave the local gate
-  disagreeing with CI under an affirmative `bootstrap complete`.
-  Bootstrap now re-reads the effective version after installing and, on
-  a mismatch, prints both paths and both versions to stderr and exits
-  non-zero instead of claiming success; it does not reorder anyone's
-  `PATH` or delete their binary. The `--version` call keeps its stderr
-  connected, so a present-but-broken binary says why rather than
-  reinstalling forever in silence, and is bounded by `timeout(1)` where
-  that exists, so a wedged binary cannot hang bootstrap. `git`, `make`
-  and `go` keep their presence-only checks and now say why in a
-  comment: they are host package-manager tools the repo deliberately
-  does not pin, with `go.mod` governing the language version and the
-  digest-pinned images covering reproducible builds. Verified on this
-  host by bootstrapping from v2.10.1 to v2.12.2 and running it again to
-  a no-op, plus stub runs of the real script under `dash` covering a
-  thirteen-input parse matrix (absent, older, newer, host-style,
-  image-style, leading-`v`, stderr-only, empty, non-zero exit, impostor
-  binary, `(devel)`, trailing `version`), a shadowed install that must
-  exit non-zero, an install destination not on `PATH` at all, `GOBIN`
-  set, and a wedged binary that must hit the timeout; `make check` and
-  `make lint` are clean at v2.12.2, so v2.10.1 was not hiding any
-  findings on `main`
+- install the Docker build stage's prerequisites by running `script/bootstrap`
+  instead of `apk add --no-cache make` inline (2026-08-09, branch
+  `dockerfile-bootstrap`, closes https://git.eeqj.de/sneak/sfdupes/issues/42):
+  the stage copies `script/` plus `go.mod`/`go.sum` and runs `script/bootstrap`,
+  which ends in `go mod download`, so the separate call to it is gone.
+  `COPY --from=lint /usr/bin/golangci-lint` stays and moves above the bootstrap
+  layer: it is the only edge making this stage depend on the lint stage, so
+  deleting it would end fail-fast linting silently. A new
+  `script/verify-linter-pin`, run in the build stage before bootstrap, fails the
+  build naming both versions unless that copied binary is the version
+  `script/bootstrap` pins; a pin it cannot read is a hard failure, not a skip.
+  `$GOPATH/bin` joins `PATH`, where bootstrap's `go install` lands. The `chown`
+  and `USER builder` still precede `make check`. Verified: the guard fails the
+  build with both versions named when the lint stage's linter is faked to
+  another version, and passes an unmodified build; bootstrap runs clean under
+  Alpine's `sh` and `apk`, finding the copied linter already at the pin; a
+  second build served the bootstrap and dependency layers `CACHED` while both
+  gates ran; a planted `unused` finding failed the build at the lint gate in
+  48.9s with the build stage's `make check` never starting; and the suite run in
+  the image as `--user 0:0` fails `TestScanHardlinkRunFailsTogether`, so the
+  drop to the unprivileged user is still needed. That last check needs the Go
+  test cache off: as root it first reported `ok ... (cached)`, reusing the
+  build-time result. Build times on a noisy shared host: 2m13s on an unchanged
+  tree, 2m17s and 4m29s after a source change, 5m14s cold, which breaches the
+  policy ceiling; `chown -R builder:builder /src /home/builder` walks the module
+  cache and alone varied from 77s to 210s across those builds, and `main`
+  measured 5m03s cold with a 209s `chown`. Filed as
+  https://git.eeqj.de/sneak/sfdupes/issues/43
+- bust the Docker layer cache for the gate steps, so `script/cibuild` and
+  `script/docker` cannot report a green they did not earn (2026-08-09, branch
+  `cibuild-cache-bust`, closes https://git.eeqj.de/sneak/sfdupes/issues/32): the
+  `Dockerfile` copies the tree before its gates, so on an unchanged tree Docker
+  served them from cache and the build exited 0 having run nothing. Every
+  `docker build` in `script/` now passes `--no-cache` instead
+  (https://git.eeqj.de/sneak/sfdupes/issues/95). Run as root, the tests fail
+  `TestScanHardlinkRunFailsTogether`, because root reads through the `chmod(0)`
+  the test relies on, so they run as an unprivileged user
+- check the installed golangci-lint version in `script/bootstrap` instead of
+  only its presence (2026-08-09, branch `bootstrap-version-check`, closes
+  https://git.eeqj.de/sneak/sfdupes/issues/24): the version lives only in
+  `GOLANGCI_LINT_VERSION`, with the `go install` module ref derived from it, and
+  any installed version that is not the pin — older, newer, absent or
+  unparseable — is reinstalled. `go install` writes into `GOBIN` (or
+  `GOPATH/bin`) while `make lint` runs the first `golangci-lint` on `PATH`, so
+  bootstrap re-reads the effective version after installing and, on a mismatch,
+  prints both paths and both versions and exits non-zero; it does not reorder
+  `PATH` or delete anyone's binary. The `--version` call keeps its stderr and is
+  bounded by `timeout(1)` where that exists. `git`, `make` and `go` keep
+  presence-only checks. Verified by bootstrapping this host from v2.10.1 to
+  v2.12.2 and again to a no-op, and by stub runs of the script under `dash`
+  covering a thirteen-input version-parse matrix, a shadowed install that must
+  exit non-zero, an install destination not on `PATH`, `GOBIN` set, and a wedged
+  binary that must hit the timeout; `make check` and `make lint` are clean at
+  v2.12.2, so v2.10.1 was not hiding any findings on `main`
 - unwind the hash worker pool on the error path (2026-08-09, branch
-  `hash-pool-cleanup`, closes #6): `hashPhase` used to return the
-  moment `recordRun` failed and abandon the pool — the feeder parked
-  forever on a full `jobs` channel and every worker on a full
-  `results` channel. That only stopped being invisible when #4 landed
-  and `runScan` began unwinding instead of calling `os.Exit`. The
-  pool is now an owned, context-aware `hashPool`: every blocking send
-  in the feeder and the workers selects on `ctx.Done()`, `jobs` is
-  closed on every path out, and `hashPhase` defers `pool.stop()`,
-  which cancels and then drains `results` until the last goroutine
-  has exited — draining is what frees a worker already parked on a
-  send. `ctx` is threaded from `cmd.Context()` through `runScan`,
-  `syncScan`, both worker pools and the whole database layer (it is
-  the first parameter everywhere), so #5 can hand this path a signal
-  and needs to add nothing else. The walk pool never leaked, because
-  `walkPhase` always drains its events to close, but it has the same
-  unbounded-send shape and #5 will give it an early return, so it
-  gets the same treatment plus a `ctx.Err()` guard after the walk: a
-  cancelled walk yields a partial size census, and every file it never
-  reached looks vanished to the update phase. That phase's own
-  `BeginTx` fails on the same cancelled context before deleting
-  anything, so the guard is defence in depth rather than the only
-  barrier — but it is the one that survives #5 deciding an interrupted
-  scan may commit what it has. Tests drive `run(scan)` against a
-  database whose insert trigger aborts, and assert both that the scan
-  fails instead of hanging and that `runtime.NumGoroutine()` polls
-  back to its pre-scan baseline; a second set cancels a scan part-way
-  through the walk — deterministically, by counting the scan's own
-  consultations of `ctx.Done()` rather than racing a timer — and
-  asserts that it stops at the guard holding a partial census and a
-  still-populated record index, with every record intact. The
-  remaining cancellation branches of both pools are covered by direct
-  tests of `sendEvent`, the walk workers, `dispatchDirs`,
-  `feedHashJobs`, `hashWorker` and `hashPhase`
-- guarantee the database is closed on every fatal exit path
-  (2026-08-09, branch `db-close-on-fatal`, closes #4): `fatalf` and
-  its `os.Exit(1)` are gone, so the deferred `db.Close()` — and with
-  it the SQLite WAL checkpoint — now actually runs when a subcommand
-  fails; `runScan`, `runReport`, `runTrees`, `loadRecords` and
-  `resolveRoots` return errors instead. The single exit point is `run`
-  in `main.go`: it maps a `fatalError` (anything a subcommand
-  returned) to exit 1 and cobra's own argument and flag errors to exit
-  2, which keeps a runtime failure from being reported as a usage
-  error or printing the usage text. New `main_test.go` drives the CLI
-  in-process and asserts the exit codes from README §Error handling
-  plus the stdout/stderr split, including that a fatal error raised
-  after the database is open leaves no `-wal`/`-shm` sidecar behind
-  for `scan`, `report` or `trees`
-- update golangci-lint to v2.12.2 with the canonical config
-  (2026-08-09, branch `golangci-v2.12.2`, merged as `38a01bd`,
-  closes #3): bumped the pinned linter in the `Dockerfile` lint
-  stage and `script/bootstrap` from v2.12.1 to v2.12.2, and replaced
-  `.golangci.yml` with the canonical file — the linter settings
-  (`lll`, `funlen`, `cyclop`, `dupl` thresholds) now live under
-  `linters.settings` per the v2 schema, so they are actually
-  applied; no new lint findings surfaced
-- convert Makefile targets to scripts-to-rule-them-all `script/`
-  entrypoints like the other managed repos (2026-07-26, commit
-  `3abeacf`, closes #1): all 12 `script/` entrypoints exist
-  (`bootstrap`, `setup`, `projectname`, `test`, `lint`, `fmt`,
-  `fmt-check`, `check`, `docker`, `cibuild`, `precommit`,
-  `install-precommit`) and every Makefile target is now a thin shim
-  over them, matching the other managed repos
+  `hash-pool-cleanup`, closes https://git.eeqj.de/sneak/sfdupes/issues/6): the
+  pool is now an owned, context-aware `hashPool`: every blocking send in the
+  feeder and the workers selects on `ctx.Done()`, `jobs` is closed on every path
+  out, and `hashPhase` defers `pool.stop()`, which cancels and then drains
+  `results` until the last goroutine has exited — draining is what frees a
+  worker already parked on a send. `ctx` is threaded from `cmd.Context()`
+  through `runScan`, `syncScan`, both worker pools and the whole database layer,
+  as the first parameter everywhere. The walk pool gets the same treatment plus
+  a `ctx.Err()` guard after the walk: a cancelled walk yields a partial size
+  census, and every file it never reached looks vanished to the update phase.
+  That phase's own `BeginTx` also fails on the cancelled context before deleting
+  anything, but the guard is the barrier that still holds once an interrupted
+  scan may commit what it has. Tests drive `run(scan)` against a database whose
+  insert trigger aborts and assert that the scan fails instead of hanging and
+  that `runtime.NumGoroutine()` polls back to its pre-scan baseline; others
+  cancel a scan part-way through the walk, deterministically, by counting its
+  own consultations of `ctx.Done()`, and assert that it stops at the guard
+  holding a partial census and a still-populated record index, with every record
+  intact. Direct tests of `sendEvent`, the walk workers, `dispatchDirs`,
+  `feedHashJobs`, `hashWorker` and `hashPhase` cover the remaining cancellation
+  branches of both pools
+- guarantee the database is closed on every fatal exit path (2026-08-09, branch
+  `db-close-on-fatal`, closes https://git.eeqj.de/sneak/sfdupes/issues/4):
+  `fatalf` and its `os.Exit(1)` are gone, so the deferred `db.Close()` — and
+  with it the SQLite WAL checkpoint — now actually runs when a subcommand fails;
+  `runScan`, `runReport`, `runTrees`, `loadRecords` and `resolveRoots` return
+  errors instead. The single exit point is `run` in `main.go`: it maps a
+  `fatalError` (anything a subcommand returned) to exit 1 and cobra's own
+  argument and flag errors to exit 2, which keeps a runtime failure from being
+  reported as a usage error or printing the usage text. New `main_test.go`
+  drives the CLI in-process and asserts the exit codes from README §Error
+  handling plus the stdout/stderr split, including that a fatal error raised
+  after the database is open leaves no `-wal`/`-shm` sidecar behind for `scan`,
+  `report` or `trees`
+- update golangci-lint to v2.12.2 with the canonical config (2026-08-09, branch
+  `golangci-v2.12.2`, merged as `38a01bd`, closes
+  https://git.eeqj.de/sneak/sfdupes/issues/3): bumped the pinned linter in the
+  `Dockerfile` lint stage and `script/bootstrap` from v2.12.1 to v2.12.2, and
+  replaced `.golangci.yml` with the canonical file — the linter settings (`lll`,
+  `funlen`, `cyclop`, `dupl` thresholds) now live under `linters.settings` per
+  the v2 schema, so they are actually applied; no new lint findings surfaced
+- convert Makefile targets to scripts-to-rule-them-all `script/` entrypoints
+  like the other managed repos (2026-07-26, commit `3abeacf`, closes
+  https://git.eeqj.de/sneak/sfdupes/issues/1): all 12 `script/` entrypoints
+  exist (`bootstrap`, `setup`, `projectname`, `test`, `lint`, `fmt`,
+  `fmt-check`, `check`, `docker`, `cibuild`, `precommit`, `install-precommit`)
+  and every Makefile target is now a thin shim over them
 - make the binary the default Make target (2026-07-24, branch
-  `make-default-target`): plain `make` now builds `sfdupes`
-  (previously it ran `check` plus `build`); `make build` remains as
-  an alias
-- scan-wide phases, concurrent operands, batched updates (2026-07-24,
-  branch `scan-wide-phases`): all operands seed the shared walk pool
-  and every pass runs once over the whole scan, so totals and ETAs
-  are scan-global; the per-operand walk/hash/update cycles and their
-  stderr announcements are gone; the update pass commits in batched
-  transactions — the filesystem is authoritative and the database an
-  eventually-consistent reflection, so scan-level atomicity is not
-  required
+  `make-default-target`): plain `make` now builds `sfdupes` (previously it ran
+  `check` plus `build`); `make build` remains as an alias
+- scan-wide phases, concurrent operands, batched updates (2026-07-24, branch
+  `scan-wide-phases`): all operands seed the shared walk pool and every pass
+  runs once over the whole scan, so totals and ETAs are scan-global; the
+  per-operand walk/hash/update cycles and their stderr announcements are gone;
+  the update pass commits in batched transactions — the filesystem is
+  authoritative and the database an eventually-consistent reflection, so
+  scan-level atomicity is not required
 - split the stat pass back out of the walk (2026-07-24, branch
-  `parallel-phases`): phases are strictly sequential again — walk,
-  stat, hash, update per operand — with parallelism only inside each
-  phase; the walk enumerates paths with per-directory workers and the
-  stat pass lstats them with per-file workers, restoring the exact
-  total/ETA stat bar
-- announce each operand on stderr before its passes (2026-07-24,
-  branch `scan-operand-progress`): with per-operand walk/hash/update
-  cycles, a multi-operand run (e.g. `scan /srv/*`) showed pass totals
-  that looked like the whole run's — an operator watching operand 3 of
-  14 hash 300k files concluded 20M files were being skipped
-- parallel walk (2026-07-24, branch `parallel-walk`): the walk pass
-  was a single goroutine and took hours at ~20M files on a busy pool
-  (observed: 22M files in 4h on a ZFS server); it is now a
-  per-directory worker-pool traversal that records size/mtime during
-  the walk (folding away the separate stat pass, halving metadata
-  I/O), and each `PATH` operand commits in its own transaction so an
-  interrupted scan keeps completed operands
+  `parallel-phases`): phases are strictly sequential again — walk, stat, hash,
+  update per operand — with parallelism only inside each phase; the walk
+  enumerates paths with per-directory workers and the stat pass lstats them with
+  per-file workers, restoring the exact total/ETA stat bar
+- announce each operand on stderr before its passes (2026-07-24, branch
+  `scan-operand-progress`): with per-operand walk/hash/update cycles, a
+  multi-operand run (e.g. `scan /srv/*`) showed pass totals that looked like the
+  whole run's
+- parallel walk (2026-07-24, branch `parallel-walk`): the walk pass was a single
+  goroutine and took hours at ~20M files on a busy pool (observed: 22M files in
+  4h on a ZFS server); it is now a per-directory worker-pool traversal that
+  records size/mtime during the walk (folding away the separate stat pass,
+  halving metadata I/O), and each `PATH` operand commits in its own transaction
+  so an interrupted scan keeps completed operands
 
-- persistent scan database (2026-07-24, branch `persistent-database`):
-  `scan` now maintains a SQLite database (`modernc.org/sqlite`, pure
-  Go, cgo stays disabled) keyed by absolute path that survives between
-  runs — a rescan hashes only new or changed files (by mtime/size),
-  deletes records for files vanished from under the scanned operands,
-  and leaves records outside them untouched, so `scan` can be cronned
-  daily; `report` and `trees` read the database (no positional
-  arguments) instead of a scan stream. Database at
-  `/var/lib/sfdupes/db.sqlite`, overridable via `SFDUPES_DATABASE`;
-  WAL journaling plus a single-transaction update keep a report run
-  during a scan safe
-- add the `origin` remote (`git@git.eeqj.de:sneak/sfdupes.git`), tag
-  `v0.0.1`, and push `main` plus tags (2026-07-23)
+- persistent scan database (2026-07-24, branch `persistent-database`): `scan`
+  now maintains a SQLite database (`modernc.org/sqlite`, pure Go, cgo stays
+  disabled) keyed by absolute path that survives between runs — a rescan hashes
+  only new or changed files (by mtime/size), deletes records for files vanished
+  from under the scanned operands, and leaves records outside them untouched, so
+  `scan` can be cronned daily; `report` and `trees` read the database (no
+  positional arguments) instead of a scan stream. Database at
+  `/var/lib/sfdupes/db.sqlite`, overridable via `SFDUPES_DATABASE`; WAL
+  journaling plus a single-transaction update keep a report run during a scan
+  safe
+- add the `origin` remote (`git@git.eeqj.de:sneak/sfdupes.git`), tag `v0.0.1`,
+  and push `main` plus tags (2026-07-23)
 - `scan` CLI rework (2026-07-23, branch `scan-required-paths`): required
-  `PATH...` operands via cobra flags replacing the `/srv` `-root`
-  default; new `-x`/`--one-file-system` flag (GNU convention) to stop
-  at filesystem boundaries, which are crossed by default
+  `PATH...` operands via cobra flags replacing the `/srv` `-root` default; new
+  `-x`/`--one-file-system` flag (GNU convention) to stop at filesystem
+  boundaries, which are crossed by default
 - bring the repo into full policy compliance (2026-07-23, branch
   `repo-policy-compliance`; checklist below)
-- `git init` with README-only first commit; code baseline committed on
-  `main` (2026-07-22)
+- `git init` with README-only first commit; code baseline committed on `main`
+  (2026-07-22)
 - implement `scan`, `report`, and `trees` subcommands (pre-git history)
 
 # Future Steps
 
-- possible later features (explicitly out of scope per README):
-  full-content verification of candidates, removal-script helpers
+- possible later features (explicitly out of scope per README): full-content
+  verification of candidates, removal-script helpers
 
 # Repo Policy Compliance
 
-Audited 2026-07-22 against `REPO_POLICIES.md` (2026-07-06), the existing
-repo checklist, and the Go styleguide. Code is already gofmt-clean, so no
-standalone formatting commit is needed.
+Audited 2026-07-22 against `REPO_POLICIES.md` (2026-07-06), the existing repo
+checklist, and the Go styleguide. Code is already gofmt-clean, so no standalone
+formatting commit is needed.
 
-- [x] `.gitignore` missing — the compiled `sfdupes` binary and
-      `files.dat` sit untracked in the tree; needs OS/editor/Go
-      artifacts plus secrets patterns
+- [x] `.gitignore` missing — the compiled `sfdupes` binary and `files.dat` sit
+      untracked in the tree; needs OS/editor/Go artifacts plus secrets patterns
 - [x] `.editorconfig` missing
-- [x] `LICENSE` missing and README has no License section (MIT assumed
-      from house convention — user to confirm)
+- [x] `LICENSE` missing and README has no License section (MIT assumed from
+      house convention — user to confirm)
 - [x] `REPO_POLICIES.md` missing from repo root
-- [x] `.golangci.yml` missing (install canonical copy); code must then
-      pass `make lint` (150 findings fixed; `make lint` is clean)
-- [x] `Makefile` lacks required targets `test`, `lint`, `fmt`,
-      `fmt-check`, `docker`, `hooks`; `check` currently depends on
-      `build`, which writes the binary (`make check` must not modify
-      files)
-- [x] no tests — `go test ./...` has nothing to run; policy requires
-      real tests with a 30-second timeout and the conditional `-v`
-      rerun pattern (suite covers parsing, grouping, digests,
-      suppression, hashing, and the scan pipeline; 64% coverage)
-- [x] `Dockerfile` missing — Go multistage with hash-pinned images:
-      fail-fast lint stage, build stage running `make check`
+- [x] `.golangci.yml` missing (install canonical copy); code must then pass
+      `make lint` (150 findings fixed; `make lint` is clean)
+- [x] `Makefile` lacks required targets `test`, `lint`, `fmt`, `fmt-check`,
+      `docker`, `hooks`; `check` currently depends on `build`, which writes the
+      binary (`make check` must not modify files)
+- [x] no tests — `go test ./...` has nothing to run; policy requires real tests
+      with a 30-second timeout and the conditional `-v` rerun pattern (suite
+      covers parsing, grouping, digests, suppression, hashing, and the scan
+      pipeline; 64% coverage)
+- [x] `Dockerfile` missing — Go multistage with hash-pinned images: fail-fast
+      lint stage, build stage running `make check`
 - [x] `.dockerignore` missing
-- [x] `.gitea/workflows/check.yml` missing (`docker build .` on push,
-      checkout action pinned by commit SHA)
+- [x] `.gitea/workflows/check.yml` missing (`docker build .` on push, checkout
+      action pinned by commit SHA)
 - [x] README lacks required sections: Description first line
-      (name/purpose/category/license/author), Getting Started,
-      Rationale, TODO, License, Author
-- [x] README non-goal "no git repository setup and no CI" is stale now
-      that the repo is under git with CI
-- [x] pre-commit hook not installed (`make hooks` once the target
-      exists)
+      (name/purpose/category/license/author), Getting Started, Rationale, TODO,
+      License, Author
+- [x] README non-goal "no git repository setup and no CI" is stale now that the
+      repo is under git with CI
+- [x] pre-commit hook not installed (`make hooks` once the target exists)
 
 Accepted divergences (no action):
 
-- flat single-package layout with `.go` files in the repo root — fine
-  for a small single-binary tool per the Go styleguide; the tracker
-  audit agrees
-- `go test` runs without `-race` — the repo mandates `CGO_ENABLED=0`
-  (pure-Go builds) and the race detector requires cgo
+- flat single-package layout with `.go` files in the repo root — fine for a
+  small single-binary tool per the Go styleguide; the tracker audit agrees

cancel_test.go

@@ -344,13 +344,14 @@ func storedPaths(t *testing.T, path string) []string {
 
 // TestRunScanInterrupted calls the scan entrypoint with a context that
 // is already cancelled, as when a signal arrives at once. It must return
-// errInterrupted promptly with its one line on stderr, leave the
-// database valid and as it was, and leave nothing in the way of the
-// next scan, which must bring the database up to date.
+// errInterrupted promptly with its one line on stderr and nothing on
+// stdout, leave the database valid and as it was, and leave nothing in
+// the way of the next scan, which must bring the database up to date.
 func TestRunScanInterrupted(t *testing.T) {
 	path := testDBPath(t)
 	t.Setenv(databaseEnv, path)
 
+	stdout := captureStdout(t)
 	stderr := captureStderr(t)
 	dir := buildSmokeTree(t)
 
@@ -393,6 +394,10 @@ func TestRunScanInterrupted(t *testing.T) {
 		t.Errorf("stderr = %q, want %q", got, want)
 	}
 
+	if got := stdout(); got != "" {
+		t.Errorf("stdout = %q, want nothing (data only)", got)
+	}
+
 	assertNoSidecars(t, path)
 
 	if got := storedPaths(t, path); !slices.Equal(got, before) {
@@ -415,12 +420,13 @@ func TestRunScanInterrupted(t *testing.T) {
 // TestRunScanInterruptedMidHash interrupts the scan entrypoint part-way
 // through its hash phase, after the database is open. It must return
 // errInterrupted, release the lock, end stderr with its line counting
-// every file the walk reached, close the database out of WAL mode, and
-// keep the records it hashed.
+// every file the walk reached, write nothing to stdout, close the
+// database out of WAL mode, and keep the records it hashed.
 func TestRunScanInterruptedMidHash(t *testing.T) {
 	path := testDBPath(t)
 	t.Setenv(databaseEnv, path)
 
+	stdout := captureStdout(t)
 	stderr := captureStderr(t)
 	dir := buildWalkCancelTree(t)
 
@@ -438,6 +444,10 @@ func TestRunScanInterruptedMidHash(t *testing.T) {
 		t.Errorf("stderr = %q, want it to end with %q", got, want)
 	}
 
+	if got := stdout(); got != "" {
+		t.Errorf("stdout = %q, want nothing (data only)", got)
+	}
+
 	assertNoSidecars(t, path)
 
 	db, err := openReportDatabase(t.Context(), path)
@@ -586,20 +596,49 @@ func TestSendEventAbandonsBlockedSend(t *testing.T) {
 	awaitReturn(t, done, "sendEvent")
 }
 
-// TestWalkWorkersDropQueuedDirs checks that cancelled walk workers keep
-// reading jobs and drop the directories rather than stopping their
-// read: the range over jobs has to run out for the pool to tear down
-// and close its event stream.
-func TestWalkWorkersDropQueuedDirs(t *testing.T) {
+// TestWalkOneDirStopsWhenCancelled checks that a cancelled scan stops
+// reading a directory instead of going through the rest of its
+// entries. A walk that kept going would return the subdirectory below
+// to descend into. Unlike a file event, that return is not a send the
+// cancellation can abandon, so the test catches the regression every
+// time.
+func TestWalkOneDirStopsWhenCancelled(t *testing.T) {
 	t.Parallel()
 
 	dir := t.TempDir()
-	writeEmptyFiles(t, dir, walkCancelFilesPerDir)
+
+	err := os.Mkdir(filepath.Join(dir, "sub"), 0o750)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Unbuffered and unread: on a cancelled scan every send gives up.
+	events := make(chan walkEvent)
+
+	subs := walkOneDir(cancelledContext(t), dirJob{path: dir}, false, events)
+	if len(subs) != 0 {
+		t.Errorf("cancelled walkOneDir returned %+v to descend into, "+
+			"want none", subs)
+	}
+}
+
+// TestWalkWorkersDropQueuedDirs checks that cancelled walk workers keep
+// reading jobs and drop the directories rather than stopping their
+// read: the range over jobs has to run out for the pool to tear down
+// and close its event stream. The queued directory does not exist, so
+// a worker that walked it anyway would send a warning before
+// walkOneDir's own cancellation check could stop it. On a cancelled
+// scan that send delivers or gives up at random, so with 64 jobs
+// queued the regression has a one in 2^64 chance of passing.
+func TestWalkWorkersDropQueuedDirs(t *testing.T) {
+	t.Parallel()
+
+	missing := filepath.Join(t.TempDir(), "missing")
 
 	jobs, _, events := startWalkWorkers(cancelledContext(t), 2, false)
 
-	for range 4 {
-		jobs <- dirJob{path: dir}
+	for range 64 {
+		jobs <- dirJob{path: missing}
 	}
 
 	close(jobs)
@@ -700,47 +739,77 @@ func TestFeedHashJobsClosesJobsWhenCancelled(t *testing.T) {
 // TestHashWorkerDropsQueuedRuns checks that a cancelled hash worker
 // keeps reading jobs and drops the runs rather than reading files
 // nobody wants the hashes of — while still letting the range run out
-// so the pool tears down. The queued run names a file that does not
-// exist, so a worker that hashed it anyway would produce a result.
-//
-// hashWorker's other cancellation exit, abandoning the send of a
-// result, is reachable from the scan: stop cancels the pool before it
-// drains results, so a worker waiting on that send can leave through
-// it. The tests that stop a scan mid-hash, among them
-// TestScanHashWriteFailureUnwindsPool, reach it in some runs only,
-// depending on timing, and no test fails without it, since stop's
-// drain frees a waiting worker anyway. This test, for its part, catches
-// a removed drop check in some runs only: a worker that hashes the run
-// anyway then picks at random between sending the result and leaving.
+// so the pool tears down. The hash function records that it was
+// called, so a worker that hashed the queued run anyway is caught
+// every time.
 func TestHashWorkerDropsQueuedRuns(t *testing.T) {
 	t.Parallel()
 
 	done := make(chan struct{})
 	jobs := make(chan []fileRec, 1)
-	results := make(chan hashResult, 1)
+	results := make(chan hashResult)
 
-	run := []fileRec{{path: filepath.Join(t.TempDir(), "missing"), size: 1}}
-
-	jobs <- run
+	jobs <- []fileRec{{path: filepath.Join(t.TempDir(), "missing"), size: 1}}
 
 	close(jobs)
 
+	var hashed atomic.Bool
+
+	hash := func(path string, size int64) (string, string, string, error) {
+		hashed.Store(true)
+
+		return hashSignature(path, size)
+	}
+
 	go func() {
 		defer close(done)
 
-		hashWorker(cancelledContext(t), jobs, results, hashSignature)
+		hashWorker(cancelledContext(t), jobs, results, hash)
 	}()
 
 	awaitReturn(t, done, "hashWorker")
 
-	select {
-	case r := <-results:
-		t.Errorf("cancelled hash worker produced %+v, want the run dropped",
-			r)
-	default:
+	if hashed.Load() {
+		t.Error("cancelled hash worker hashed the queued run, want it dropped")
 	}
 }
 
+// TestHashWorkerAbandonsBlockedSend checks that a hash worker with a
+// result to deliver and nobody to deliver it to leaves once the scan
+// is cancelled, instead of holding the pool open. The scan tests do
+// not catch this: stop drains results, which frees a parked worker
+// anyway.
+func TestHashWorkerAbandonsBlockedSend(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+
+	done := make(chan struct{})
+	jobs := make(chan []fileRec, 1)
+	// Unbuffered and unread, with jobs left open: the worker's only way
+	// out is the cancellation case beside its send.
+	results := make(chan hashResult)
+
+	jobs <- []fileRec{{path: filepath.Join(t.TempDir(), "missing"), size: 1}}
+
+	// The scan is cancelled while the worker hashes, so the worker has
+	// already passed the check that drops queued runs.
+	hash := func(path string, size int64) (string, string, string, error) {
+		cancel()
+
+		return hashSignature(path, size)
+	}
+
+	go func() {
+		defer close(done)
+
+		hashWorker(ctx, jobs, results, hash)
+	}()
+
+	awaitReturn(t, done, "hashWorker")
+}
+
 // TestHashPhaseCancelledReturnsContextError checks the result loop's
 // own exit: with the pool cancelled, no result will ever arrive, and
 // the loop must leave through the cancellation rather than wait for a

db.go

@@ -6,6 +6,7 @@ import (
 	"errors"
 	"fmt"
 	"io/fs"
+	"net/url"
 	"os"
 	"path/filepath"
 	"slices"
@@ -107,7 +108,19 @@ const reportParams = "mode=ro" +
 // openDB opens the SQLite database at path with the connection
 // parameters params. It does not create or verify the schema.
 func openDB(path, params string) (*sql.DB, error) {
-	db, err := sql.Open("sqlite", "file:"+path+"?"+params)
+	// The path is escaped into a file: URI, so ?, # and % in it stay
+	// part of the file name. SQLite reads what follows file:// up to
+	// the next / as a host name, so an absolute path goes after an
+	// empty host (file:///abs) and a relative path goes without one
+	// (file:rel).
+	uri := url.URL{
+		Scheme:   "file",
+		OmitHost: !filepath.IsAbs(path),
+		Path:     path,
+		RawQuery: params,
+	}
+
+	db, err := sql.Open("sqlite", uri.String())
 	if err != nil {
 		return nil, fmt.Errorf("open database %s: %w", path, err)
 	}

main.go

@@ -51,6 +51,10 @@ const (
 // cobra prints for it is the whole message.
 var errNoSubcommand = errors.New("no subcommand")
 
+// errWorkersBelowOne is the usage error for a scan --workers value
+// below 1.
+var errWorkersBelowOne = errors.New("--workers must be at least 1")
+
 // Version is the build version, injected at link time via -ldflags
 // (see the Makefile); "dev" for a plain go build.
 //
@@ -98,8 +102,7 @@ func run(args []string, stdout, stderr io.Writer) int {
 
 		return exitFatal
 	default:
-		// A usage error: cobra has already printed the message and
-		// the usage text.
+		// A usage error, which cobra has already reported on stderr.
 		return exitUsage
 	}
 }
@@ -154,6 +157,9 @@ func newRootCommand(stdout, stderr io.Writer) *cobra.Command {
 		Use:   cmdScan + " [--workers N] [-x] PATH...",
 		Short: "Walk trees and synchronize the scan database",
 		Args:  cobra.MinimumNArgs(1),
+		PreRunE: func(cmd *cobra.Command, _ []string) error {
+			return checkScanWorkers(cmd, scanWorkers)
+		},
 		RunE: runE(func(ctx context.Context, args []string) error {
 			ctx, stop := interruptContext(ctx)
 			defer stop()
@@ -189,6 +195,19 @@ func newRootCommand(stdout, stderr io.Writer) *cobra.Command {
 	return root
 }
 
+// checkScanWorkers rejects a scan --workers value below 1. That is a
+// usage error reported in one line: cobra prints the returned message
+// without the usage text, and run exits 2.
+func checkScanWorkers(cmd *cobra.Command, workers int) error {
+	if workers >= 1 {
+		return nil
+	}
+
+	cmd.SilenceUsage = true
+
+	return fmt.Errorf("%w, got %d", errWorkersBelowOne, workers)
+}
+
 // runE adapts a subcommand implementation, or the version print, to
 // cobra's RunE. Cobra prints the error and the command's usage text for
 // every error RunE returns, but a subcommand that ran and failed has no

main_test.go

@@ -8,6 +8,7 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
+	"slices"
 	"strconv"
 	"strings"
 	"testing"
@@ -84,21 +85,41 @@ func makeReadOnly(t *testing.T, path string) {
 
 // captureStderr redirects os.Stderr to a file for the rest of the test
 // and returns a function reading back everything written to it. scan
-// writes its warnings and summary straight to os.Stderr, not to the
-// stderr writer run is given.
+// writes its warnings and summary, and report and trees their
+// summaries, straight to os.Stderr, not to the stderr writer run is
+// given.
 func captureStderr(t *testing.T) func() string {
 	t.Helper()
 
-	f, err := os.Create(filepath.Join(t.TempDir(), "stderr"))
+	return capture(t, &os.Stderr)
+}
+
+// captureStdout does for os.Stdout what captureStderr does for
+// os.Stderr. scan is never given run's stdout writer, so anything it
+// printed would go straight to os.Stdout. The scan tests pass os.Stdout
+// as run's stdout too, so the one capture sees both.
+func captureStdout(t *testing.T) func() string {
+	t.Helper()
+
+	return capture(t, &os.Stdout)
+}
+
+// capture redirects *std, which is os.Stdout or os.Stderr, to a file
+// for the rest of the test and returns a function reading back
+// everything written to it.
+func capture(t *testing.T, std **os.File) func() string {
+	t.Helper()
+
+	f, err := os.Create(filepath.Join(t.TempDir(), "output"))
 	if err != nil {
 		t.Fatal(err)
 	}
 
-	saved := os.Stderr
-	os.Stderr = f
+	saved := *std
+	*std = f
 
 	t.Cleanup(func() {
-		os.Stderr = saved
+		*std = saved
 
 		_ = f.Close()
 	})
@@ -183,30 +204,33 @@ func TestRunFatalAfterOpenClosesDatabase(t *testing.T) {
 	// sidecar check is evidence of the close only for scan: report and
 	// trees only read a database that is out of WAL mode, which leaves
 	// nothing on disk whether they close it or not.
-	cases := map[string][]string{
-		cmdScan:   {cmdScan},
-		cmdReport: {cmdReport},
-		cmdTrees:  {cmdTrees},
-	}
+	//
+	// The subcommands come from the command tree, so a new one is
+	// checked too: one wired with a bare RunE instead of runE reports
+	// its failure as a usage error, exit 2 with the usage text.
+	for _, cmd := range newRootCommand(io.Discard, io.Discard).Commands() {
+		name := cmd.Name()
 
-	for name, args := range cases {
 		t.Run(name, func(t *testing.T) {
 			path := brokenDatabase(t)
 			t.Setenv(databaseEnv, path)
 
+			args := []string{name}
 			if name == cmdScan {
 				args = append(args, t.TempDir())
 			}
 
-			var stdout, stderr bytes.Buffer
+			stdout := captureStdout(t)
 
-			code := run(args, &stdout, &stderr)
+			var stderr bytes.Buffer
+
+			code := run(args, os.Stdout, &stderr)
 			if code != exitFatal {
 				t.Errorf("run(%v) = %d, want %d", args, code, exitFatal)
 			}
 
 			assertNoSidecars(t, path)
-			assertFatalOutput(t, stderr.String(), stdout.String())
+			assertFatalOutput(t, stderr.String(), stdout())
 
 			// Proof that the failure happened after the open: only a
 			// query against the opened database can report this.
@@ -218,22 +242,24 @@ func TestRunFatalAfterOpenClosesDatabase(t *testing.T) {
 	}
 }
 
-func TestRunMissingOperandIsFatalNotUsage(t *testing.T) {
+func TestRunNonexistentPathIsFatalNotUsage(t *testing.T) {
 	// README §Error handling: a PATH operand that does not exist is a
 	// fatal error (1), not a usage error (2) — and a runtime failure
 	// must not dump the usage text.
 	t.Setenv(databaseEnv, testDBPath(t))
 
-	var stdout, stderr bytes.Buffer
+	stdout := captureStdout(t)
+
+	var stderr bytes.Buffer
 
 	missing := filepath.Join(t.TempDir(), "nope")
 
-	code := run([]string{cmdScan, missing}, &stdout, &stderr)
+	code := run([]string{cmdScan, missing}, os.Stdout, &stderr)
 	if code != exitFatal {
 		t.Errorf("run(scan %s) = %d, want %d", missing, code, exitFatal)
 	}
 
-	assertFatalOutput(t, stderr.String(), stdout.String())
+	assertFatalOutput(t, stderr.String(), stdout())
 }
 
 // assertFatalOutput checks that a fatal error was reported the way
@@ -257,6 +283,34 @@ func assertFatalOutput(t *testing.T, stderr, stdout string) {
 	}
 }
 
+func TestRunMissingDatabaseIsFatal(t *testing.T) {
+	// README §Database: report and trees need an existing database; a
+	// missing one exits 1 with a message telling the user to run scan.
+	for _, name := range []string{cmdReport, cmdTrees} {
+		t.Run(name, func(t *testing.T) {
+			path := testDBPath(t)
+			t.Setenv(databaseEnv, path)
+
+			var stdout, stderr bytes.Buffer
+
+			code := run([]string{name}, &stdout, &stderr)
+			if code != exitFatal {
+				t.Errorf("run(%s) = %d, want %d", name, code, exitFatal)
+			}
+
+			want := "sfdupes: " + path + ": no database (run \"sfdupes " +
+				"scan\" first, or set " + databaseEnv + ")\n"
+			if got := stderr.String(); got != want {
+				t.Errorf("stderr = %q, want %q", got, want)
+			}
+
+			if got := stdout.String(); got != "" {
+				t.Errorf("stdout = %q, want nothing (data only)", got)
+			}
+		})
+	}
+}
+
 func TestRunUsageErrors(t *testing.T) {
 	// Usage errors keep exiting 2 with cobra's own report on stderr.
 	cases := map[string]struct {
@@ -295,6 +349,42 @@ func TestRunUsageErrors(t *testing.T) {
 	}
 }
 
+func TestRunScanRejectsWorkersBelowOne(t *testing.T) {
+	// README §scan mode: --workers below 1 is a usage error reported in
+	// one line on stderr, before the scan opens the database.
+	for _, workers := range []string{"0", "-1"} {
+		t.Run(workers, func(t *testing.T) {
+			dbPath := testDBPath(t)
+			t.Setenv(databaseEnv, dbPath)
+
+			var stdout, stderr bytes.Buffer
+
+			args := []string{cmdScan, "--workers", workers, t.TempDir()}
+
+			code := run(args, &stdout, &stderr)
+			if code != exitUsage {
+				t.Errorf("run(%v) = %d, want %d", args, code, exitUsage)
+			}
+
+			want := "Error: --workers must be at least 1, got " + workers +
+				"\n"
+			if got := stderr.String(); got != want {
+				t.Errorf("stderr = %q, want %q", got, want)
+			}
+
+			if got := stdout.String(); got != "" {
+				t.Errorf("stdout = %q, want nothing (data only)", got)
+			}
+
+			_, err := os.Stat(dbPath)
+			if !errors.Is(err, fs.ErrNotExist) {
+				t.Errorf("stat %s: %v, want the database never created",
+					dbPath, err)
+			}
+		})
+	}
+}
+
 func TestRunHelp(t *testing.T) {
 	t.Parallel()
 
@@ -398,17 +488,16 @@ func scanFixture(t *testing.T) []string {
 func scanOK(t *testing.T, operands ...string) string {
 	t.Helper()
 
-	var stdout bytes.Buffer
-
+	stdout := captureStdout(t)
 	stderr := captureStderr(t)
 
-	code := run(append([]string{cmdScan}, operands...), &stdout, os.Stderr)
+	code := run(append([]string{cmdScan}, operands...), os.Stdout, os.Stderr)
 	if code != exitOK {
 		t.Fatalf("run(scan %q) = %d, want %d; stderr: %s",
 			operands, code, exitOK, stderr())
 	}
 
-	if got := stdout.String(); got != "" {
+	if got := stdout(); got != "" {
 		t.Errorf("scan stdout = %q, want nothing (data only)", got)
 	}
 
@@ -416,10 +505,41 @@ func scanOK(t *testing.T, operands ...string) string {
 }
 
 func TestRunScanSucceedsDespiteWarnings(t *testing.T) {
+	// README §Error handling: a scan that skips a file it cannot read
+	// warns, counts the skip in its summary, and still exits 0, which
+	// scanOK checks along with the empty stdout.
+	if os.Geteuid() == 0 {
+		t.Skip("root ignores file permissions")
+	}
+
 	path := testDBPath(t)
 	t.Setenv(databaseEnv, path)
 
-	scanFixture(t)
+	dir := t.TempDir()
+	writeFile(t, dir, "a.bin", pattern(1, 300))
+
+	// Same size as a.bin, so the scan reads it, and the read fails.
+	unreadable := writeFile(t, dir, "unreadable.bin", pattern(2, 300))
+
+	err := os.Chmod(unreadable, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	stderr := scanOK(t, dir)
+
+	warning := "hash " + unreadable + ": open " + unreadable +
+		": permission denied\n"
+	if !strings.Contains(stderr, warning) {
+		t.Errorf("stderr = %q, want %q", stderr, warning)
+	}
+
+	summary := "scan: 1 files seen (1 added, 0 updated, 0 removed, " +
+		"0 unchanged), 1 skipped\n"
+	if !strings.Contains(stderr, summary) {
+		t.Errorf("stderr = %q, want %q", stderr, summary)
+	}
+
 	assertNoSidecars(t, path)
 }
 
@@ -526,12 +646,14 @@ func TestRunReportSucceeds(t *testing.T) {
 
 	dupes := scanFixture(t)
 
-	var stdout, stderr bytes.Buffer
+	var stdout bytes.Buffer
 
-	code := run([]string{cmdReport}, &stdout, &stderr)
+	stderr := captureStderr(t)
+
+	code := run([]string{cmdReport}, &stdout, os.Stderr)
 	if code != exitOK {
 		t.Fatalf("run(report) = %d, want %d; stderr: %s",
-			code, exitOK, stderr.String())
+			code, exitOK, stderr())
 	}
 
 	want := "first\tdupe\tsize\n" + dupes[0] + "\t" + dupes[1] + "\t300\n"
@@ -539,6 +661,12 @@ func TestRunReportSucceeds(t *testing.T) {
 		t.Errorf("stdout = %q, want %q", got, want)
 	}
 
+	want = "report: 2 records read, 1 duplicate groups, 1 dupe files, " +
+		"300 B reclaimable\n"
+	if got := stderr(); got != want {
+		t.Errorf("stderr = %q, want %q", got, want)
+	}
+
 	assertNoSidecars(t, path)
 }
 
@@ -548,12 +676,14 @@ func TestRunTreesSucceeds(t *testing.T) {
 
 	dupes := scanFixture(t)
 
-	var stdout, stderr bytes.Buffer
+	var stdout bytes.Buffer
 
-	code := run([]string{cmdTrees}, &stdout, &stderr)
+	stderr := captureStderr(t)
+
+	code := run([]string{cmdTrees}, &stdout, os.Stderr)
 	if code != exitOK {
 		t.Fatalf("run(trees) = %d, want %d; stderr: %s",
-			code, exitOK, stderr.String())
+			code, exitOK, stderr())
 	}
 
 	// The two directories holding the duplicate pair are duplicate
@@ -564,6 +694,12 @@ func TestRunTreesSucceeds(t *testing.T) {
 		t.Errorf("stdout = %q, want %q", got, want)
 	}
 
+	want = "trees: 2 records read, 1 duplicate tree groups, 1 dupe trees, " +
+		"300 B reclaimable\n"
+	if got := stderr(); got != want {
+		t.Errorf("stderr = %q, want %q", got, want)
+	}
+
 	assertNoSidecars(t, path)
 }
 
@@ -603,6 +739,73 @@ func TestRunReportsNeedOnlyReadAccess(t *testing.T) {
 	}
 }
 
+// assertRunsUseDatabase runs scan, then report and trees, against the
+// database that SFDUPES_DATABASE names, the file name in dir. It fails
+// unless the reports find the duplicate pair the scan recorded and dir
+// then holds only that file and its lock file: nothing was created
+// under a shortened name.
+func assertRunsUseDatabase(t *testing.T, dir, name string) {
+	t.Helper()
+
+	dupes := scanFixture(t)
+
+	want := "first\tdupe\tsize\n" + dupes[0] + "\t" + dupes[1] + "\t300\n"
+	if got := runStdout(t, cmdReport); got != want {
+		t.Errorf("report stdout = %q, want %q", got, want)
+	}
+
+	want = "first\tdupe\tfiles\tsize\n" +
+		filepath.Dir(dupes[0]) + "\t" + filepath.Dir(dupes[1]) + "\t1\t300\n"
+	if got := runStdout(t, cmdTrees); got != want {
+		t.Errorf("trees stdout = %q, want %q", got, want)
+	}
+
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	got := make([]string, 0, len(entries))
+	for _, e := range entries {
+		got = append(got, e.Name())
+	}
+
+	if wantFiles := []string{name, name + ".lock"}; !slices.Equal(got, wantFiles) {
+		t.Errorf("%s holds %q, want %q", dir, got, wantFiles)
+	}
+}
+
+func TestRunDatabasePathUsedAsGiven(t *testing.T) {
+	// README §Database: the path names the database file exactly. In
+	// SQLite's connection string an unescaped ? or # would end the file
+	// name and % would start an escape, and a path starting with //
+	// could be read as a host name. %25 is a valid escape, so unescaped
+	// this name opens a file named a without any error.
+	const name = "a?b#c%25d e.sqlite"
+
+	t.Run("absolute", func(t *testing.T) {
+		dir := t.TempDir()
+		t.Setenv(databaseEnv, filepath.Join(dir, name))
+
+		assertRunsUseDatabase(t, dir, name)
+	})
+
+	t.Run("leading double slash", func(t *testing.T) {
+		dir := t.TempDir()
+		t.Setenv(databaseEnv, "/"+filepath.Join(dir, name))
+
+		assertRunsUseDatabase(t, dir, name)
+	})
+
+	t.Run("relative", func(t *testing.T) {
+		dir := t.TempDir()
+		t.Chdir(dir)
+		t.Setenv(databaseEnv, name)
+
+		assertRunsUseDatabase(t, dir, name)
+	})
+}
+
 // holdScanLock takes the lock on the database at path, as a running
 // scan does, and holds it until the test ends. It fails the test when
 // the lock is already held.
@@ -626,9 +829,11 @@ func TestRunSecondScanFails(t *testing.T) {
 
 	holdScanLock(t, path)
 
-	var stdout, stderr bytes.Buffer
+	stdout := captureStdout(t)
 
-	code := run([]string{cmdScan, t.TempDir()}, &stdout, &stderr)
+	var stderr bytes.Buffer
+
+	code := run([]string{cmdScan, t.TempDir()}, os.Stdout, &stderr)
 	if code != exitFatal {
 		t.Errorf("run(scan) = %d, want %d", code, exitFatal)
 	}
@@ -639,7 +844,7 @@ func TestRunSecondScanFails(t *testing.T) {
 		t.Errorf("stderr = %q, want %q", got, want)
 	}
 
-	if got := stdout.String(); got != "" {
+	if got := stdout(); got != "" {
 		t.Errorf("stdout = %q, want nothing (data only)", got)
 	}
 

package.json

@@ -0,0 +1,5 @@
+{
+  "devDependencies": {
+    "prettier": "3.8.1"
+  }
+}

scan.go

@@ -98,14 +98,11 @@ type fileMeta struct {
 // is released after it. When ctx is cancelled, as by the SIGINT or
 // SIGTERM that interruptContext catches, the scan keeps what it has
 // hashed (see syncScan), prints how many files its walk reached, and
-// returns errInterrupted.
+// returns errInterrupted. workers must be at least 1; the scan command
+// rejects anything less.
 func runScan(ctx context.Context, roots []string, workers int,
 	oneFS bool,
 ) error {
-	if workers < 1 {
-		workers = 1
-	}
-
 	roots, err := resolveRoots(roots)
 	if err != nil {
 		return err

script/bootstrap

@@ -1,12 +1,9 @@
 #!/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,
-# or apk (detected in that order); assumes nothing is present (not git,
-# make, or go). The linter is NOT installed: golangci-lint runs via
-# docker only (script/lint), pinned by image digest, so the only lint
-# prerequisite is a working docker — which is warned about, not
-# installed, because everything except linting works without it.
+# this repo. Idempotent; assumes nothing is present (not git, make, or
+# go). Base tooling comes from nix, apt, brew, or apk (detected in that
+# order). golangci-lint and prettier are never installed: they run via
+# docker only (script/lint, script/fmt, script/fmt-check).
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
@@ -61,25 +58,19 @@ missing() {
 main() {
     cd "$ROOT"
 
-    # System tooling, deliberately unpinned: these come from the host
-    # package manager and whatever version it ships is what the host
-    # gets, so a presence check is the right check. The repo pins no
-    # system toolchain versions — the Go language version is governed by
-    # go.mod, and builds that must be reproducible run in the Docker
-    # image, whose base images are pinned by digest.
+    # Deliberately unpinned, so presence is the whole check: go.mod
+    # governs the Go version, and reproducible builds run in the
+    # digest-pinned Docker images.
     if missing git; then pkg_install git git git git; fi
     if missing make; then pkg_install gnumake make make make; fi
     if missing go; then pkg_install go golang go go; fi
 
-    # Linting runs via docker only (script/lint), so docker is a lint
-    # prerequisite rather than something bootstrap installs. Warn, do
-    # not fail: everything except `make lint` — and, through it,
-    # `make check`, `make docker` and the pre-commit hook — works
-    # without it.
+    # Warn, do not fail: only the targets named below, and the
+    # pre-commit hook, need docker.
     if missing docker; then
-        echo "bootstrap: WARNING: docker not found; make lint, make check" >&2
-        echo "bootstrap: and make docker require it. Install docker to" >&2
-        echo "bootstrap: run the linter." >&2
+        echo "bootstrap: WARNING: docker not found; make test, make lint," >&2
+        echo "bootstrap: make fmt, make fmt-check, make check and" >&2
+        echo "bootstrap: make docker require it." >&2
     fi
 
     go mod download

script/cibuild

@@ -1,34 +1,28 @@
 #!/bin/sh
-# script/cibuild: run the CI build. The Gitea workflow runs this on
-# push.
-#
-# The Dockerfile runs the gates individually as build steps, not the
-# make check aggregate: the lint stage runs make fmt-check,
-# script/verify-lint-image-pin, golangci-lint config verify and
-# golangci-lint run; the build stage, dropped to an unprivileged user,
-# runs make test and make fmt-check. Neither make lint nor make check
-# appears, because both reach script/lint, which is itself a docker
-# build, and a docker build cannot run inside one. Lint is not skipped
-# by that — the linter is invoked directly in the lint stage, and the
-# build stage's COPY --from=lint makes that stage a prerequisite, so
-# BuildKit must finish it first. Between the two stages everything
-# make check would run has run, which is why a successful build here
-# implies the repo is green.
-#
-# That implication holds only because of CHECK_EPOCH. A COPY layer is
-# invalidated only by changed content, and a rebuild of an unchanged
-# checkout sends the same content, so without a fresh value here Docker
-# serves the gate layers from cache and the build reports a green it
-# never earned. Passing the current epoch invalidates the gate
-# layers on every run while leaving the pinned base images and
-# go mod download cached; see the Dockerfile for the placement.
+# 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
+# final stage depends on are RUN steps, and a cached one is a check that
+# did not run.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build --build-arg CHECK_EPOCH="$(date +%s)" .
+    "$SCRIPT_DIR/bootstrap"
+    "$SCRIPT_DIR/check"
+    # Own line: a failing command substitution inside an argument does
+    # not trip `set -e`, so the inline form degrades silently to an
+    # empty constant. 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"
+    docker build --no-cache \
+        --build-arg VERSION="$version" \
+        -t "$("$SCRIPT_DIR/projectname")" .
 }
 
 main "$@"

script/docker

@@ -1,14 +1,8 @@
 #!/bin/sh
 # script/docker: build the Docker image tagged with the project name.
-# The tag comes from script/projectname.
-#
-# CHECK_EPOCH is passed for the same reason script/cibuild passes it:
-# without it Docker serves the Dockerfile's gate layers from cache on an
-# unchanged tree and this exits 0 having run neither the lint stage's
-# gates nor the builder stage's test and fmt-check gates. This is the
-# set of gates a developer or reviewer runs by hand, so a cached pass
-# here is the most misleading result the repo can produce. Dependency
-# layers sit above the ARG and stay cached.
+# Identical in all repos; the tag comes from script/projectname.
+# --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)"
@@ -16,10 +10,15 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build \
-        --build-arg CHECK_EPOCH="$(date +%s)" \
-        -t "$("$SCRIPT_DIR/projectname")" \
-        .
+    # 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"
+    docker build --no-cache \
+        --build-arg VERSION="$version" \
+        -t "$("$SCRIPT_DIR/projectname")" .
 }
 
 main "$@"

script/fmt

@@ -1,12 +1,23 @@
 #!/bin/sh
-# script/fmt: format all files (writes).
+# script/fmt: format all files (writes): the Go sources with gofmt, the
+# Markdown with prettier. prettier is never installed on the host: it
+# runs from the Dockerfile's prettier stage with the repository mounted,
+# as the calling user so the files it rewrites keep their owner. The
+# build passes --no-cache, as every docker build in script/ does. The tag
+# makes each build replace the previous image instead of leaving another
+# one behind.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
     gofmt -s -w .
+    image="$("$SCRIPT_DIR/projectname")-prettier"
+    docker build -q --no-cache --target prettier -t "$image" . >/dev/null
+    docker run --rm --user "$(id -u):$(id -g)" -v "$ROOT:/src" "$image" \
+        prettier --write '**/*.md' --tab-width 4 --prose-wrap always
 }
 
 main "$@"

script/fmt-check

@@ -1,18 +1,39 @@
 #!/bin/sh
 # script/fmt-check: check formatting (read-only). Same scope as
-# script/fmt, but fails instead of writing.
+# script/fmt, but fails instead of writing. gofmt and prettier both run
+# every time and each reports its own failure, so the output says which
+# one failed.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    files="$(gofmt -s -l .)"
+    status=0
+
+    # Under set -e a bare assignment would end the script when gofmt
+    # fails (a Go file it cannot parse), and prettier would never run.
+    if ! files="$(gofmt -s -l .)"; then
+        echo "gofmt: failed; see its errors above" >&2
+        status=1
+    fi
     if [ -n "$files" ]; then
         echo "gofmt: files not formatted:" >&2
         echo "$files" >&2
-        exit 1
+        status=1
     fi
+
+    # Same image as script/fmt; see there.
+    image="$("$SCRIPT_DIR/projectname")-prettier"
+    docker build -q --no-cache --target prettier -t "$image" . >/dev/null
+    if ! docker run --rm -v "$ROOT:/src:ro" "$image" \
+        prettier --check '**/*.md' --tab-width 4 --prose-wrap always; then
+        echo "prettier: Markdown not formatted; run make fmt" >&2
+        status=1
+    fi
+
+    exit "$status"
 }
 
 main "$@"

script/lint

@@ -1,29 +1,23 @@
 #!/bin/sh
-# script/lint: run the linter. golangci-lint is never installed on a
-# host: it runs via docker only, one way, everywhere — this builds
-# Dockerfile.lint, which COPYs the repo into the digest-pinned
-# golangci-lint image and lints as a build step, so a successful build
-# is a clean lint. The only prerequisite is a working docker. The gate
-# steps make no network calls of their own, but Dockerfile.lint runs
-# `go mod download` above them, so a cold cache does reach the network
-# (as does pulling the pinned image); that layer stays cached, and once
-# it is warm this runs offline until go.mod or go.sum changes.
+# script/lint: run the linter. Linting is a phase of the Dockerfile and
+# this builds that phase alone; the linter is never installed or run on
+# a developer host, where a shared result cache and a host-global lock
+# make its answer untrustworthy.
 #
-# CHECK_EPOCH is what makes the result mean anything. Without it docker
-# serves the gate layers from cache on an unchanged tree and this exits
-# 0 in well under a second having run no linter. The PID is in the value
-# as well as the epoch because two lint runs land inside the same second
-# easily, and `date +%s` alone would cache the second one.
+# 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
+# that did not run. The tag makes each build replace the previous image
+# instead of leaving a dangling one behind.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build \
-        --build-arg CHECK_EPOCH="$(date +%s)-$$" \
-        -f Dockerfile.lint \
-        .
+    docker build --no-cache \
+        --target lint \
+        -t "$("$SCRIPT_DIR/projectname")-lint" .
 }
 
 main "$@"

script/test

@@ -1,17 +1,19 @@
 #!/bin/sh
-# script/test: run the test suite. Reruns verbosely on failure so CI
-# logs show which test failed.
+# 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
+# run, and a tag so each build replaces the previous image.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    go test -timeout 30s -cover ./... || {
-        echo "--- Rerunning with -v for details ---"
-        go test -timeout 30s -v ./...
-        exit 1
-    }
+    docker build --no-cache \
+        --target test \
+        -t "$("$SCRIPT_DIR/projectname")-test" .
 }
 
 main "$@"

script/verify-lint-image-pin

@@ -1,84 +0,0 @@
-#!/bin/sh
-# script/verify-lint-image-pin: fail unless the golangci-lint image
-# referenced by Dockerfile.lint and the one referenced by the main
-# Dockerfile's lint stage are the same image at the same digest. Our own
-# extension to scripts-to-rule-them-all, not one of its entrypoints.
-#
-# The linter version is pinned in two independent files. That is the
-# shape #42 turned into a build failure rather than tolerate: nothing
-# else keeps the two in sync, and a bump applied to one file alone would
-# leave `make lint` and the fail-fast lint stage of `make docker`
-# linting the same tree against different rulesets, both green. This is
-# the single guard that stops it, run as a gate in both files.
-#
-# It deliberately restates neither pin. A hardcoded expected digest here
-# would be a third copy — one more thing to bump, and the same drift one
-# file further out. It compares the two files to each other and knows
-# nothing about which version is correct.
-#
-# A reference that cannot be read is a hard failure, not a skip: a
-# comparison of two empty strings succeeds, which would turn this guard
-# into exactly the unearned green it exists to prevent.
-set -eu
-
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
-
-LINT_DOCKERFILE="Dockerfile.lint"
-MAIN_DOCKERFILE="Dockerfile"
-
-# Echo the single golangci-lint image reference in the named Dockerfile.
-# Scans every argument of every FROM instruction rather than assuming a
-# field position, so `FROM --platform=... img AS stage` reads correctly.
-# Exits non-zero, with a diagnosis, unless there is exactly one.
-lint_image_ref() {
-    file="$1"
-
-    if [ ! -f "$file" ]; then
-        echo "verify-lint-image-pin: $file: not found" >&2
-        return 1
-    fi
-
-    refs="$(
-        awk '
-            toupper($1) == "FROM" {
-                for (i = 2; i <= NF; i++) {
-                    if ($i ~ /^golangci\/golangci-lint[:@]/) {
-                        print $i
-                    }
-                }
-            }
-        ' "$file"
-    )"
-
-    count="$(printf '%s' "$refs" | grep -c . || true)"
-    if [ "$count" -ne 1 ]; then
-        echo "verify-lint-image-pin: $file: expected exactly one" \
-            "golangci/golangci-lint FROM reference, found $count" >&2
-        return 1
-    fi
-
-    printf '%s\n' "$refs"
-}
-
-main() {
-    cd "$ROOT"
-
-    lint_ref="$(lint_image_ref "$LINT_DOCKERFILE")"
-    main_ref="$(lint_image_ref "$MAIN_DOCKERFILE")"
-
-    if [ "$lint_ref" != "$main_ref" ]; then
-        echo "verify-lint-image-pin: the linter image is pinned twice and" \
-            "the two pins disagree:" >&2
-        echo "verify-lint-image-pin:   $LINT_DOCKERFILE: $lint_ref" >&2
-        echo "verify-lint-image-pin:   $MAIN_DOCKERFILE: $main_ref" >&2
-        echo "verify-lint-image-pin: bump both FROM lines together so" \
-            "script/lint and the Dockerfile lint stage keep running the" \
-            "same linter" >&2
-        exit 1
-    fi
-
-    echo "verify-lint-image-pin: $LINT_DOCKERFILE and $MAIN_DOCKERFILE" \
-        "agree on $lint_ref"
-}
-
-main "$@"

yarn.lock

@@ -0,0 +1,8 @@
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1
+
+
+prettier@3.8.1:
+  version "3.8.1"
+  resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.8.1.tgz#edf48977cf991558f4fcbd8a3ba6015ba2a3a173"
+  integrity sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg==