Run every lint in a container via Dockerfile.lint (closes #40)

The linter is no longer installed on the host and no longer invoked
there. script/lint is now `docker build -f Dockerfile.lint .` and
nothing else, with the linter running as a build step, so a successful
build of that file is a clean lint — and it works unchanged where the
docker daemon is remote and bind mounts are impossible.

That removes three host-only failure mechanisms rather than mitigating
them: the result cache keyed on file content rather than location, which
produced a confirmed false green and a string of findings reported
against other checkouts; the host-global $TMPDIR/golangci-lint.lock,
which fails a run with `parallel golangci-lint is running` in a way no
caller can distinguish from findings; and host/container version skew,
which hid thirteen findings on one repo. A container per run has its own
cache, its own lock and a binary pinned by digest.

Resolving the recursion this creates. script/lint is a docker build, so
a Dockerfile that runs `make check` would nest a build inside a build
step where there is no daemon. Fixed by direction, not detection: the
main Dockerfile runs script/test and script/fmt-check individually, with
a comment saying why `make check` must not come back, and script/cibuild
runs script/lint first for fail-fast feedback. script/check still runs
all three, so developers and the pre-commit hook are unaffected.

Dockerfile.lint carries the same CHECK_EPOCH guard as the main image,
with the ARG placed below the dependency layer so only the lint steps
re-run. Blanket --no-cache was rejected: it re-runs the dependency
install on every lint and makes linting network-dependent.

golangci-lint config verify is kept, on measurement rather than
preference. Under the pinned v2.12.2, a bogus top-level key and a bogus
key nested under linters.settings.lll both pass `golangci-lint run` with
exit 0 and `0 issues` while config verify exits 3 and names them; an
unknown linter name fails run and passes config verify. The two catch
disjoint classes, and `run` alone silently ignores the class where a
threshold reads as configured and is not applied. The concern that
config verify fetches its JSON schema over live HTTPS does not hold for
this version: every case reproduced byte-identically under
`docker run --network none`, in a container where `getent hosts
golangci-lint.run` exits 2. The schema is embedded in the pinned binary.

Two canonical forms are superseded and deleted rather than left standing
beside the new one, because consuming repos read these documents
literally and two contradictory canonical script/lint forms is worse
than either. The script/bootstrap golangci-lint install landed for
#28 is removed: nothing invokes
a host linter now, so it can only reintroduce the skew it was written to
close. Its version-enforcement principle — compare version not presence,
re-resolve through PATH after installing, let a mis-parse fall through
to reinstall, and call it — stays documented for any other pinned host
tool. The per-checkout GOLANGCI_LINT_CACHE/TMPDIR wrapper is removed
with it; its entire subject was making a host run trustworthy. Adopting
repos delete .lint-cache/ from .gitignore and .dockerignore too. The Go
multistage lint stage and its COPY --from=lint ordering trick go the
same way: that stage ran `make lint`, which is now a docker build.

Corrected everywhere the claim that a successful docker build implies
lint passed — REPO_POLICIES.md, both repo checklists, the Go styleguide
and the README. The guarantee now belongs to script/cibuild, which runs
both container builds; a bare `docker build .` never lints at all.

Verified in this repo, not only documented: two consecutive script/lint
runs on a byte-identical tree both executed prettier (4.556s and 3.738s,
lint layers DONE with a fresh epoch printed, dependency layers CACHED as
intended); a planted violation failed the build naming the file, and
reverting it went green; a bare `docker build -f Dockerfile.lint .`
failed on the guard; make check, script/docker and script/cibuild all
green with the check layers demonstrably executing; and the main image
build completed without attempting a nested build.

.dockerignore

@@ -1,3 +1,97 @@
+# Docker matches this file with moby/patternmatcher: Go filepath.Match
+# semantics plus a `**` extension, compiled to a regexp. Plain
+# filepath.Match has no `**` at all. What follows from that: `*` does not
+# cross `/`, and a pattern without a leading `**/` is anchored at the
+# build-context root. Every depth-independent pattern therefore needs the
+# `**/` prefix — without it `config/.env` and `certs/server.key` still
+# ship while the file reads as solved.
+#
+# Root-anchored entries are for paths that occur exactly once, at the
+# context root. A host-built binary is the usual case, and it must be
+# written anchored: `/myapp`, never `**/myapp`. The prefixed form also
+# matches `cmd/myapp/`, which deletes the package directory from the
+# context. In-repo agent scratch is the other case, for the same reason
+# — with the caveat recorded at that entry: anchoring is exact only
+# where agents run at the repo root, and a repo where they do not must
+# add its own entries.
+#
+# Matching is case-sensitive, so `**/*.key` does not match
+# `certs/SERVER.KEY`, which is reachable on the case-insensitive
+# filesystems most laptops use. Adding an ALL-CAPS twin per pattern is
+# not the fix: it still misses `Server.Key` while reading as though case
+# were handled. Character ranges cover every spelling in one line, so
+# every secret name below is written that way — including the
+# extensionless SSH keys and `.envrc`, because on those same
+# case-insensitive filesystems direnv reads `.ENVRC` and ssh reads
+# `ID_RSA`.
+#
+# `**/*.[eE][nN][vV]` also excludes a committed env template such as
+# `example.env`. If the build genuinely needs one, re-include it with a
+# negation after the pattern: `!docs/example.env`.
+#
+# Extend this file with the repo's own host-built artifacts (compiled
+# binaries, test binaries, coverage output); those are per-repo and
+# belong here because a host build otherwise drops them into the
+# context.
+
+# Repository metadata: exactly one, at the context root. Excluding it
+# means `git describe` cannot run in any build stage, and it fails
+# quietly there rather than erroring, so a version embedded that way
+# comes out empty. Compute the version on the host and pass it in with
+# `--build-arg VERSION=...`; see the version rule in REPO_POLICIES.md.
 .git
-node_modules
+
-.DS_Store
+# In-repo agent scratch: a directory holding a full additional checkout
+# of the repo for each in-flight agent. Anchored because it occurs
+# exactly once *where agents run at the repo root*, which is the
+# convention this file assumes; the `**/` form would also match any
+# nested directory of that name and delete it from the build.
+#
+# KNOWN GAP, and it is not hypothetical: the directory is created in the
+# agent's working directory. If agents in this repo run in
+# subdirectories — a monorepo with a per-service agent, say — then
+# `services/api/.claude/` is NOT excluded by the line below and still
+# reaches the build context and the image, which is the exposure this
+# entry exists to close. A repo in that shape adds its own anchored
+# entries (`/services/api/.claude`), or `**/.claude` after confirming no
+# legitimately named nested directory would be caught.
+#
+# Not case-folded, unlike the secret patterns below: tooling creates
+# this directory in exactly one spelling, so a folded pattern would add
+# no coverage.
+.claude
+
+# Environment files. `*.env` covers both the bare `.env` name (`*` matches
+# the empty string) and the `prod.env` convention.
+**/*.[eE][nN][vV]
+**/.[eE][nN][vV].*
+**/.[eE][nN][vV][rR][cC]
+
+# Private keys and the bundles that carry them. Public certificates
+# (*.crt, *.cer) are deliberately absent: they are not secrets and are
+# sometimes a legitimate build input.
+**/*.[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][dD]25519
+
+# 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 under a developer's
+# hands, so it invalidates COPY for reasons unrelated to the source.
+**/*.swp
+**/*.swo
+**/*~
+**/*.bak
+**/.idea
+**/.vscode
+**/*.sublime-*

.gitea/workflows/check.yml

@@ -6,4 +6,4 @@ jobs:
         steps:
             # actions/checkout v4.2.2, 2026-02-22
             - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-            - run: docker build .
+            - run: script/cibuild

.gitignore

@@ -11,6 +11,12 @@ 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/
 

.golangci.yml

@@ -1,5 +1,9 @@
 version: "2"
 
+# Config schema uses the golangci-lint v2 layout (settings live under
+# linters.settings, not top-level linters-settings) so that the
+# thresholds below are actually applied by golangci-lint >= v2.
+
 run:
   timeout: 5m
   modules-download-mode: readonly
@@ -14,19 +18,17 @@ linters:
     - wsl              # Deprecated, replaced by wsl_v5
     - wrapcheck        # Too verbose for internal packages
     - varnamelen       # Short names like db, id are idiomatic Go
-
+  settings:
-linters-settings:
+    lll:
-  lll:
+      line-length: 88
-    line-length: 88
+    funlen:
-  funlen:
+      lines: 80
-    lines: 80
+      statements: 50
-    statements: 50
+    cyclop:
-  cyclop:
+      max-complexity: 15
-    max-complexity: 15
+    dupl:
-  dupl:
+      threshold: 100
-    threshold: 100
 
 issues:
-  exclude-use-default: false
   max-issues-per-linter: 0
   max-same-issues: 0

Dockerfile

@@ -1,11 +1,37 @@
 # node 22-alpine, 2026-02-22
 FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34
 
-RUN apk add --no-cache make
-
 WORKDIR /app
+
+# script/bootstrap installs all prerequisites (make via apk here; node
+# and yarn are already in the base image, so those steps are skipped).
+# Dependency manifests are copied first so the bootstrap layer is
+# cached until they change.
+COPY script/ script/
 COPY package.json yarn.lock ./
-RUN yarn install --frozen-lockfile
+RUN script/bootstrap
+
 COPY . .
 
-RUN make check
+# CHECK_EPOCH is a per-invocation nonce supplied by script/cibuild and
+# script/docker. Without it an unchanged tree serves this layer from
+# cache and the build reports a green it never ran. ARG is stage-scoped,
+# so it must be redeclared in every stage that runs checks. The guard
+# makes a bare `docker build .` fail loudly instead of silently reusing
+# the empty (and therefore stable) cache key. Expand the value into the
+# command so the cache miss does not depend on BuildKit's handling of an
+# unreferenced ARG. Both the guard and the check RUN reference the value,
+# so both are value-keyed: there are two independent invalidation points
+# here, not one. Keep both.
+ARG CHECK_EPOCH
+RUN [ -n "$CHECK_EPOCH" ] || exit 1
+
+# The individual non-lint checks, NOT `make check`. Lint is deliberately
+# absent here: `script/lint` is itself a `docker build` (of
+# Dockerfile.lint), so running `make check` in this image would attempt
+# a docker build inside a build step, where there is no daemon. Putting
+# `make check` back reintroduces exactly that recursion. Lint is not
+# skipped — script/cibuild runs script/lint first, in its own container,
+# before this build starts.
+RUN echo "check epoch: ${CHECK_EPOCH}" && script/test
+RUN script/fmt-check

Dockerfile.lint

@@ -0,0 +1,41 @@
+# Lint-only image. `script/lint` builds this file and nothing else: the
+# linter runs as a build step, so a successful build IS a clean lint.
+# Building rather than bind-mounting is what makes it work where the
+# docker daemon is remote and bind mounts are impossible.
+#
+# The linter is invoked directly below rather than through `make lint`.
+# That is not a style choice: `script/lint` IS this build, so calling it
+# from inside would recurse into a docker build with no daemon.
+#
+# This repo's linter is prettier over markdown. A Go repo's version of
+# this file differs only in the base image and the two lint commands;
+# see the containerised-lint rule in prompts/REPO_POLICIES.md.
+#
+# node 22-alpine, 2026-02-22
+FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34
+
+WORKDIR /app
+
+# Dependency layer first, and deliberately above the ARG below, so it
+# stays cached and only the lint steps re-run on every invocation.
+# Without that ordering the cache-bust would reinstall dependencies on
+# every lint and make linting network-dependent.
+COPY script/ script/
+COPY package.json yarn.lock ./
+RUN script/bootstrap
+
+COPY . .
+
+# CHECK_EPOCH is a per-invocation nonce supplied by script/lint. Without
+# it an unchanged tree serves the lint layer from cache and the build
+# reports a lint it never ran — a green that proves nothing, which is
+# the whole failure mode this file exists to avoid reintroducing. The
+# guard makes a bare `docker build -f Dockerfile.lint .` fail loudly
+# instead of silently reusing the empty (and therefore stable) cache
+# key. The value is expanded into the lint command as well, so the cache
+# miss does not depend on BuildKit's handling of an unreferenced ARG and
+# the epoch is visible in the build log. Keep both references.
+ARG CHECK_EPOCH
+RUN [ -n "$CHECK_EPOCH" ] || exit 1
+RUN echo "lint epoch: ${CHECK_EPOCH}" && \
+    yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always

Makefile

@@ -1,31 +1,32 @@
-.PHONY: test lint fmt fmt-check check docker hooks
+.PHONY: bootstrap setup test lint fmt fmt-check check docker hooks
 
-# flags are repeated here (also in .prettierrc) so this Makefile works
+# Makefile targets are thin shims; the implementations live in script/
-# standalone when copied as a template
+# per the scripts-to-rule-them-all pattern (see the Entrypoints section
-PRETTIER := yarn run prettier
+# of README.md).
+
+bootstrap:
+	@script/bootstrap
+
+setup:
+	@script/setup
 
 test:
-	@echo "No tests defined."
+	@script/test
 
 lint:
-	@echo "Linting markdown files..."
+	@script/lint
-	@$(PRETTIER) --check '**/*.md' --tab-width 4 --prose-wrap always
 
 fmt:
-	@$(PRETTIER) --write '**/*.md' --tab-width 4 --prose-wrap always
+	@script/fmt
 
 fmt-check:
-	@$(PRETTIER) --check '**/*.md' --tab-width 4 --prose-wrap always
+	@script/fmt-check
 
-check: test lint fmt-check
+check:
+	@script/check
 
 docker:
-	docker build -t prompts .
+	@script/docker
 
 hooks:
-	@printf '#!/bin/sh\nset -e\n' > .git/hooks/pre-commit
+	@script/install-precommit
-	@if [ -f go.mod ]; then \
-		printf 'go mod tidy\ngo fmt ./...\ngit diff --exit-code -- go.mod go.sum || { echo "go mod tidy changed files; please stage and retry"; exit 1; }\n' >> .git/hooks/pre-commit; \
-	fi
-	@printf 'make check\n' >> .git/hooks/pre-commit
-	@chmod +x .git/hooks/pre-commit

README.md

@@ -102,6 +102,47 @@ cd prompts
 Prompts are stored as Markdown files in `prompts/`. Copy or reference them as
 needed in your projects.
 
+## Entrypoints
+
+This repository adheres to the
+[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+standard: normalized scripts in `script/` are the entrypoints for the
+development workflow, and the Makefile targets are thin shims that call them.
+The scripts are POSIX sh (not bash) so they run in minimal containers such as
+alpine. We provide:
+
+- `script/bootstrap` — install all dependencies (yarn install)
+- `script/setup` — set up the repo for development after a fresh clone: runs
+  `script/bootstrap`, then `script/install-precommit`
+- `script/projectname` — output the project name (our own extension); used by
+  `script/docker` for the image tag
+- `script/test` — run the test suite (no tests defined here)
+- `script/lint` — lint the markdown files, by building `Dockerfile.lint`. The
+  linter runs in a container, always: it is never installed on the host and
+  never invoked there. Linting happens as a build step, so a successful build is
+  a clean lint, and the same per-invocation `CHECK_EPOCH` nonce used elsewhere
+  is what stops Docker serving that lint from cache on an unchanged tree
+- `script/fmt` — format all markdown files with prettier (writes)
+- `script/fmt-check` — check formatting (read-only)
+- `script/check` — run all checks: `test`, `lint`, `fmt-check` (our own
+  extension). Needs a docker daemon, since `script/lint` is a container build
+- `script/docker` — build the Docker image, tagged via `script/projectname`
+  (byte-identical across repos); passes the same `CHECK_EPOCH` nonce as
+  `script/cibuild`
+- `script/cibuild` — cd to the repo root, run `script/lint` first, then assign
+  `epoch="$(date +%s%N)$$"` and
+  `docker build --build-arg CHECK_EPOCH="$epoch" .` (what CI runs). Two
+  container builds: the lint image, then the main image, which runs
+  `script/test` and `script/fmt-check` but deliberately not `make check` — that
+  would nest a docker build inside a build step. A bare `docker build .` fails
+  closed on purpose
+- `script/precommit` — run by the git pre-commit hook (our own extension); calls
+  `script/check`
+- `script/install-precommit` — installs the git pre-commit hook (our own
+  extension); `make hooks` shims to it
+
+`make hooks` installs the pre-commit hook that runs `script/precommit`.
+
 ## Rationale
 
 LLM prompts, especially development policies, benefit from version control and a

TODO.md

@@ -0,0 +1,169 @@
+# Workflow
+
+- branch (from `main`)
+- do the work in Next Step
+- move Next Step to the top of Completed Steps
+- move the top item of Future Steps into Next Step
+- commit (`TODO.md` changes in the same commit as the work)
+- merge to `main` if the branch is not protected, otherwise open a PR
+- push
+
+# Status
+
+pre-1.0
+
+# Next Step
+
+Finish the two draft prompt documents in the working tree and commit them:
+prompts/FIXUP_CLEAN.md (currently a near-empty stub) and prompts/FIXUP_REPORT.md
+(a rough draft). Write the missing content, run `make fmt` so they pass
+fmt-check, and commit.
+
+# Completed Steps
+
+- 2026-08-10: Moved every lint run into a container, on the owner's ruling, and
+  made this repo do it rather than merely document it. `script/lint` is now
+  `docker build -f Dockerfile.lint .` and nothing else; the linter is never
+  installed on the host and never invoked there, so a run cannot inherit another
+  checkout's content-keyed result cache, the host-global
+  `$TMPDIR/golangci-lint.lock`, or a host toolchain that differs from the pinned
+  one — the three mechanisms behind a confirmed false green, a string of
+  findings reported against other agents' checkouts, and a container that saw
+  thirteen findings the host missed. Linting runs as a build step, so a
+  successful build is a clean lint, which also works where the docker daemon is
+  remote and bind mounts are impossible. The recursion this creates is resolved
+  by direction rather than by detection: the main `Dockerfile` runs the
+  individual non-lint checks instead of `make check`, and `script/cibuild` runs
+  `script/lint` first, so no build ever nests a build. `Dockerfile.lint` carries
+  the same `CHECK_EPOCH` guard as the main image, with the `ARG` below the
+  dependency layer so only the lint steps re-run — blanket `--no-cache` was
+  rejected because it makes every lint reinstall its dependencies over the
+  network. Two canonical forms were superseded rather than left standing beside
+  the new one, since consuming repos read this document literally: the
+  `script/bootstrap` golangci-lint install (nothing runs a host linter now, so
+  it can only reintroduce skew; the version-enforcement principle stays
+  documented for other pinned host tools) and the per-checkout
+  cache/lock/`.lint-cache` wrapper (its whole subject was making a host run
+  trustworthy). The Go multistage lint stage goes with them: it ran `make lint`,
+  which is now a docker build. `golangci-lint config verify` was kept on
+  measurement, not preference — a bogus config key passes `golangci-lint run`
+  with `0 issues` and fails `config verify`, and every case reproduced
+  byte-identically under `docker run --network none`, so the schema is embedded
+  in the pinned binary and the line costs no network. Verified with two
+  consecutive runs on an unchanged tree both executing the linter, a planted
+  violation caught and reverted, the bare-build guard firing, and the main image
+  building without attempting a nested build.
+- 2026-08-09: Made a golangci-lint result belong to the tree that asked for it.
+  REPO_POLICIES.md now carries the canonical Go `script/lint`, which gives the
+  linter per-checkout `GOLANGCI_LINT_CACHE` and per-checkout `TMPDIR`. The two
+  are separate defects and the second is the one that gets dropped: the result
+  cache is keyed on file content rather than location, so checkouts holding
+  identical files serve each other's findings under the other's path, while the
+  concurrency lock is `$TMPDIR/golangci-lint.lock` — host-global, independent of
+  the cache, and unaffected by isolating it. Moving workers from worktrees to
+  their own clones does not help either half; it only removes the foreign-path
+  artefact that made the defect visible. The lock error is retried rather than
+  surfaced, because it is not a result: it exits non-zero exactly as findings
+  do, and reporting it as findings sends a correct branch back for rework.
+  Detection is on the stderr stream and never on exit status, so a finding
+  quoting the lock message in source cannot be retried away, and exhaustion
+  exits 75 with a VOID message rather than passing or failing quietly.
+  `--allow-serial-runners` (which keeps the guard and queues) covers the
+  same-checkout overlap that `TMPDIR` scoping cannot; `--allow-parallel-runners`
+  is rejected outright. The stdout and stderr capture files are per invocation
+  rather than per checkout, because serialising the linter does not serialise
+  the shell's redirections: two runs in one checkout — the overlap the flag
+  exists to support — would otherwise truncate and read each other's output,
+  which is the same defect one layer above where it was fixed. Both checklists
+  gained the corresponding items, since a half-fix that sets only the cache
+  reads as complete. `GOCACHE` was measured and does not need isolating.
+  Verified with the snippet extracted from the committed document and executed
+  as a consuming repo would adopt it, against paired controls: contamination
+  reproduced on the pre-fix form and absent on the adopted one, retry engaged,
+  exhaustion loud, a genuine finding still reported, and a held host lock
+  failing the pre-fix script while leaving the adopted one untouched.
+- 2026-08-09: Kept in-repo agent scratch out of the Docker build context and out
+  of version control. `.claude/` holds one worktree — an entire additional
+  checkout of the repo — per in-flight agent, and under `COPY . .` all of it was
+  reaching the image: another session's unreviewed, sometimes uncommitted work,
+  inflating the context by a multiple of the repo and invalidating `COPY` for
+  reasons unrelated to the repo's own content. The `.dockerignore` entry is
+  root-anchored, because the directory occurs exactly once where agents run at
+  the repo root and the `**/` form additionally deletes any nested directory of
+  that name — with the residual gap that follows from anchoring (a monorepo
+  running agents in subdirectories still ships `services/api/.claude/`) stated
+  in the canonical `.dockerignore`, the policy and the existing-repo checklist,
+  since consuming repos receive the files rather than the tracker; the
+  `.gitignore` entry is unanchored, because `.gitignore` patterns already match
+  at every depth, and each file is written to its own semantics rather than
+  derived from the other. Also closed the consequence that ships broken
+  silently: excluding `.git` means `git describe` cannot run in any build stage
+  and yields an empty version without erroring, so `script/docker` and
+  `script/cibuild` now compute the version on the host and pass
+  `--build-arg VERSION`, and `REPO_POLICIES.md` states where `VERSION` comes
+  from instead of leaving the reader to fill the gap with `git describe` inside
+  the build. The two Go documents that carry the `GOLDFLAGS` pattern were
+  corrected in the same pass, from `:=` to `?=`, since a `$(shell git describe)`
+  evaluated inside a build stage is exactly the empty version this closes.
+  Verified by enumerating a probe image before, after, and against the
+  `**/`-prefixed form, with a positive control and the `CHECK_EPOCH` cache
+  verification re-run under the changed build context.
+- 2026-08-09: Closed the secret exposure in the canonical `.dockerignore`: a
+  developer's local `.env`, `*.pem` or `*.key` was reaching the Docker build
+  context under `COPY . .`, invisible to every git-based check because
+  `.gitignore` covers it. The patterns are written to `.dockerignore`'s own
+  `moby/patternmatcher` semantics — `**/`-prefixed so they hold at every depth,
+  which also fixes nested `node_modules` — rather than transplanted from
+  `.gitignore`, whose unprefixed form protects only the repository root while
+  reading as solved. Coverage extends past the `.env`/`.pem`/`.key` trio to the
+  `prod.env` convention, `.envrc`, PKCS#12 bundles and extensionless SSH keys,
+  every one of them case-folded with character ranges because matching is
+  case-sensitive and an ALL-CAPS twin per pattern still misses `Server.Key`.
+  `REPO_POLICIES.md` and both repo checklists now state that asymmetry and
+  require verification by enumerating the image rather than by reading the
+  patterns. Verified with a probe image before, against three naive forms
+  (unprefixed, lowercase-only, ALL-CAPS-doubled), and after.
+- 2026-08-09: Made the pinned golangci-lint actually propagate: REPO_POLICIES.md
+  now carries the canonical `script/bootstrap` snippet for Go repos, which
+  installs when the installed version does not match the pin (the old
+  `if missing` guard tested PATH presence only, so pins were inert on any
+  provisioned machine and CI silently disagreed with local) and then re-resolves
+  the binary through `PATH` and fails loudly, naming the shadowing path, when
+  the install did not take effect — the failure mode the naive
+  compare-then-install fix leaves behind while reporting success.
+- 2026-08-09: Fixed the false green in the canonical CI gate: `script/cibuild`
+  and `script/docker` now pass a per-invocation `CHECK_EPOCH` nonce, and the
+  `Dockerfile` (plus the Go multistage template in REPO_POLICIES.md, in both its
+  lint and builder stages) declares `ARG CHECK_EPOCH` with a guard that makes a
+  bare `docker build .` fail closed. Corrected the org-canonical text that
+  asserted a successful build implies all checks pass, across every document
+  carrying it: `REPO_POLICIES.md`, both repo checklists (which still told agents
+  to write the pre-fix `script/cibuild` and ended on an acceptance item the
+  guard makes unsatisfiable), and the Go styleguide.
+- 2026-08-07: Set the canonical `.golangci.yml` to the org-standard v2-schema
+  config already deployed byte-identical across the org's Go repos (settings
+  under `linters.settings` so thresholds like lll/funlen/cyclop/dupl actually
+  apply under golangci-lint v2). Recorded the canonical golangci-lint version
+  (v2.12.2, commit-pinned) in REPO_POLICIES.md.
+- 2026-03-20: Strengthened constructor naming and Params struct rules in the Go
+  styleguide.
+- 2026-03-18: Documented fail-fast Dockerfile lint stage and conditional -v test
+  rerun patterns in REPO_POLICIES.md.
+- 2026-03-11: Added HTTP service hardening policy for 1.0 releases.
+- 2026-03-10: Added policy: no build artifacts in repos.
+- 2026-03-04: Added LLM prose tells reference and copyediting checklist, then
+  several self-applied revision passes.
+- 2026-02-28: Expanded the pre-1.0 schema migration rule; added clawpub
+  reference.
+- 2026-02-23: Added Go style rules (no type-only packages, Stringer for
+  string-based types); template repos section in README.
+- 2026-02-22: Initial policy corpus: REPO_POLICIES.md, code styleguides
+  (general, Go, JS, Python), repo checklists, CI policy, hash pinning, Go HTTP
+  server conventions, repo scaffolding.
+
+# Future Steps
+
+- Finish, format, and commit FIXUP_CLEAN.md and FIXUP_REPORT.md (the Next Step).
+- Commit this TODO.md at the repo root; it is the last missing policy file.
+- Decide the fate of untracked resume.sh: commit it or delete it.
+- Add more prompt templates for common development tasks (from README TODO).

prompts/CODE_STYLEGUIDE_GO.md

@@ -1,6 +1,6 @@
 ---
 title: Code Styleguide — Go
-last_modified: 2026-02-22
+last_modified: 2026-08-10
 ---
 
 1.  Try to hard wrap long lines at 77 characters or less.
@@ -49,7 +49,20 @@ last_modified: 2026-02-22
     ```
 
     ```make
-    VERSION := $(shell git describe --always --dirty)
+    # ?= rather than := because this `$(shell git describe ...)` is only
+    # correct on the host. `.dockerignore` excludes `.git`, so evaluated
+    # inside a build stage it expands to the empty string without failing
+    # and the binary reports no version at all. The version is computed on
+    # the host by `script/docker` / `script/cibuild` and passed with
+    # `--build-arg VERSION=...`. If this repo's Dockerfile compiles by
+    # invoking make (`RUN make build`), `ARG VERSION` in that stage puts the
+    # value in the environment and `?=` defers to it. The canonical Go
+    # template in REPO_POLICIES.md instead runs `go build` directly with
+    # `-ldflags "... -X main.Version=${VERSION}"`, so there this Makefile is
+    # a host-only path — but it is still `?=`, because a repo that later
+    # moves the build behind make must not silently start shipping an empty
+    # version. See the git-describe rule in REPO_POLICIES.md.
+    VERSION ?= $(shell git describe --always --dirty)
     BUILDARCH := $(shell uname -m)
 
     GOLDFLAGS += -X main.Version=$(VERSION)
@@ -98,12 +111,26 @@ last_modified: 2026-02-22
 
 1.  For anything beyond a simple script or tool, or anything that is going to
     run in any sort of "production" anywhere, make sure it passes
-    `golangci-lint`.
+    `golangci-lint`. Run it with `make lint`, which builds `Dockerfile.lint`:
+    the linter runs in a container, always, and is never installed on the host.
+    A `golangci-lint` invoked directly on a shared host reads a result cache
+    keyed on file content rather than location and a host-global lock, so its
+    answer may belong to another checkout entirely.
 
-1.  Write a `Dockerfile` for every repo, even if it only runs the tests and
+1.  Write a `Dockerfile` for every repo, even if it only runs the tests. It runs
-    linting. `docker build .` should always make sure that the code is in an
+    the non-lint checks; linting lives in `Dockerfile.lint` and is run by
-    able-to-be-compiled state, linted, and any tests run. The Docker build
+    `script/cibuild` before the main build, because `script/lint` is itself a
-    should fail if linting doesn't pass.
+    `docker build` and cannot run inside one. So `script/cibuild` is what
+    guarantees the code is in an able-to-be-compiled state, linted, and tested —
+    **a successful `docker build .` on its own does not, because it never
+    lints.** That guarantee holds only because each build passes a
+    per-invocation `CHECK_EPOCH` build arg that busts its check layers out of
+    the Docker cache; without it an unchanged tree serves those layers from
+    cache and the build reports a green it never ran. A bare `docker build .`
+    fails closed by design, on the `[ -n "$CHECK_EPOCH" ]` guard — always go
+    through `script/cibuild`, `script/docker` or `script/lint`. See
+    [Repository Policies](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md)
+    for the canonical form.
 
 1.  Every repo must have a `Makefile`. See
     [Repository Policies](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md)
@@ -136,8 +163,15 @@ last_modified: 2026-02-22
 1.  Provide a .gitignore file that ignores at least `*.log`, `*.out`, and
     `*.test` files, as well as any binaries.
 
-1.  Constructors should be called `New()` whenever possible. `modulename.New()`
+1.  Constructors **must** be called `New()`. `modulename.New()` works great if
-    works great if you name the packages properly.
+    you name the packages properly. If the constructor creates an instance from
+    an existing value or representation, `From<Something>()` (e.g.
+    `FromBytes()`, `FromConfig()`) is also acceptable. If the package contains
+    multiple types and `New()` is ambiguous, `NewThing()` is occasionally
+    acceptable — but prefer restructuring packages so each type gets its own
+    package and a plain `New()`. Do not invent creative constructor names like
+    `Create()`, `Make()`, `Build()`, `Open()` (unless wrapping an OS resource),
+    or `Init()`. If you see a constructor with a non-standard name, rename it.
 
 1.  Don't make packages too big. Break them up.
 
@@ -149,9 +183,15 @@ last_modified: 2026-02-22
 1.  Use descriptive names for modules and filenames. Avoid generic names like
     `server`. `util` is banned.
 
-1.  Constructors should take a Params struct if they need more than 1-2
+1.  Constructors **must** take a `Params` struct (or `ThingParams` when
-    arguments. Positional arguments are an endless source of bugs and should be
+    `NewThing()` is used), even for a single argument. Named fields in a Params
-    avoided whenever possible.
+    struct are always clearer than positional arguments. Positional arguments
+    for constructors are an endless source of bugs — they make call sites
+    unreadable, invite wrong-order errors that the compiler can't catch when
+    types coincide, and force every caller to update when a new field is added.
+    The only exception is when the single argument is stupidly obvious from
+    context — e.g. `featureflag.New(true)` or `thing.NewFromReader(r)`. When in
+    doubt, use a Params struct.
 
 1.  Use `context.Context` for all functions that need it. If you don't need it,
     you can pass `context.Background()`. Anything long-running should get and

prompts/EXISTING_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: Existing Repo Checklist
-last_modified: 2026-02-22
+last_modified: 2026-08-10
 ---
 
 Use this checklist when beginning work in a repo that may not yet conform to our
@@ -24,15 +24,68 @@ with your task.
 - [ ] `LICENSE` file exists and matches the README
 - [ ] `REPO_POLICIES.md` exists and version date is current — fetch from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md`
-- [ ] `.gitignore` is comprehensive (OS, editor, language artifacts, secrets) —
+- [ ] `.gitignore` is comprehensive (OS, editor, agent scratch, language
-      fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore`
+      artifacts, secrets) — fetch from
-      if missing
+      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` if missing.
+      An existing repo usually has a hand-written one that is never re-fetched,
+      so check the entries rather than the file's presence: `.claude/` in
+      particular, unanchored, so agent worktrees cannot be committed by
+      accident. Do not give it a `**/` prefix — that is a `.dockerignore` form
+      and is wrong here.
 - [ ] `.editorconfig` exists — fetch from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`
-- [ ] `Dockerfile` and `.dockerignore` exist; Dockerfile runs `make check` as a
+- [ ] `Dockerfile` and `.dockerignore` exist (fetch `.dockerignore` from
-      build step — fetch `.dockerignore` from
+      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore`);
-      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore`
+      Dockerfile runs the **non-lint** checks as build steps (`script/test`,
-- [ ] Gitea Actions workflow in `.gitea/workflows/` runs `docker build .` on
+      `script/fmt-check`), and every stage containing a check-running `RUN`
+      declares `ARG CHECK_EPOCH` with the `RUN [ -n "$CHECK_EPOCH" ] || exit 1`
+      guard immediately below it — see the `CHECK_EPOCH` rule in
+      `REPO_POLICIES.md`. Without them the check layer is served from cache on
+      an unchanged tree and the build reports a green it never ran.
+- [ ] The `Dockerfile` no longer runs `make check`, and no longer has a `lint`
+      stage or a `COPY --from=lint ... /dev/null` ordering line. This is the
+      item an existing repo most often fails: `script/lint` is now a
+      `docker build`, so both of those nest a docker build inside a build step.
+      Delete the stage; `script/cibuild` running `script/lint` first is what
+      replaces its fail-fast purpose.
+- [ ] `Dockerfile.lint` exists and `script/lint` builds it — see the
+      containerised-lint rule in `REPO_POLICIES.md` for the canonical file. Its
+      base image is pinned by sha256 with a version/date comment, it carries
+      `ARG CHECK_EPOCH` **after** the dependency layer with the guard below it,
+      and it invokes the linter directly rather than through `make lint`.
+- [ ] `.dockerignore` excludes the repo's own host-built artifacts (compiled
+      binaries, test binaries, coverage output), written root-anchored —
+      `/myapp`, never `**/myapp`, which would also match `cmd/myapp/`. An
+      existing repo is where such a binary is likeliest to already be sitting in
+      the build context, invisible to git.
+- [ ] `.dockerignore` excludes `.claude`, root-anchored and with no `**/`
+      prefix. Agent worktrees are entire checkouts of the repo, so they inflate
+      the context by a multiple of it and can copy another session's unreviewed
+      work into an image layer. Confirm by enumerating the image, not by reading
+      the file — `.gitignore` hides these from `git status` too.
+- [ ] **Do agents in this repo run anywhere other than the repo root?** The
+      scratch directory is created in the agent's working directory, so the
+      canonical anchored entry misses `services/api/.claude/` in a monorepo with
+      a per-service agent — it still reaches the build context and the image. An
+      existing repo is where such a layout already exists, so check it here
+      rather than assuming the canonical entry covers you: add anchored entries
+      for the subdirectories that have one (`/services/api/.claude`), or
+      `**/.claude` once you have confirmed no legitimately named nested
+      directory would be caught.
+- [ ] If the repo embeds a version in a binary, that version is computed on the
+      host and passed with `--build-arg VERSION=...` by `script/docker` and
+      `script/cibuild`. No stage calls `git describe`: `.dockerignore` excludes
+      `.git`, so it yields an empty version without failing the build. A
+      tag-derived version additionally needs `fetch-depth: 0` on the CI checkout
+      step, which clones shallow and fetches no tags by default.
+- [ ] Every depth-independent pattern in `.dockerignore` carries a `**/` prefix;
+      only genuinely root-anchored entries such as `.git` are unprefixed, and
+      `.gitignore`'s patterns have not been transplanted unmodified.
+      `.dockerignore` anchors an unprefixed pattern at the context root, so the
+      transplanted form leaves `config/.env` and `certs/server.key` in the build
+      context while reading as solved — see the `.dockerignore` rule in
+      `REPO_POLICIES.md`.
+- [ ] Gitea Actions workflow in `.gitea/workflows/` runs `script/cibuild` on
       push — reference
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitea/workflows/check.yml`
 - [ ] Language-specific config:
@@ -45,12 +98,37 @@ with your task.
     - [ ] Python: `pyproject.toml`
     - [ ] Docs/writing: `.prettierrc`, `.prettierignore` (same URLs as above)
 
-# Makefile
+# Makefile and script/ Entrypoints
 
 - [ ] `Makefile` exists in root — reference
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`
 - [ ] Has targets: `test`, `lint`, `fmt`, `fmt-check`, `check`, `docker`,
       `hooks`
+- [ ] Target implementations live in `script/` (scripts-to-rule-them-all);
+      Makefile targets are thin shims calling them — model scripts at
+      `https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`
+- [ ] `script/precommit` exists and the pre-commit hook (installed by
+      `script/install-precommit`, shimmed by `make hooks`) runs it
+- [ ] README has an **Entrypoints** section documenting the `script/`
+      entrypoints and linking the standard
+- [ ] `script/lint` is the canonical container build and nothing else. No host
+      linter invocation survives anywhere in the repo — grep for the linter's
+      own name in `script/`, the `Makefile` and CI config, not just in
+      `script/lint`. An existing repo is where a second path to the linter is
+      likeliest to exist: a `make lint-fast`, a container-versus-host branch, or
+      a CI step that calls the binary directly.
+- [ ] `script/bootstrap` installs no linter. Delete the golangci-lint install
+      block, its version and ref variables, and its call site: nothing invokes a
+      host linter any more, so all it can still do is put a differently
+      versioned binary where somebody runs it by hand and believes the result.
+- [ ] The per-checkout lint state is gone: no `GOLANGCI_LINT_CACHE` or `TMPDIR`
+      exports, no `--allow-serial-runners`, and `.lint-cache/` removed from
+      `.gitignore` and `.dockerignore`. A container has its own cache and its
+      own lock, so keeping the wrapper leaves two contradictory `script/lint`
+      forms in the fleet.
+- [ ] `script/cibuild` runs `script/lint` before the main `docker build`.
+      Without that line CI never lints at all, because the main image
+      deliberately does not.
 - [ ] `make check` does not modify any files in the repo
 - [ ] `make test` has a 30-second timeout
 - [ ] `make test` runs real tests, not a no-op (at minimum, import/compile
@@ -78,8 +156,28 @@ with your task.
       `internal/`, `static/`, etc.)
 - [ ] Go migrations in `internal/db/migrations/` and embedded in binary
 
+# HTTP Service Hardening (if targeting 1.0 and the repo is an HTTP/web service)
+
+- [ ] Security headers set on all responses (HSTS, CSP, X-Frame-Options,
+      X-Content-Type-Options, Referrer-Policy, Permissions-Policy)
+- [ ] Request body size limits enforced on all endpoints
+- [ ] Read/write/idle timeouts configured on the HTTP server (slowloris defense)
+- [ ] Per-handler execution time limits in place
+- [ ] Password-based auth endpoints are rate-limited
+- [ ] CSRF tokens on all state-mutating HTML forms
+- [ ] Passwords hashed with bcrypt, scrypt, or argon2
+- [ ] Session cookies use HttpOnly, Secure, and SameSite attributes
+- [ ] True client IP correctly detected behind reverse proxy (trusted proxy
+      allowlist configured)
+- [ ] CORS restricted to explicit origin allowlist for authenticated endpoints
+- [ ] Error responses do not leak stack traces, SQL queries, or internal paths
+
 # Final
 
 - [ ] `make check` passes
-- [ ] `docker build` succeeds
+- [ ] `make lint` runs twice on an unchanged tree with the lint layer `DONE`
+      both times, never `CACHED` and never sub-second
+- [ ] `script/cibuild` succeeds and runs both container builds (a bare
+      `docker build .` or `docker build -f Dockerfile.lint .` fails closed by
+      design, on the `CHECK_EPOCH` guard)
 - [ ] Commit and merge fixes before starting your actual task

prompts/GO_HTTP_SERVER_CONVENTIONS.md

@@ -1,6 +1,6 @@
 ---
 title: Go HTTP Server Conventions
-last_modified: 2026-02-22
+last_modified: 2026-08-09
 ---
 
 This document defines the architectural patterns, design decisions, and
@@ -991,7 +991,14 @@ func main() {
 Use ldflags to inject version information at build time:
 
 ```makefile
-VERSION := $(shell git describe --tags --always)
+# ?= rather than := because this `$(shell git describe ...)` is only correct
+# on the host: `.dockerignore` excludes `.git`, so evaluated inside a build
+# stage it expands to the empty string without failing and the binary reports
+# no version. The version is computed on the host by `script/docker` /
+# `script/cibuild` and passed with `--build-arg VERSION=...`; where the build
+# stage invokes make, `ARG VERSION` puts it in the environment and `?=` defers
+# to it. See the git-describe rule in REPO_POLICIES.md.
+VERSION ?= $(shell git describe --tags --always)
 BUILDARCH := $(shell go env GOARCH)
 
 build:

prompts/LLM_PROSE_TELLS.md

@@ -1,7 +1,6 @@
 # LLM Prose Tells
 
-Human writers occasionally use every pattern in this document. The reason they
+A catalog of patterns found in LLM-generated prose.
-work as tells is that LLM output packs fifteen of them into a paragraph.
 
 ---
 
@@ -14,17 +13,11 @@ A negation followed by an em-dash and a reframe.
 > "It's not just a tool—it's a paradigm shift." "This isn't about
 > technology—it's about trust."
 
-The most recognizable LLM construction. Models produce this at roughly 10 to 50x
-the rate of human writers. Four of them in one essay and you know what you're
-reading.
-
 ### Em-Dash Overuse Generally
 
-Even outside the "not X but Y" pivot, models use em-dashes at far higher rates
+Even outside the "not X but Y" pivot, models substitute em-dashes for commas,
-than human writers. They substitute em-dashes for commas, semicolons,
+semicolons, parentheses, colons, and periods. The em-dash can replace any other
-parentheses, colons, and periods. A human writer might use one or two in a
+punctuation mark, so models default to it.
-piece. Models scatter them everywhere because the em-dash can stand in for any
-other punctuation mark. More than two or three per page is a signal.
 
 ### The Colon Elaboration
 
@@ -32,33 +25,25 @@ A short declarative clause, then a colon, then a longer explanation.
 
 > "The answer is simple: we need to rethink our approach from the ground up."
 
-Models reach for this in every other paragraph. The construction is perfectly
-normal. The frequency gives it away.
-
 ### The Triple Construction
 
 > "It's fast, it's scalable, and it's open source."
 
 Three parallel items in a list, usually escalating. Always exactly three (rarely
-two, never four) with strict grammatical parallelism that human writers rarely
+two, never four) with strict grammatical parallelism.
-bother maintaining.
 
 ### The Staccato Burst
 
 > "This matters. It always has. And it always will." "The data is clear. The
 > trend is undeniable. The conclusion is obvious."
 
-Runs of very short sentences at the same cadence. Human writers use a short
+Runs of very short sentences at the same cadence and matching length.
-sentence for emphasis occasionally, but stacking three or four of them in a row
-at matching length creates a mechanical regularity.
 
 ### The Two-Clause Compound Sentence
 
-Possibly the most pervasive tell, and easy to miss because each individual
+An independent clause, a comma, a conjunction ("and," "but," "which,"
-instance looks like normal English. The model produces sentence after sentence
+"because"), and a second independent clause of similar length. Every sentence
-where an independent clause is followed by a comma, a conjunction ("and," "but,"
+becomes two balanced halves.
-"which," "because"), and a second independent clause of similar length. Every
-sentence becomes two balanced halves.
 
 > "The construction itself is perfectly normal, which is why the frequency is
 > what gives it away." "They contain zero information, and the actual point
@@ -68,49 +53,44 @@ sentence becomes two balanced halves.
 
 Human prose has sentences with one clause, sentences with three, sentences that
 start with a subordinate clause before reaching the main one, sentences that
-embed their complexity in the middle. When every sentence on the page has that
+embed their complexity in the middle.
-same two-part structure, the rhythm becomes monotonous.
 
 ### Uniform Sentences Per Paragraph
 
-Model-generated paragraphs contain between three and five sentences. This count
+Model-generated paragraphs contain between three and five sentences, a count
-holds steady across a piece. If the first paragraph has four sentences, every
+that holds steady across a piece. If the first paragraph has four sentences,
-subsequent paragraph will too. Human writers are much more varied (a single
+every subsequent paragraph will too.
-sentence followed by one that runs eight or nine) because they follow the shape
-of an idea.
 
 ### The Dramatic Fragment
 
-Sentence fragments used as standalone paragraphs for emphasis, like "Full stop."
+Sentence fragments used as standalone paragraphs for emphasis.
-or "Let that sink in." on their own line. Using one in an essay is a reasonable
+
-stylistic choice, but models drop them in once per section or more.
+> "Full stop." "Let that sink in."
 
 ### The Pivot Paragraph
 
 > "But here's where it gets interesting." "Which raises an uncomfortable truth."
 
-One-sentence paragraphs that exist only to transition between ideas. They
+One-sentence paragraphs that exist only to transition between ideas, containing
-contain zero information. The actual point is always in the next paragraph.
+zero information. The actual point is always in the next paragraph.
-Delete every one of these and the piece reads better.
 
 ### The Parenthetical Qualifier
 
 > "This is, of course, a simplification." "There are, to be fair, exceptions."
 
-Parenthetical asides inserted to look thoughtful. The qualifier never changes
+Parenthetical asides inserted to perform nuance without changing the argument.
-the argument that follows it. Its purpose is to perform nuance.
 
 ### The Unnecessary Contrast
 
-Models append a contrasting clause to statements that don't need one, tacking on
+A contrasting clause appended to a statement that doesn't need one, using
 "whereas," "as opposed to," "unlike," or "except that."
 
 > "Models write one register above where a human would, whereas human writers
 > tend to match register to context."
 
-The first clause already makes the point. The contrasting clause restates it
+The contrasting clause restates what the first clause already said. If you
-from the other direction. If you delete the "whereas" clause and the sentence
+delete the "whereas" clause and the sentence still says everything it needs to,
-still says everything it needs to, the contrast was filler.
+the contrast was filler.
 
 ### Unnecessary Elaboration
 
@@ -120,19 +100,15 @@ Models keep going after the sentence has already made its point.
 > LLM output will use fifteen of them per paragraph, consistently, throughout
 > the entire piece."
 
-This sentence could end at "paragraph." The words after it just repeat what "per
+This sentence could end at "paragraph." The words after it repeat what "per
-paragraph" already means. Models do this because they're optimizing for clarity
+paragraph" already means. If you can cut the last third of a sentence without
-at the expense of concision. The result is prose that feels padded. If you can
+losing meaning, the last third shouldn't be there.
-cut the last third of a sentence without losing any meaning, the last third
-shouldn't be there.
 
 ### The Question-Then-Answer
 
 > "So what does this mean for the average user? It means everything."
 
-A rhetorical question immediately followed by its own answer. Models do this two
+A rhetorical question immediately followed by its own answer.
-or three times per piece because it fakes forward momentum. A human writer might
-do it once.
 
 ---
 
@@ -140,43 +116,38 @@ do it once.
 
 ### Overused Intensifiers
 
-The following words appear at dramatically elevated rates in model output:
+"Crucial," "vital," "robust," "comprehensive," "fundamental," "arguably,"
-"crucial," "vital," "robust," "comprehensive," "fundamental," "arguably,"
 "straightforward," "noteworthy," "realm," "landscape," "leverage" (as a verb),
-"delve," "tapestry," "multifaceted," "nuanced" (which models apply to their own
+"delve," "tapestry," "multifaceted," "nuanced" (applied to the model's own
-analysis with startling regularity), "pivotal," "unprecedented" (frequently
+analysis), "pivotal," "unprecedented" (applied to things with plenty of
-applied to things with plenty of precedent), "navigate," "foster,"
+precedent), "navigate," "foster," "underscores," "resonates," "embark,"
-"underscores," "resonates," "embark," "streamline," and "spearhead." Three or
+"streamline," "spearhead."
-more on the same page is a strong signal.
 
 ### Elevated Register Drift
 
-Models write one register above where a human would. "Use" becomes "utilize."
+Models write one register above where a human would, replacing "use" with
-"Start" becomes "commence." "Help" becomes "facilitate." "Show" becomes
+"utilize," "start" with "commence," "help" with "facilitate," "show" with
-"demonstrate." "Try" becomes "endeavor." "Change" becomes "transform." "Make"
+"demonstrate," "try" with "endeavor," "change" with "transform," and "make" with
-becomes "craft." The tendency holds regardless of topic or audience.
+"craft."
 
 ### Filler Adverbs
 
 "Importantly," "essentially," "fundamentally," "ultimately," "inherently,"
-"particularly," "increasingly." Dropped in to signal that something matters,
+"particularly," "increasingly." Dropped in to signal that something matters when
-which is unnecessary when the writing itself makes the importance clear.
+the writing itself should make the importance clear.
 
 ### The "Almost" Hedge
 
-Models rarely commit to an unqualified statement. Instead of saying a pattern
+Instead of saying a pattern "always" or "never" does something, models write
-"always" or "never" does something, they write "almost always," "almost never,"
+"almost always," "almost never," "almost certainly," "almost exclusively." A
-"almost certainly," "almost exclusively." The word "almost" shows up at high
+micro-hedge, less obvious than the full hedge stack.
-density in model-generated analytical prose. It's a micro-hedge, diagnostic in
-volume.
 
 ### "In an era of..."
 
 > "In an era of rapid technological change..."
 
-A model habit as an essay opener. The model uses it to stall while it figures
+Used to open an essay. The model is stalling while it figures out what the
-out what the actual argument is. Human writers don't begin a piece by zooming
+actual argument is.
-out to the civilizational scale.
 
 ---
 
@@ -187,23 +158,20 @@ out to the civilizational scale.
 > "While X has its drawbacks, it also offers significant benefits."
 
 Every argument followed by a concession, every criticism softened. A direct
-artifact of RLHF training, which penalizes strong stances. Models reflexively
+artifact of RLHF training, which penalizes strong stances.
-both-sides everything.
 
 ### The Throat-Clearing Opener
 
 > "In today's rapidly evolving digital landscape, the question of data privacy
 > has never been more important."
 
-The first paragraph of most model-generated essays adds no information. Delete
+The first paragraph adds no information. Delete it and the piece improves.
-it and the piece improves.
 
 ### The False Conclusion
 
 > "At the end of the day, what matters most is..." "Moving forward, we must..."
 
 The high school "In conclusion,..." dressed up for a professional audience.
-Signals that the model is wrapping up without actually landing on anything.
 
 ### The Sycophantic Frame
 
@@ -224,15 +192,13 @@ the key considerations:"
 > cases it can potentially offer significant benefits."
 
 Five hedges in one sentence ("worth noting," "while," "may not be," "in many
-cases," "can potentially"), communicating nothing. The model would rather be
+cases," "can potentially"), communicating nothing.
-vague than risk being wrong about anything.
 
 ### The Empathy Performance
 
 > "This can be a deeply challenging experience." "Your feelings are valid."
 
-Generic emotional language that could apply equally to a bad day at work or a
+Generic emotional language that could apply to anything.
-natural disaster.
 
 ---
 
@@ -240,33 +206,28 @@ natural disaster.
 
 ### Symmetrical Section Length
 
-If the first section of a model-generated essay runs about 150 words, every
+If the first section runs about 150 words, every subsequent section will fall
-subsequent section will fall between 130 and 170. Human writing is much more
+between 130 and 170.
-uneven.
 
 ### The Five-Paragraph Prison
 
 Model essays follow a rigid introduction-body-conclusion arc even when nobody
 asked for one. The introduction previews the argument, the body presents 3 to 5
-points, and then the conclusion restates the thesis.
+points, the conclusion restates the thesis.
 
 ### Connector Addiction
 
-Look at the first word of each paragraph in model output. You'll find an
+The first word of each paragraph forms an unbroken chain of transition words:
-unbroken chain of transition words: "However," "Furthermore," "Moreover,"
+"However," "Furthermore," "Moreover," "Additionally," "That said," "To that
-"Additionally," "That said," "To that end," "With that in mind," "Building on
+end," "With that in mind," "Building on this."
-this." Human prose doesn't do this.
 
 ### Absence of Mess
 
 Model prose doesn't contradict itself mid-paragraph and then catch the
-contradiction. It doesn't go on a tangent and have to walk it back, use an
+contradiction, go on a tangent and have to walk it back, use an obscure idiom
-obscure idiom without explaining it, make a joke that risks falling flat, leave
+without explaining it, make a joke that risks falling flat, leave a thought
-a thought genuinely unfinished, or keep a sentence the writer liked the sound of
+genuinely unfinished, or keep a sentence the writer liked the sound of even
-even though it doesn't quite work.
+though it doesn't quite work.
-
-Human writing does all of those things regularly. That total absence of rough
-patches and false starts is one of the strongest signals.
 
 ---
 
@@ -276,42 +237,27 @@ patches and false starts is one of the strongest signals.
 
 > "This has implications far beyond just the tech industry."
 
-Zooming out to claim broader significance without substantiating it. The model
+Zooming out to claim broader significance without substantiating it.
-has learned that essays are supposed to gesture at big ideas, so it gestures.
 
 ### "It's important to note that..."
 
 This phrase and its variants ("it's worth noting," "it bears mentioning," "it
-should be noted") appear at absurd rates in model output. They function as
+should be noted") function as verbal tics before a qualification the model
-verbal tics before a qualification the model believes someone expects.
+believes someone expects.
 
 ### The Metaphor Crutch
 
-Models rely on a small, predictable set of metaphors ("double-edged sword," "tip
+Models rely on a small, predictable set of metaphors: "double-edged sword," "tip
 of the iceberg," "north star," "building blocks," "elephant in the room,"
-"perfect storm," "game-changer") and reach for them with unusual regularity
+"perfect storm," "game-changer."
-across every topic.
-
----
-
-## How to Actually Spot It
-
-No single pattern on this list proves anything by itself. Humans use em-dashes.
-Humans write "crucial." Humans ask rhetorical questions.
-
-What gives it away is how many of these show up at once. Model output will hit
-10 to 20 of these patterns per page. Human writing might trigger 2 or 3,
-distributed unevenly. When every paragraph on the page reads like it came from
-the same careful, balanced, slightly formal, structurally predictable process,
-it was generated by one.
 
 ---
 
 ## Copyediting Checklist: Removing LLM Tells
 
 Follow this checklist when editing any document to remove machine-generated
-patterns. Go through the entire list for every piece. Do at least two full
+patterns. Do at least two full passes, because fixing one pattern often
-passes, because fixing one pattern often introduces another.
+introduces another.
 
 ### Pass 1: Word-Level Cleanup
 
@@ -325,8 +271,7 @@ passes, because fixing one pattern often introduces another.
 
 2. Search for filler adverbs ("importantly," "essentially," "fundamentally,"
    "ultimately," "inherently," "particularly," "increasingly") and delete every
-   instance where the sentence still makes sense without it. That will be most
+   instance where the sentence still makes sense without it.
-   of them.
 
 3. Look for elevated register drift ("utilize," "commence," "facilitate,"
    "demonstrate," "endeavor," "transform," "craft" and similar) and replace with
@@ -334,7 +279,6 @@ passes, because fixing one pattern often introduces another.
 
 4. Search for "it's important to note," "it's worth noting," "it bears
    mentioning," and "it should be noted" and delete the phrase in every case.
-   The sentence that follows always stands on its own.
 
 5. Search for the stock metaphors ("double-edged sword," "tip of the iceberg,"
    "north star," "building blocks," "elephant in the room," "perfect storm,"
@@ -343,105 +287,114 @@ passes, because fixing one pattern often introduces another.
 
 6. Search for "almost" used as a hedge ("almost always," "almost never," "almost
    certainly," "almost exclusively") and decide in each case whether to commit
-   to the unqualified claim or to drop the sentence entirely. If the claim needs
+   to the unqualified claim or to drop the sentence entirely.
-   "almost" to be true, it might not be worth making.
 
 7. Search for em-dashes and replace each one with the punctuation mark that
    would normally be used in that position (comma, semicolon, colon, period, or
    parentheses). If you can't identify which one it should be, the sentence
    needs to be restructured.
 
+8. Remove redundant adjectives. For each adjective, ask whether the sentence
+   changes meaning without it. "A single paragraph" means the same as "a
+   paragraph." "An entire essay" means the same as "an essay." If the adjective
+   doesn't change the meaning, cut it.
+
+9. Remove unnecessary trailing clauses. Read the end of each sentence and ask
+   whether the last clause restates what the sentence already said. If so, end
+   the sentence earlier.
+
 ### Pass 2: Sentence-Level Restructuring
 
-8. Find every em-dash pivot ("not X...but Y," "not just X...Y," "more than
+10. Find every em-dash pivot ("not X—but Y," "not just X—Y," "more than X—Y")
-   X...Y") and rewrite it as two separate clauses or a single sentence that
+    and rewrite it as two separate clauses or a single sentence that makes the
-   makes the point without the negation-then-correction structure.
+    point without the negation-then-correction structure.
 
-9. Find every colon elaboration and check whether it's doing real work. If the
+11. Find every colon elaboration and check whether it's doing real work. If the
-   clause before the colon could be deleted without losing meaning, rewrite the
+    clause before the colon could be deleted without losing meaning, rewrite the
-   sentence to start with the substance that comes after the colon.
+    sentence to start with the substance that comes after the colon.
 
-10. Find every triple construction (three parallel items in a row) and either
+12. Find every triple construction (three parallel items in a row) and either
     reduce it to two, expand it to four or more, or break the parallelism so the
     items don't share the same grammatical structure.
 
-11. Find every staccato burst (three or more short sentences in a row at similar
+13. Find every staccato burst (three or more short sentences in a row at similar
     length) and combine at least two of them into a longer sentence, or vary
     their lengths so they don't land at the same cadence.
 
-12. Find every unnecessary contrast ("whereas," "as opposed to," "unlike," "as
+14. Find every unnecessary contrast ("whereas," "as opposed to," "unlike," "as
     compared to," "except that") and check whether the contrasting clause adds
     information not already obvious from the main clause. If the sentence says
     the same thing twice from two directions, delete the contrast.
 
-13. Check for the two-clause compound sentence pattern. If most sentences in a
+15. Check for the two-clause compound sentence pattern. If most sentences in a
-    passage follow the "\[clause\], \[conjunction\] \[clause\]" structure,
+    passage follow the "\[clause\], \[conjunction\] \[clause\]" structure, first
-    rewrite some of them. Break a few into two sentences. Start some with a
+    try removing the conjunction and second clause entirely, since it's often
-    subordinate clause. Embed a relative clause in the middle of one instead of
+    redundant. If the second clause does carry meaning, break it into its own
-    appending it at the end. The goal is variety in sentence shape, not just
+    sentence, start the sentence with a subordinate clause, or embed a relative
-    sentence length.
+    clause in the middle instead of appending it at the end.
 
-14. Find every rhetorical question that is immediately followed by its own
+16. Find every rhetorical question that is immediately followed by its own
     answer and rewrite the passage as a direct statement.
 
-15. Find every sentence fragment being used as its own paragraph and either
+17. Find every sentence fragment being used as its own paragraph and either
-    delete it or expand it into a complete sentence that adds actual
+    delete it or expand it into a complete sentence that adds information.
-    information.
 
-16. Check for unnecessary elaboration. Read every clause, phrase, and adjective
+18. Check for unnecessary elaboration. Read every clause, phrase, and adjective
-    in each sentence and ask whether the sentence loses meaning without it. This
+    in each sentence and ask whether the sentence loses meaning without it. If
-    includes trailing clauses that restate what the sentence already said,
+    you can cut it and the sentence still says the same thing, cut it.
-    redundant modifiers ("a single paragraph" when "a paragraph" works),
-    secondary clauses that add nothing ("which is why this matters"), and any
-    words whose removal doesn't change the meaning. If you can cut it and the
-    sentence still says the same thing, cut it.
 
-17. Find every pivot paragraph ("But here's where it gets interesting." and
+19. Check each pair of adjacent sentences to see if they can be merged into one
-    similar) and delete it. The paragraph after it always contains the actual
+    sentence cleanly. If a sentence just continues the thought of the previous
-    point.
+    one, combine them using a participle, a relative clause, or by folding the
+    second into the first. Don't merge if the result would create a two-clause
+    compound.
+
+20. Find every pivot paragraph ("But here's where it gets interesting." and
+    similar) and delete it.
 
 ### Pass 3: Paragraph and Section-Level Review
 
-18. Check paragraph lengths across the piece and verify they actually vary. If
+21. Review the last sentence of each paragraph. If it restates the point the
+    paragraph already made, delete it.
+
+22. Check paragraph lengths across the piece and verify they actually vary. If
     most paragraphs have between three and five sentences, rewrite some to be
     one or two sentences and let others run to six or seven.
 
-19. Check section lengths for suspicious uniformity. If every section is roughly
+23. Check section lengths for suspicious uniformity. If every section is roughly
     the same word count, combine some shorter ones or split a longer one
     unevenly.
 
-20. Check the first word of every paragraph for chains of connectors ("However,"
+24. Check the first word of every paragraph for chains of connectors ("However,"
     "Furthermore," "Moreover," "Additionally," "That said"). If more than two
     transition words start consecutive paragraphs, rewrite those openings to
     start with their subject.
 
-21. Check whether every argument is followed by a concession or qualifier. If
+25. Check whether every argument is followed by a concession or qualifier. If
     the piece both-sides every point, pick a side on at least some of them and
     cut the hedging.
 
-22. Read the first paragraph and ask whether deleting it would improve the
+26. Read the first paragraph and ask whether deleting it would improve the
     piece. If it's scene-setting that previews the argument, delete it and start
     with paragraph two.
 
-23. Read the last paragraph and check whether it restates the thesis or uses a
+27. Read the last paragraph and check whether it restates the thesis or uses a
     phrase like "at the end of the day" or "moving forward." If so, either
     delete it or rewrite it to say something the piece hasn't said yet.
 
 ### Pass 4: Overall Texture
 
-24. Read the piece aloud and listen for passages that sound too smooth, too
+28. Read the piece aloud and listen for passages that sound too smooth, too
     even, or too predictable. Human prose has rough patches. If there aren't
     any, the piece still reads as machine output.
 
-25. Check that the piece contains at least a few constructions that feel
+29. Check that the piece contains at least a few constructions that feel
     idiosyncratic: a sentence with unusual word order, a parenthetical that goes
     on a bit long, an aside only loosely connected to the main point, a word
-    choice that's specific and unexpected. If every sentence is clean and
+    choice that's specific and unexpected.
-    correct and unremarkable, it will still read as generated.
 
-26. Verify that you haven't introduced new patterns while fixing the original
+30. Verify that you haven't introduced new patterns while fixing the original
-    ones. This happens constantly. Run the entire checklist again from the top
+    ones. Run the entire checklist again from the top on the revised version.
-    on the revised version.
 
 ---
 
@@ -488,16 +441,9 @@ roughly like this:
 >
 > **model:** _(rewrites entire document without em-dashes while describing
 > em-dash overuse)_
->
-> **human:** now run the checklist methodically on each paragraph
->
-> **model:** _(finds staccato burst in the section about triple constructions, a
-> triple in the section about absence of mess, two-clause compounds everywhere,
-> and "almost" hedges in its own prose about em-dash overuse)_
 
 The human compared this process to the deleted scene in Terminator 2 where John
 Connor switches the T-800's CPU to learning mode. The model compared it to a
 physician trying to heal itself. Both are accurate.
 
-This document has been through eight editing passes and it still has tells in
+This document has been through ten editing passes and it still has tells in it.
-it.

prompts/NEW_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: New Repo Checklist
-last_modified: 2026-02-22
+last_modified: 2026-08-10
 ---
 
 Use this checklist when creating a new repository from scratch. Follow the steps
@@ -35,7 +35,11 @@ Template files can be fetched from:
 
 - [ ] `.gitignore` — fetch from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore`, extend for
-      language-specific artifacts
+      language-specific artifacts. Extensions are written to `.gitignore`'s own
+      semantics, where an unanchored pattern already matches at every depth:
+      never add a `**/` prefix here, which is a `.dockerignore` form. The
+      canonical file already carries `.claude/` so agent worktrees cannot be
+      committed by accident.
 - [ ] `.editorconfig` — fetch from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`
 - [ ] `Makefile` — fetch from
@@ -52,12 +56,46 @@ Template files can be fetched from:
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md`
 - [ ] `Dockerfile` and `.dockerignore` — fetch `.dockerignore` from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore`
-    - All Dockerfiles must run `make check` as a build step
+    - Extend `.dockerignore` with the repo's own host-built artifacts, giving
+      every depth-independent pattern a `**/` prefix — but write a repo-root
+      binary anchored, `/myapp` and never `**/myapp`, which would also match
+      `cmd/myapp/` and delete the package directory. Do not transplant
+      `.gitignore`'s patterns: `.dockerignore` anchors an unprefixed pattern at
+      the context root, so the copied form leaves `config/.env` in the build
+      context while reading as solved. See the `.dockerignore` rule in
+      `REPO_POLICIES.md`. The canonical file's `.claude` entry is anchored for
+      the same reason as a repo-root binary; leave it that way, but note it only
+      covers agents running at the repo root — if this repo will run them in
+      subdirectories, `services/api/.claude/` is not excluded and needs its own
+      anchored entry.
+    - If the image embeds a version in a binary, the version is computed on the
+      host and passed with `--build-arg VERSION=...`. `ARG VERSION=dev` is
+      declared in the stage that compiles, and **no stage calls `git describe`**
+      — `.dockerignore` excludes `.git`, so it yields an empty version without
+      failing the build.
+    - The `Dockerfile` runs the **non-lint** checks as build steps —
+      `script/test` and `script/fmt-check`, never `make check`. `script/lint` is
+      a `docker build` of `Dockerfile.lint`, so `make check` here nests a build
+      inside a build step, where there is no daemon. Put a comment above those
+      `RUN` lines saying so. Every stage containing a check-running `RUN` must
+      declare `ARG CHECK_EPOCH` with the `RUN [ -n "$CHECK_EPOCH" ] || exit 1`
+      guard immediately below it — see the `CHECK_EPOCH` rule in
+      `REPO_POLICIES.md`. Without them the check layer is served from cache on
+      an unchanged tree and the build reports a green it never ran.
     - Server: also builds and runs the application
-    - Non-server: brings up dev environment and runs `make check`
+    - Non-server: brings up dev environment and runs those checks
     - Image pinned by sha256 hash with version/date comment
+- [ ] `Dockerfile.lint` — the lint-only image that `script/lint` builds. Same
+      `ARG CHECK_EPOCH` + guard + expanded-value discipline as above, with the
+      `ARG` placed **after** the dependency layer so only the lint steps re-run.
+      Base image pinned by sha256 with a version/date comment. Go repos use
+      `golangci/golangci-lint` and run both `golangci-lint config verify` and
+      `golangci-lint run`; other repos use the same pattern around their own
+      linter (eslint, ruff, prettier). Copy the canonical file from
+      `REPO_POLICIES.md`. The linter is invoked directly there, never via
+      `make lint`, which would recurse.
 - [ ] Gitea Actions workflow at `.gitea/workflows/check.yml` that runs
-      `docker build .` on push — reference
+      `script/cibuild` on push — reference
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitea/workflows/check.yml`
 - [ ] Language-specific:
     - [ ] Go: `go mod init sneak.berlin/go/<name>`, `.golangci.yml` (fetch from
@@ -65,20 +103,81 @@ Template files can be fetched from:
     - [ ] JS: `yarn init`, `yarn add --dev prettier`
     - [ ] Python: `pyproject.toml`
 
-## Configure Makefile
+## Configure script/ Entrypoints and Makefile
 
-- [ ] `make test` — runs real tests, not a no-op (30-second timeout)
+Implementations live in `script/` (scripts-to-rule-them-all); Makefile targets
-- [ ] `make lint` — runs linter
+are thin shims calling them. Model scripts:
-- [ ] `make fmt` — formats code (writes)
+`https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`
-- [ ] `make fmt-check` — checks formatting (read-only)
+
-- [ ] `make check` — prereqs: `test`, `lint`, `fmt-check`; must not modify files
+- [ ] scripts are POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they run on
-- [ ] `make docker` — builds Docker image
+      alpine images without bash
-- [ ] `make hooks` — installs pre-commit hook
+- [ ] `script/bootstrap` / `make bootstrap` — installs all dependencies,
+      idempotently, assuming nothing (pkg manager detection nix/apt/brew/apk;
+      node used if present, else pinned version via nvm from a hash-verified
+      archive; pinned yarn via corepack); Dockerfile runs it instead of inline
+      installs
+- [ ] `script/setup` / `make setup` — readies a fresh clone: runs `bootstrap`,
+      then `install-precommit`, plus repo-specific init
+- [ ] `script/test` / `make test` — runs real tests, not a no-op (30-second
+      timeout)
+- [ ] `script/lint` / `make lint` — builds `Dockerfile.lint` and nothing else:
+      `epoch="$(date +%s%N)$$"` on its own line, then
+      `docker build --build-arg CHECK_EPOCH="$epoch" -f Dockerfile.lint .`. The
+      linter is never installed on the host and never invoked there. Copy the
+      canonical script from `REPO_POLICIES.md`; it is byte-identical across
+      repos. Without the nonce this script exits 0 on an unchanged tree having
+      linted nothing.
+- [ ] `script/fmt` / `make fmt` — formats code (writes)
+- [ ] `script/fmt-check` / `make fmt-check` — checks formatting (read-only)
+- [ ] `script/check` / `make check` — runs `test`, `lint`, `fmt-check`; must not
+      modify files. It needs a docker daemon, because `script/lint` is a
+      container build, and it must never be called from inside a build stage
+- [ ] `script/projectname` — outputs the project name (used by `script/docker`
+      for the image tag)
+- [ ] `script/docker` / `make docker` — builds Docker image, tagged via
+      `script/projectname` (byte-identical across repos); carries the same three
+      version lines as `script/cibuild` below, and passes
+      `--build-arg CHECK_EPOCH="$epoch"` and `--build-arg VERSION="$version"`
+- [ ] `script/cibuild` — cd to repo root, run `script/lint` **first** for
+      fail-fast feedback, then, each on its own line:
+
+    ```sh
+    epoch="$(date +%s%N)$$"
+    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    [ -n "$version" ] || version="unknown"
+    docker build \
+        --build-arg CHECK_EPOCH="$epoch" \
+        --build-arg VERSION="$version" \
+        .
+    ```
+
+    (what CI runs). The `script/lint` call is not optional: the main image does
+    not lint, so without it CI never lints. Both build args are mandatory, and
+    both assignments must be on their own line: a failing command substitution
+    inside an argument does not trip `set -e`, so the inline form degrades
+    silently to an empty constant. The `[ -n "$version" ]` line is a live check
+    that fires on an export with no `.git` and on a repo with no commits — keep
+    it, and do not collapse it into `|| echo unknown`, which makes it
+    unreachable. See the `CHECK_EPOCH` and git-describe rules in
+    `REPO_POLICIES.md` for why each element is load-bearing. A bare
+    `docker build .` fails closed by design, and so does a bare
+    `docker build -f Dockerfile.lint .`.
+
+- [ ] `script/precommit` — called by the pre-commit hook; runs `script/check`
+- [ ] `script/install-precommit` — installs the pre-commit hook that runs
+      `script/precommit`
+- [ ] `make hooks` — shims to `script/install-precommit`
+- [ ] README **Entrypoints** section documents the scripts and links the
+      standard
 
 # 4. Verify
 
 - [ ] `make check` passes
+- [ ] `make lint` demonstrably runs the linter rather than returning a cached
+      build: run it twice on an unchanged tree and confirm the lint layer says
+      `DONE`, never `CACHED`, both times
 - [ ] `make docker` succeeds
+- [ ] `script/cibuild` succeeds and runs both container builds
 - [ ] No secrets in repo
 - [ ] No mutable image/package references
 - [ ] No unnecessary files in repo root

prompts/REPO_POLICIES.md

@@ -1,6 +1,6 @@
 ---
 title: Repository Policies
-last_modified: 2026-02-22
+last_modified: 2026-08-10
 ---
 
 This document covers repository structure, tooling, and workflow standards. Code
@@ -34,10 +34,51 @@ style conventions are in separate documents:
   every file before committing. There are zero exceptions to this rule.
 
 - Every repo with software must have a root `Makefile` with these targets:
-  `make test`, `make lint`, `make fmt` (writes), `make fmt-check` (read-only),
+  `make bootstrap`, `make setup`, `make test`, `make lint`, `make fmt` (writes),
-  `make check` (prereqs: `test`, `lint`, `fmt-check`), `make docker`, and
+  `make fmt-check` (read-only), `make check` (runs `test`, `lint`, `fmt-check`),
-  `make hooks` (installs pre-commit hook). A model Makefile is at
+  `make docker`, and `make hooks` (installs pre-commit hook). A model Makefile
-  `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`.
+  is at `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`.
+
+- Repos follow the
+  [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+  pattern: the implementation of each Makefile target lives in an executable
+  script in `script/` (`script/bootstrap`, `script/setup`, `script/test`,
+  `script/lint`, `script/fmt`, `script/fmt-check`, `script/check`,
+  `script/docker`), and the Makefile targets are thin shims that call them. The
+  scripts must be POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they run in
+  minimal containers (e.g. alpine images have no bash); locate the repo root
+  with `$(cd "$(dirname "$0")/.." && pwd -P)` and `cd` there before acting. From
+  the standard's canonical set we use `bootstrap`, `setup` (make the repo ready
+  for development after a fresh clone: runs `bootstrap`, then
+  `install-precommit`, plus any repo-specific initialization), `test`, and
+  `cibuild`. `script/bootstrap` installs all dependencies idempotently and
+  assumes nothing is present: base tools come from nix, apt, brew, or apk
+  (detected in that order; apt runs noninteractive). For node it uses the
+  installed node if present; otherwise it installs a PINNED node version via
+  nvm, first installing nvm itself if missing — from a hash-verified GitHub
+  release archive (never `curl | sh`), with bash installed as an explicit
+  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, runs `script/lint` first for fail-fast feedback (that is itself a
+  container build — see the containerised-lint rule below), and then runs
+  `docker build --build-arg CHECK_EPOCH="$epoch" --build-arg VERSION="$version" .`,
+  where `epoch` is a per-invocation nonce (see the `CHECK_EPOCH` rule below) and
+  `version` is computed on the host because `.git` is not in the build context
+  (see the git-describe rule below); 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
+  `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).
 
 - Always use Makefile targets (`make fmt`, `make test`, `make lint`, etc.)
   instead of invoking the underlying tools directly. The Makefile is the single
@@ -53,15 +94,338 @@ 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`
+- Every repo should have a `Dockerfile`. It must run the repo's checks as build
-  as a build step so the build fails if the branch is not green. For non-server
+  steps so the build fails if the branch is not green — which requires
-  repos, the Dockerfile should bring up a development environment and run
+  `ARG CHECK_EPOCH` and its guard in every stage containing a check-running
-  `make check`. For server repos, `make check` should run as an early build
+  `RUN`, per the `CHECK_EPOCH` rule below. Without them a Dockerfile satisfies
-  stage before the final image is assembled.
+  this criterion while its check layers are served from cache, so the build
+  cannot fail on a branch that is not green.
+
+    **It runs the individual non-lint checks — `script/test` and
+    `script/fmt-check` — and never `make check`.** `script/lint` is itself a
+    `docker build` (of `Dockerfile.lint`, per the containerised-lint rule
+    below), so a `RUN make check` in this file attempts a docker build inside a
+    build step, where there is no daemon. Lint is not skipped by this: it runs
+    in its own container, and `script/cibuild` runs it first. Put a comment to
+    that effect directly above those `RUN` lines, because `make check` is what
+    the next person will reach for.
+
+    For non-server repos, the Dockerfile should bring up a development
+    environment and run those checks. For server repos, they 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 check-running `RUN` must be cache-busted with `CHECK_EPOCH`.** Docker
+  invalidates a `COPY` layer only when the copied content changes, so on an
+  unchanged tree the check layer is served from cache, the suite never runs, and
+  the build still exits 0. A sub-second `docker build` reporting success is a
+  cache hit, not a result. This applies to **every** file that runs checks in a
+  build step, which since linting moved into its own container means
+  `Dockerfile` and `Dockerfile.lint` both — a `Dockerfile.lint` without the
+  cache-bust is a lint that never ran, reported as a pass. The canonical form,
+  in **every** stage containing a check-running `RUN`, placed **after** the
+  dependency-install layer so that layer stays cached:
+
+    ```dockerfile
+    ARG CHECK_EPOCH
+    RUN [ -n "$CHECK_EPOCH" ] || exit 1
+    RUN echo "check epoch: ${CHECK_EPOCH}" && <the check command>
+    ```
+
+    and in `script/lint`, `script/cibuild` and `script/docker`:
+
+    ```sh
+    epoch="$(date +%s%N)$$"
+    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    [ -n "$version" ] || version="unknown"
+    docker build \
+        --build-arg CHECK_EPOCH="$epoch" \
+        --build-arg VERSION="$version" \
+        .
+    ```
+
+    The `VERSION` lines are there for a different reason, covered by the
+    git-describe rule below; they are shown here so the two rules do not each
+    document half a command. `script/lint` passes only `CHECK_EPOCH`, since no
+    version is embedded in a lint image. All four `CHECK_EPOCH` elements are
+    load-bearing; none is optional, and each guards a failure mode that
+    otherwise fails green:
+    - `ARG` is stage-scoped, so a single declaration leaves the other check
+      stages frozen while the fix reviews as complete. Declare it in every stage
+      that runs checks, immediately above the first such `RUN`.
+    - Expand the value into the command. This makes the cache miss contractual
+      rather than dependent on BuildKit's handling of an unreferenced `ARG`, and
+      it puts the epoch in the build log. The guard is itself value-keyed, for
+      the same reason: it references `$CHECK_EPOCH`, so BuildKit renders the
+      epoch into that layer's description (rendered as
+      `RUN [ -n "<epoch>" ] || exit 1`) and re-runs it whenever the value
+      changes. Each stage therefore has two independent invalidation points, and
+      the guard always precedes the check `RUN`. Keep both: the expansion is
+      defence in depth, and it is what makes the epoch visible in the build
+      output.
+    - The `[ -n ... ]` guard is required: an unset `ARG` is empty, and empty is
+      a stable cache key, so without it a bare `docker build .` still produces
+      the false green. Failed steps are never cached, so the guard fails on
+      every such invocation, loudly. A bare `docker build .` failing is by
+      design.
+    - Assign `epoch=` on its own line, never inline in the `--build-arg`
+      argument: a failing command substitution inside an argument does not trip
+      `set -e`, so the inline form silently degrades to an empty constant. The
+      `$$` suffix is required because busybox `date` drops `%N` and exits 0, so
+      on an alpine host the epoch would degrade to second granularity and
+      concurrent invocations would collide.
+
+    This invalidates the check layers and everything after them while leaving
+    `go mod download`, `script/bootstrap`, and the pinned toolchain install
+    cached, so it does not push against the five-minute Docker build ceiling.
+    Blanket `--no-cache` is **not** an acceptable substitute, on `Dockerfile` or
+    on `Dockerfile.lint`: it re-runs `go mod download` / `yarn install` on every
+    invocation, which makes linting network-dependent and pushes a lint that
+    should take seconds toward the build ceiling. Never reach for
+    `docker builder prune` to achieve the same end — the build cache is shared
+    with every other build on the host, including other people's.
+
+- **Every lint run happens in a container, and `script/lint` is that container
+  build.** The linter is never installed on the host and never invoked there.
+  Every repo carries a `Dockerfile.lint` next to its `Dockerfile`; the linter
+  runs as a **build step**, so a successful build _is_ a clean lint. Building
+  rather than bind-mounting is deliberate: it is what makes the pattern work
+  unchanged where the docker daemon is remote and bind mounts are impossible.
+  Docker is assumed available in every environment. Discarding the linter's
+  cache on every run is the point of this rule, not a cost it pays.
+
+    This closes a family of defects, every one of them an artefact of running
+    the linter on a shared host, and every one of them observed rather than
+    hypothesised:
+    - **A confirmed false green.** An implementer reported `0 issues` on a
+      branch that was genuinely red with a `goconst` finding. golangci-lint keys
+      cached results on file **content, not location**, so a second checkout of
+      the same commit holds byte-identical files and serves its result. Note
+      what content-keying implies: moving agents from worktrees into their own
+      clones does **not** help, because two clones are byte-identical exactly as
+      two worktrees were. It removes the foreign-path symptom and leaves the
+      mechanism live, which makes the defect quieter rather than rarer.
+    - **False reds**, repeatedly: findings reported against `../wt82-lint/...`,
+      against another agent's checkout, and against a worktree that had already
+      been deleted; in one case 399 issues returned to a clean clone that
+      genuinely lints 0.
+    - **Lock contention that cannot be distinguished from findings.**
+      golangci-lint flocks `$TMPDIR/golangci-lint.lock` (`pkg/commands/run.go`,
+      `acquireFileLock()`) — host-global, keyed on the temp directory, entirely
+      independent of `GOLANGCI_LINT_CACHE`, with a 5-second acquire timeout, so
+      it fails precisely when the host is busiest. On failure it prints
+      `parallel golangci-lint is running`, analyzes nothing, and exits non-zero.
+      **Proven not fixed by per-cache isolation**: two concurrent runs with
+      entirely separate cache directories still collided.
+    - **Version skew.** A host linter differing from the pinned one, with the
+      container surfacing thirteen findings the host missed on one repo, and a
+      local `make check` green against a `make docker` that rejected the same
+      commit with six `goconst` findings.
+
+    A container per run has its own cache, its own `TMPDIR` and therefore its
+    own lock, and a binary pinned by digest, so none of the above is reachable.
+    That is also why the per-checkout `GOLANGCI_LINT_CACHE`/`TMPDIR` wrapper
+    that used to be canonical here is **gone rather than kept alongside this**:
+    its entire subject was making a host run trustworthy, and there are no host
+    runs. Consuming repos delete it when they adopt this; see the adoption list
+    at the end of this rule.
+
+    The canonical `Dockerfile.lint` for a Go repo:
+
+    ```dockerfile
+    # Lint-only image. `script/lint` builds this file and nothing else: the
+    # linter runs as a build step, so a successful build IS a clean lint.
+    #
+    # The linter is invoked directly below rather than through `make lint`.
+    # That is not a style choice: `script/lint` IS this build, so calling it
+    # from inside would recurse into a docker build with no daemon.
+    #
+    # golangci/golangci-lint:v2.12.2 (Debian-based), 2026-08-07
+    FROM golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240
+
+    WORKDIR /src
+
+    # Dependency layer first, and deliberately above the ARG below, so it
+    # stays cached and only the lint steps re-run on every invocation.
+    COPY go.mod go.sum ./
+    RUN go mod download
+
+    COPY . .
+
+    ARG CHECK_EPOCH
+    RUN [ -n "$CHECK_EPOCH" ] || exit 1
+    RUN echo "lint epoch: ${CHECK_EPOCH}" && \
+        golangci-lint config verify --config .golangci.yml
+    RUN golangci-lint run --config .golangci.yml ./...
+    ```
+
+    and the canonical `script/lint`, identical in every repo:
+
+    ```sh
+    #!/bin/sh
+    # script/lint: run the linter. The linter is never installed on the host
+    # and never invoked there — it runs in a container, one way, everywhere,
+    # so a run cannot inherit another checkout's cache, another process's
+    # lock, or a host toolchain that differs from the pinned one.
+    set -eu
+
+    ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+    main() {
+        cd "$ROOT"
+        # Own line: a failing command substitution inside an argument does
+        # not trip `set -e`, and `$$` is required because busybox `date`
+        # drops %N without erroring. Without a fresh nonce the lint layer is
+        # served from cache and this script exits 0 having linted nothing.
+        epoch="$(date +%s%N)$$"
+        docker build \
+            --build-arg CHECK_EPOCH="$epoch" \
+            -f Dockerfile.lint \
+            .
+    }
+
+    main "$@"
+    ```
+
+    Load-bearing properties:
+    - **`CHECK_EPOCH`, not `--no-cache`.** `docker build -f Dockerfile.lint .`
+      on an unchanged tree returns a sub-second cached success having linted
+      nothing — the same false green the `CHECK_EPOCH` rule above exists to
+      close, arriving through a new file. The `ARG` goes **after** the
+      dependency layer so `go mod download` / `yarn install` stay cached and
+      only the lint steps re-run. Blanket `--no-cache` also busts the dependency
+      layer, which makes every lint network-dependent.
+    - **Non-Go repos get the same pattern around their own linter** — `eslint`,
+      `ruff`, `prettier`, `shellcheck` — because the ruling is every lint run,
+      not every Go lint run. Only the base image and the lint commands change;
+      the `WORKDIR`, dependency layer, `ARG CHECK_EPOCH`, guard and
+      expanded-value `RUN` are identical. A JS or docs repo bases on its pinned
+      node image, runs `script/bootstrap` as the dependency layer, and lints
+      with the linter from `node_modules`, which is also how it gets the version
+      pinned in `package.json` rather than whatever is on the host.
+    - **Keep `golangci-lint config verify`, and it costs no network.** The two
+      commands catch **disjoint** classes of defect, measured under the pinned
+      v2.12.2 against a config carrying one planted defect at a time: a bogus
+      top-level key and a bogus key nested under `linters.settings.lll` both
+      pass `golangci-lint run` with **exit 0 and `0 issues`** while
+      `config verify` exits 3 and names the key; an invalid value type fails
+      both; an unknown linter name fails `run` and passes `config verify`. So
+      `run` alone silently ignores an unknown key, which is exactly the mode
+      where a threshold reads as configured and is not applied. The earlier
+      caution that `config verify` resolves its JSON schema over a live HTTPS
+      fetch does **not** hold for this pinned version: every case above was
+      re-run under `docker run --network none` and produced byte-identical
+      diagnostics and exit statuses, in a container where
+      `getent hosts golangci-lint.run` exits 2. The schema is embedded in the
+      pinned binary. Re-run that control when bumping the pin rather than
+      treating the result as permanent.
+    - **No repo installs a linter on the host, in `script/bootstrap` or anywhere
+      else.** A host install is now dead weight whose only remaining effect is
+      to reintroduce the version skew above.
+    - **`script/check` still runs `test`, `lint` and `fmt-check`**, so a
+      developer and the pre-commit hook get all three. It therefore requires a
+      docker daemon, and it must never be invoked from inside a build stage —
+      see the `Dockerfile` rule above.
+    - If the project uses `//go:embed` directives referencing build artifacts
+      (e.g. a web frontend compiled elsewhere), `Dockerfile.lint` must create
+      placeholder files so the directives resolve:
+      `RUN mkdir -p web/dist && touch web/dist/index.html`. It must not depend
+      on the real build output; it exists to fail fast.
+    - If linting requires CGO or system libraries (e.g. `vips-dev`), install
+      them in `Dockerfile.lint`.
+
+    **What a consuming repo does to adopt this**, in order: add
+    `Dockerfile.lint`; replace `script/lint` with the build above; delete the
+    `lint` stage from its `Dockerfile` along with the
+    `COPY --from=lint ... /dev/null` ordering line; change that `Dockerfile`'s
+    `RUN make check` to `script/test` and `script/fmt-check` with the comment
+    explaining why; add `script/lint` as the first step of `script/cibuild`;
+    delete any golangci-lint install from `script/bootstrap`; and delete the
+    `.lint-cache/` entries from `.gitignore` and `.dockerignore` together with
+    the per-checkout cache/lock wrapper they served.
+
+    **The separate lint _stage_ is superseded by this and must not survive
+    alongside it.** It ran `make lint`, which is now a docker build, so keeping
+    it is not a stylistic preference but a recursion. Its purpose — fail-fast
+    feedback before the slow build — is served by `script/cibuild` running
+    `script/lint` first, and its `COPY --from=lint /src/go.sum /dev/null`
+    ordering trick, along with the warm-cache re-proof that trick required, is
+    no longer needed because the ordering is now sequential in the shell.
+
+- **The canonical Go repo `Dockerfile`**, which builds and tests but does not
+  lint:
+
+    ```dockerfile
+    # Build stage
+    # golang:1.x-alpine, YYYY-MM-DD
+    FROM golang@sha256:... AS builder
+    WORKDIR /src
+    COPY go.mod go.sum ./
+    RUN go mod download
+    COPY . .
+
+    ARG CHECK_EPOCH
+    RUN [ -n "$CHECK_EPOCH" ] || exit 1
+
+    # The individual non-lint checks, NOT `make check`: script/lint is a
+    # docker build (Dockerfile.lint), so `make check` here would nest a
+    # build inside a build step, where there is no daemon. Lint is not
+    # skipped — script/cibuild runs it first, in its own container.
+    RUN echo "check epoch: ${CHECK_EPOCH}" && make fmt-check
+    RUN make test
+
+    # VERSION comes from the host via --build-arg; see the git-describe rule
+    # below. Never run `git describe` here: .dockerignore excludes .git, so
+    # it yields an empty version without failing the build.
+    ARG VERSION=dev
+    RUN CGO_ENABLED=0 go build -trimpath \
+        -ldflags="-s -w -X main.Version=${VERSION}" \
+        -o /app ./cmd/app/
+
+    # Runtime stage
+    FROM alpine@sha256:...
+    COPY --from=builder /app /usr/local/bin/app
+    ENTRYPOINT ["app"]
+    ```
+
+    Key points:
+    - Tests run in the build stage because they may require compiled artifacts
+      or heavier dependencies.
+    - `ARG CHECK_EPOCH` must be declared in **every** stage containing a
+      check-running `RUN`, because `ARG` is stage-scoped: declaring it in one
+      stage leaves the others frozen at their last cached result while the fix
+      reviews as complete. In each such stage the guard sits immediately below
+      the `ARG`, and the value is expanded into the first check `RUN` so the
+      cache miss does not rely on BuildKit's unreferenced-`ARG` handling. Both
+      lines reference `$CHECK_EPOCH`, so each stage has two independent
+      invalidation points. Later `RUN`s in the same stage need no expansion of
+      their own: their parent layer is already busted.
+    - `ARG VERSION=dev` is declared in the build stage, and its value is
+      supplied on the host by `script/docker` and `script/cibuild` via
+      `--build-arg VERSION=...`. The `dev` default is a placeholder for a local
+      build, not a source of truth. **No stage may call `git describe`**:
+      `.dockerignore` excludes `.git`, so it yields an empty version without
+      failing. See the git-describe rule further down.
 
 - Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
-  runs `docker build .` on push. Since the Dockerfile already runs `make check`,
+  runs `script/cibuild` on push. `script/cibuild` runs **two** container builds:
-  a successful build implies all checks pass.
+  `script/lint` (`Dockerfile.lint`) first, then
+  `docker build --build-arg CHECK_EPOCH="$epoch" --build-arg VERSION="$version" .`
+  for the main image, which runs the non-lint checks. A successful
+  `script/cibuild` therefore implies all checks pass; **a successful
+  `docker build .` on its own does not, because it never lints.** That is the
+  one claim to be careful with when reading these files: the guarantee belongs
+  to `script/cibuild`, not to any single Dockerfile. Both halves of it hold only
+  because each build passes its own `CHECK_EPOCH` nonce — without it an
+  unchanged tree serves the layers from cache and the build reports a green it
+  never earned. A bare `docker build .` or `docker build -f Dockerfile.lint .`
+  fails closed by design, on the `[ -n "$CHECK_EPOCH" ]` guard; always go
+  through `script/cibuild`, `script/docker` or `script/lint`. Never accept a
+  pass as evidence without confirming it ran: a sub-second wall time, or
+  `CACHED` on a check or lint layer, means nothing was executed.
 
 - Use platform-standard formatters: `black` for Python, `prettier` for
   JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
@@ -69,9 +433,11 @@ style conventions are in separate documents:
   Markdown (hard-wrap at 80 columns). Documentation and writing repos (Markdown,
   HTML, CSS) should also have `.prettierrc` and `.prettierignore`.
 
-- Pre-commit hook: `make check` if local testing is possible, otherwise
+- Pre-commit hook: runs `script/precommit`, which calls `script/check`. If local
-  `make lint && make fmt-check`. The Makefile should provide a `make hooks`
+  testing is not possible in the repo, `script/precommit` may skip `script/test`
-  target to install the pre-commit hook.
+  and run only `script/lint` and `script/fmt-check`. The hook is installed by
+  `script/install-precommit`; the Makefile must provide a `make hooks` target
+  that shims to it.
 
 - All repos with software must have tests that run via the platform-standard
   test framework (`go test`, `pytest`, `jest`/`vitest`, etc.). If no meaningful
@@ -82,6 +448,42 @@ style conventions are in separate documents:
 - `make test` must complete in under 20 seconds. Add a 30-second timeout in the
   Makefile.
 
+- **`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:
+
+    ```makefile
+    test:
+    	@<test-command> || \
+    		{ echo "--- Rerunning with -v for details ---"; \
+    		  <test-command-with-v>; exit 1; }
+    ```
+
+    Go example:
+
+    ```makefile
+    test:
+    	@go test -timeout 30s -race -cover ./... || \
+    		{ echo "--- Rerunning with -v for details ---"; \
+    		  go test -timeout 30s -race -v ./...; exit 1; }
+    ```
+
+    Python example:
+
+    ```makefile
+    test:
+    	@python -m pytest || \
+    		{ echo "--- Rerunning with -v for details ---"; \
+    		  python -m pytest -v; exit 1; }
+    ```
+
+    The `exit 1` ensures the target always fails after a rerun — the first run
+    already proved the tests are broken, so the build must not pass even if a
+    flaky test happens to succeed on the second attempt. The rerun exists solely
+    for diagnostic output.
+
 - Docker builds must complete in under 5 minutes.
 
 - `make check` must not modify any files in the repo. Tests may use temporary
@@ -93,10 +495,147 @@ 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/`.
+  editor files (`.swp`, `*~`), in-repo agent scratch directories (`.claude/`,
-  Fetch the standard `.gitignore` from
+  which holds one worktree — an entire additional checkout of the repo — per
+  in-flight agent), 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.
+  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 — see the
+  next rule.
+
+- **`.dockerignore` does not use `.gitignore` semantics, and copying patterns
+  across unmodified leaves secrets in the build context.** Docker matches with
+  `moby/patternmatcher`: Go `filepath.Match` semantics plus a `**` extension,
+  compiled to a regexp — plain `filepath.Match` has no `**` at all. 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; `config/.env` and
+  `certs/server.key` still reach the context and can land in an image layer.
+  That file is more dangerous than a short one with no secret patterns at all,
+  because it reads as solved and stops anyone looking. Give every
+  depth-independent pattern the `**/` prefix — `**/node_modules`,
+  `**/.DS_Store`, and the secret patterns in the canonical file, which are
+  additionally case-folded per the rule below — and leave only genuinely
+  root-anchored entries unprefixed: `.git`, the in-repo agent scratch directory
+  `.claude`, and the repo's own host-built binary. The inverse move is equally
+  wrong: never apply `**/` to `.gitignore`, where it is redundant and produces a
+  file that is wrong in a way that looks careful. Each file is written to its
+  own semantics; neither is derived from the other. Fetch the standard
+  `.dockerignore` from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` and extend
+  it with the repo's own host-built artifacts — a host `make build` that leaves
+  a compiled binary in the repo root puts that binary in the build context,
+  where `.gitignore` hides it from every git-based check. Write that binary
+  anchored, `/myapp` and never `**/myapp`: the prefixed form also matches
+  `cmd/myapp/` and deletes the package directory from the context.
+
+- **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 with `COPY . .` the build context
+  inflates by a multiple of the repo, and another session's unreviewed,
+  sometimes uncommitted work can be copied into an image layer. The directory is
+  also created and destroyed constantly, so it invalidates `COPY . .` for
+  reasons that have nothing to do with the repo's own content. In `.gitignore`
+  the entry is `.claude/`, unanchored, which already matches at every depth. In
+  `.dockerignore` it is `.claude`, anchored and with **no** `**/` prefix: the
+  directory occurs exactly once **where agents run at the repo root**, and the
+  prefixed form would also match any nested directory of that name and delete it
+  from the build. It is not case-folded the way the secret patterns are, because
+  tooling creates it in exactly one spelling, so a folded pattern would add no
+  coverage.
+
+    **Known gap that comes with the anchored form.** The directory is created in
+    the agent's working directory, so the "exactly once, at the root" premise is
+    a property of how agents are run and not of the tooling. Where agents run in
+    subdirectories — a monorepo with a per-service agent is the ordinary case —
+    `services/api/.claude/` is **not** excluded by the canonical entry and still
+    reaches the build context and the image, which is the exposure the entry
+    exists to close. A repo in that shape adds its own anchored entries
+    (`/services/api/.claude`), or `**/.claude` once it has confirmed no
+    legitimately named nested directory would be caught. This is stated in the
+    canonical `.dockerignore` itself, since that file is what consuming repos
+    receive.
+
+- **`.dockerignore` matching is case-sensitive, so cover capitalisation with
+  character classes rather than by doubling patterns.** `**/*.key` does not
+  match `certs/SERVER.KEY`, which is reachable on the case-insensitive
+  filesystems most laptops use. Adding an ALL-CAPS twin for each pattern is not
+  the fix: it still misses `Server.Key` and `Ca.Pem` while reading as though
+  case were handled — the same manufactured confidence as the root-anchored
+  form. The matcher supports character ranges, so one line covers every
+  spelling: `**/*.[kK][eE][yY]`, `**/*.[pP][eE][mM]`. Apply this to every secret
+  name, not only to extensions: the extensionless SSH keys and `.envrc` need it
+  for the same reason, since on the very filesystems that make `SERVER.KEY`
+  reachable, direnv reads `.ENVRC` and ssh reads `ID_RSA`. Note that `*` matches
+  the empty string, so `**/*.[eE][nN][vV]` already covers a bare `.ENV` and no
+  separate literal `.env` entry is needed.
+
+- **A pattern that also catches something the build needs is re-included with a
+  negation, not deleted.** The canonical `**/*.[eE][nN][vV]` excludes a
+  committed env template such as `example.env`; a repo whose build genuinely
+  reads one adds `!docs/example.env` after the pattern. Deleting the pattern
+  instead reopens the exposure for every other file it covers.
+
+- **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`). Reading the patterns and
+  agreeing they look right is exactly what lets the root-only form through. 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, so the
+  reported size describes the transfer and not the contents of the image.
+
+- **Excluding `.git` means `git describe` cannot run inside any build stage, and
+  it fails quietly there.** The `GOLDFLAGS` version-embedding pattern assumes
+  `.git` is present; in a build stage there is no repository, so `git describe`
+  writes nothing to stdout and the `-X main.Version=` value comes out **empty**
+  rather than erroring. The binary then reports no version at all and the build
+  still exits 0. Compute the version **on the host** and thread it in as a build
+  arg. `script/docker` and `script/cibuild` do this, byte-identically across
+  repos:
+
+    ```sh
+    # Assign on its own line: a failing command substitution inside an
+    # argument does not trip `set -e`, so the inline form degrades to an
+    # empty constant — the same silent-empty failure this rule is about.
+    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    [ -n "$version" ] || version="unknown"
+    docker build \
+        --build-arg CHECK_EPOCH="$epoch" \
+        --build-arg VERSION="$version" \
+        .
+    ```
+
+    `--always` makes an untagged repo yield the abbreviated commit hash instead
+    of failing. `|| true` keeps a failing `git describe` from tripping `set -e`
+    and leaves the value empty, so the `[ -n "$version" ]` line is the single
+    place the fallback is applied — and it is a **live** check, not defence in
+    depth: it fires on a build from an export with no `.git`, and on a
+    repository with no commits yet. Do not fold the fallback into the
+    substitution as `|| echo unknown`; that makes the guard unreachable, and a
+    guard that cannot fire is indistinguishable from one that works to everyone
+    who copies it. The result is non-empty by construction either way, which is
+    the point: an empty version reads as a successful one, while `unknown` is
+    visibly wrong. The Dockerfile's side is `ARG VERSION=dev` in the stage that
+    compiles, declared there and not inherited, because `ARG` is stage-scoped
+    exactly as `CHECK_EPOCH` is. Passing `VERSION` to a repo whose Dockerfile
+    declares no such `ARG` is silently ignored by BuildKit and costs nothing,
+    which is why the scripts stay byte-identical rather than growing a per-repo
+    variant.
+
+    One consequence for CI: the standard checkout action clones shallow and
+    fetches no tags, so `git describe --tags` there falls back to a bare commit
+    hash. A repo that embeds a tag-derived version must set `fetch-depth: 0` on
+    its checkout step; a repo that does not embed a version needs no change.
+
+- **No build artifacts in version control.** Code-derived data (compiled
+  bundles, minified output, generated assets) must never be committed to the
+  repository if it can be avoided. The build process (e.g. Dockerfile, Makefile)
+  should generate these at build time. Notable exception: Go protobuf generated
+  files (`.pb.go`) ARE committed because repos need to work with `go get`, which
+  downloads code but does not execute code generation.
 
 - Never use `git add -A` or `git add .`. Always stage files explicitly by name.
 
@@ -107,7 +646,127 @@ style conventions are in separate documents:
 
 - `.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`.
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`. The
+  canonical golangci-lint version is v2.12.2 (released 2026-05-06), pinned as
+  the image digest in `Dockerfile.lint`
+  (`golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240`,
+  which reports
+  `golangci-lint has version 2.12.2 built with go1.26.2 from c0d3ddc9`). That
+  digest is the only pin there is: the linter is not installed on the host, in
+  `script/bootstrap` or anywhere else. Bumping the version means changing that
+  one digest, and it propagates to every consumer of the image with no host
+  state able to disagree with it.
+
+- **`script/bootstrap` must not install a linter at all.** This supersedes the
+  pinned-golangci-lint install that used to be canonical here. Nothing runs a
+  linter on the host any more — `script/lint` is a container build — so a host
+  install has no caller left, and its only remaining effect is to put a second,
+  independently-versioned linter on the machine where somebody will eventually
+  run it by hand and believe the result. The version-skew failures that install
+  was written to close (a local `make check` green while `make docker` rejected
+  the same commit with six `goconst` findings; a container linter surfacing
+  thirteen findings the host run missed) are closed more completely by having
+  exactly one linter, pinned by image digest, that no host state can shadow.
+  Repos adopting the containerised lint delete the install block, its version
+  and ref variables, and its call site from `script/bootstrap`.
+
+    **The version-enforcement principle it established still applies to any
+    other tool a repo pins and installs on the host**, and it is the part worth
+    keeping, because each of its four properties guards a failure that otherwise
+    reports success:
+    - **Compare the installed version against the pin, never test presence.** A
+      `if missing <tool>; then install; fi` guard tests `PATH` presence and
+      never version, so on any already-provisioned machine the pin is inert and
+      a version bump is a silent no-op. Compare the **whole** version token,
+      exactly: a parser that stops at the first `-` reports `2.12.2` for a host
+      running `2.12.2-rc1` and skips the install — the original defect,
+      reintroduced through the comparison meant to fix it.
+    - **After installing, re-resolve the binary the way callers resolve it** —
+      through `PATH`, not the directory the installer wrote to — and assert the
+      reported version is the pin. An installer that writes to `GOBIN` while a
+      different binary shadows it earlier in `PATH` genuinely succeeds and
+      changes nothing any caller sees, which is worse than no fix: it converts a
+      known-stale tool into one everyone believes is pinned. Run `hash -r` first
+      so the shell does not answer from its own lookup cache, and when the
+      assertion fails, name the path `command -v` found, the version it reports,
+      and the directory the install wrote to. Diagnose from the resolved path
+      rather than asserting a cause: only a path **outside** the install
+      directory is shadowing.
+    - **A mis-parse must fall through to reinstall, never to a false match.**
+      Absent binary, non-zero exit, empty output and unrecognised output should
+      all yield an empty string, which compares unequal to the pin. The failure
+      direction is always a redundant install, never a skipped one.
+    - **Call it, and say so on success.** A function defined and never called is
+      a silent no-op indistinguishable from success: exit 0, nothing installed,
+      no output. Both success branches must print a line naming the version.
+
+    Verifying such logic requires a negative control in an environment where a
+    shadowing binary exists earlier in `PATH` than the install target — without
+    it the control passes against the naive compare-then-install form too and
+    proves nothing — plus a mis-parse control that feeds unparseable `--version`
+    output and confirms a reinstall. Run those controls against the block as a
+    consuming repo would adopt it: pasted into a `script/bootstrap`-shaped file
+    that is then executed, never by sourcing it and invoking the function
+    yourself. Driving the function directly tests something the artifact does
+    not do, and it is exactly how a missing call site passes every control while
+    the adopted snippet does nothing.
+
+    Keep it POSIX sh: no bashisms, no arrays, no `[[`, no `grep -P`.
+
+- **SUPERSEDED, and deleted rather than kept: the per-checkout
+  `GOLANGCI_LINT_CACHE`/`TMPDIR` wrapper for `script/lint`.** Every line of it
+  was about making a linter run on a shared host trustworthy — a private result
+  cache so a byte-identical checkout could not serve its findings, a private
+  `TMPDIR` so the host-global lock could not collide, retry and VOID handling so
+  a lock collision was never reported as findings. The containerised-lint rule
+  above removes the host run itself, so there is nothing left for that wrapper
+  to isolate, and a repo carrying both would carry two contradictory canonical
+  `script/lint` forms. Its findings are not lost: they are the evidence for
+  containerising, and they are recorded in that rule. Repos that adopted it
+  delete the wrapper, the `.lint-cache/` entries from `.gitignore` and
+  `.dockerignore`, and the `--allow-serial-runners` flag with them.
+
+    Two of its conclusions are kept because they outlive it. **`GOCACHE` does
+    not need isolating**, measured rather than assumed: it is content-addressed,
+    its entries are compiled artifacts rather than diagnostics carrying a
+    foreign tree's paths, and it has no equivalent global lock — the whole fleet
+    compiles concurrently against one `GOCACHE` all day without a contention
+    error. And **verifying any change to lint plumbing requires paired
+    controls**: a control that passes against the broken form proves nothing,
+    and it must be run against the artifact as a consuming repo would adopt it —
+    the file executed, not the functions sourced and driven by hand.
+
+- **Interim rule for reading a lint result produced on the host, in a repo that
+  has not yet adopted the containerised lint above.** A lint run is **VOID**
+  unless both hold:
+    - the output contains no `parallel golangci-lint is running`, and
+    - no reported file path begins with `../`, and none is an absolute path
+      outside the tree the run was launched from.
+
+    Do not record a verdict from a void run, and do not "fix" findings in files
+    the change does not touch — chasing phantom findings across untouched files
+    puts unrelated edits into a reviewed diff, which is more expensive than the
+    wasted rework.
+
+    The `../` clause is the one that actually bites, and it is why a filter
+    keyed on `/tmp` or on absolute prefixes is not enough: golangci-lint reports
+    paths relative to its own resolved root rather than yours, and three of the
+    org's reported sightings had relative paths and would have passed such a
+    filter. Both clauses are needed and neither alone is sufficient — one
+    reproduction exited non-zero with the lock error and no foreign paths at
+    all, and another reported 34 well-formed findings, every one of them against
+    another checkout.
+
+    **State the limit of these tests rather than treating them as a guarantee.**
+    They catch contamination that **names** foreign files. They cannot catch
+    contamination that **suppresses** findings through a poisoned entry for
+    colliding content, which has no wall-clock tell either — **no evidence of
+    that mode has been observed, and nobody should go chasing it**; the point is
+    the reach of the tests, not a claim that the mode exists. They are a filter
+    for the loud mode, not a proof of soundness — which is the whole argument
+    for containerising the linter instead of documenting a discipline that
+    depends on every agent remembering to apply it. Adopt the rule above and
+    this one stops applying to the repo entirely.
 
 - When pinning images or packages by hash, add a comment above the reference
   with the version and date (YYYY-MM-DD).
@@ -121,12 +780,76 @@ style conventions are in separate documents:
 - Dockerized web services listen on port 8080 by default, overridable with
   `PORT`.
 
+- **HTTP/web services must be hardened for production internet exposure before
+  tagging 1.0.** This means full compliance with security best practices
+  including, without limitation, all of the following:
+    - **Security headers** on every response:
+        - `Strict-Transport-Security` (HSTS) with `max-age` of at least one year
+          and `includeSubDomains`.
+        - `Content-Security-Policy` (CSP) with a restrictive default policy
+          (`default-src 'self'` as a baseline, tightened per-resource as
+          needed). Never use `unsafe-inline` or `unsafe-eval` unless
+          unavoidable, and document the reason.
+        - `X-Frame-Options: DENY` (or `SAMEORIGIN` if framing is required).
+          Prefer the `frame-ancestors` CSP directive as the primary control.
+        - `X-Content-Type-Options: nosniff`.
+        - `Referrer-Policy: strict-origin-when-cross-origin` (or stricter).
+        - `Permissions-Policy` restricting access to browser features the
+          application does not use (camera, microphone, geolocation, etc.).
+    - **Request and response limits:**
+        - Maximum request body size enforced on all endpoints (e.g. Go
+          `http.MaxBytesReader`). Choose a sane default per-route; never accept
+          unbounded input.
+        - Maximum response body size where applicable (e.g. paginated APIs).
+        - `ReadTimeout` and `ReadHeaderTimeout` on the `http.Server` to defend
+          against slowloris attacks.
+        - `WriteTimeout` on the `http.Server`.
+        - `IdleTimeout` on the `http.Server`.
+        - Per-handler execution time limits via `context.WithTimeout` or
+          chi/stdlib `middleware.Timeout`.
+    - **Authentication and session security:**
+        - Rate limiting on password-based authentication endpoints. API keys are
+          high-entropy and not susceptible to brute force, so they are exempt.
+        - CSRF tokens on all state-mutating HTML forms. API endpoints
+          authenticated via `Authorization` header (Bearer token, API key) are
+          exempt because the browser does not attach these automatically.
+        - Passwords stored using bcrypt, scrypt, or argon2 — never plain-text,
+          MD5, or SHA.
+        - Session cookies set with `HttpOnly`, `Secure`, and `SameSite=Lax` (or
+          `Strict`) attributes.
+    - **Reverse proxy awareness:**
+        - True client IP detection when behind a reverse proxy
+          (`X-Forwarded-For`, `X-Real-IP`). The application must accept
+          forwarded headers only from a configured set of trusted proxy
+          addresses — never trust `X-Forwarded-For` unconditionally.
+    - **CORS:**
+        - Authenticated endpoints must restrict `Access-Control-Allow-Origin` to
+          an explicit allowlist of known origins. Wildcard (`*`) is acceptable
+          only for public, unauthenticated read-only APIs.
+    - **Error handling:**
+        - Internal errors must never leak stack traces, SQL queries, file paths,
+          or other implementation details to the client. Return generic error
+          messages in production; detailed errors only when `DEBUG` is enabled.
+    - **TLS:**
+        - Services never terminate TLS directly. They are always deployed behind
+          a TLS-terminating reverse proxy. The service itself listens on plain
+          HTTP. However, HSTS headers and `Secure` cookie flags must still be
+          set by the application so that the browser enforces HTTPS end-to-end.
+
+    This list is non-exhaustive. Apply defense-in-depth: if a standard security
+    hardening measure exists for HTTP services and is not listed here, it is
+    still expected. When in doubt, harden.
+
 - `README.md` is the primary documentation. Required sections:
     - **Description**: First line must include the project name, purpose,
       category (web server, SPA, CLI tool, etc.), license, and author. Example:
       "µPaaS is an MIT-licensed Go web application by @sneak that receives
       git-frontend webhooks and deploys applications via Docker in realtime."
     - **Getting Started**: Copy-pasteable install/usage code block.
+    - **Entrypoints**: Opens by stating that the repo adheres to the
+      [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+      standard (with that link), then documents each provided `script/`
+      entrypoint and its purpose.
     - **Rationale**: Why does this exist?
     - **Design**: How is the program structured?
     - **TODO**: Update meticulously, even between commits. When planning, put
@@ -181,6 +904,9 @@ style conventions are in separate documents:
     - `README.md`, `.git`, `.gitignore`, `.editorconfig`
     - `LICENSE`, `REPO_POLICIES.md` (copy from the `prompts` repo)
     - `Makefile`
+    - `script/` entrypoints (`bootstrap`, `setup`, `projectname`, `test`,
+      `lint`, `fmt`, `fmt-check`, `check`, `docker`, `cibuild`, `precommit`,
+      `install-precommit`)
     - `Dockerfile`, `.dockerignore`
     - `.gitea/workflows/check.yml`
     - Go: `go.mod`, `go.sum`, `.golangci.yml`

script/bootstrap

@@ -0,0 +1,136 @@
+#!/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. Node is
+# used directly if installed; otherwise it is installed at a pinned
+# version via nvm (installing nvm itself first, from a hash-verified
+# release archive, never curl | sh).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+# Pinned versions, 2026-07-06
+NODE_VERSION="22.17.0"
+NVM_VERSION="0.40.3"
+# sha256 of https://github.com/nvm-sh/nvm/archive/refs/tags/v0.40.3.tar.gz
+NVM_SHA256="5f4d6aaa04a177dc93c985e31dbc411ab6b8c6e1e21d8015dbc1372625fcd1d0"
+YARN_VERSION="1.22.22"
+
+PKGMGR=""
+SUDO=""
+
+detect_pkgmgr() {
+    [ -n "$PKGMGR" ] && return 0
+    if command -v nix-env >/dev/null 2>&1; then
+        PKGMGR="nix"
+    elif command -v apt-get >/dev/null 2>&1; then
+        PKGMGR="apt"
+    elif command -v brew >/dev/null 2>&1; then
+        PKGMGR="brew"
+    elif command -v apk >/dev/null 2>&1; then
+        PKGMGR="apk"
+    else
+        echo "bootstrap: no supported package manager (nix, apt, brew, apk)" >&2
+        exit 1
+    fi
+    if [ "$PKGMGR" = "apt" ]; then
+        export DEBIAN_FRONTEND=noninteractive
+        if [ "$(id -u)" != "0" ]; then
+            SUDO="sudo"
+        fi
+    fi
+}
+
+# pkg_install <nix-attr> <apt-pkg> <brew-formula> <apk-pkg>
+pkg_install() {
+    detect_pkgmgr
+    case "$PKGMGR" in
+        nix) nix-env -iA "nixpkgs.$1" ;;
+        apt) $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y "$2" ;;
+        brew) brew install "$3" ;;
+        apk) apk add --no-cache "$4" ;;
+    esac
+}
+
+missing() {
+    ! command -v "$1" >/dev/null 2>&1
+}
+
+# verify_sha256 <file> <expected-hash>
+verify_sha256() {
+    if command -v sha256sum >/dev/null 2>&1; then
+        actual="$(sha256sum "$1" | cut -d' ' -f1)"
+    else
+        actual="$(shasum -a 256 "$1" | cut -d' ' -f1)"
+    fi
+    if [ "$actual" != "$2" ]; then
+        echo "bootstrap: sha256 mismatch for $1" >&2
+        echo "  expected: $2" >&2
+        echo "  actual:   $actual" >&2
+        exit 1
+    fi
+}
+
+# nvm is a bash script; run a command in a bash with nvm loaded
+nvm_sh() {
+    bash -c ". \"\$HOME/.nvm/nvm.sh\" && $*"
+}
+
+ensure_nvm() {
+    [ -s "$HOME/.nvm/nvm.sh" ] && return 0
+    # nvm prerequisites; nvm itself requires bash
+    if missing bash; then pkg_install bash bash bash bash; fi
+    if missing curl; then pkg_install curl curl curl curl; fi
+    if missing git; then pkg_install git git git git; fi
+    tmp="$(mktemp -d)"
+    curl -fsSL -o "$tmp/nvm.tar.gz" \
+        "https://github.com/nvm-sh/nvm/archive/refs/tags/v${NVM_VERSION}.tar.gz"
+    verify_sha256 "$tmp/nvm.tar.gz" "$NVM_SHA256"
+    mkdir -p "$HOME/.nvm"
+    tar -xzf "$tmp/nvm.tar.gz" -C "$HOME/.nvm" --strip-components=1
+    rm -rf "$tmp"
+}
+
+ensure_node() {
+    if ! missing node; then return 0; fi
+    ensure_nvm
+    nvm_sh "nvm install $NODE_VERSION"
+}
+
+ensure_yarn() {
+    if ! missing yarn; then return 0; fi
+    if ! missing corepack; then
+        corepack enable
+        corepack prepare "yarn@$YARN_VERSION" --activate
+    elif [ -s "$HOME/.nvm/nvm.sh" ]; then
+        nvm_sh "nvm use $NODE_VERSION >/dev/null && corepack enable && \
+            corepack prepare yarn@$YARN_VERSION --activate"
+    else
+        npm install -g "yarn@$YARN_VERSION"
+    fi
+}
+
+install_js_deps() {
+    if missing yarn && [ -s "$HOME/.nvm/nvm.sh" ]; then
+        nvm_sh "nvm use $NODE_VERSION >/dev/null && cd \"$ROOT\" && \
+            yarn install --frozen-lockfile"
+    else
+        yarn install --frozen-lockfile
+    fi
+}
+
+main() {
+    cd "$ROOT"
+
+    if missing make; then pkg_install gnumake make make make; fi
+    if missing git; then pkg_install git git git git; fi
+
+    ensure_node
+    ensure_yarn
+    install_js_deps
+
+    echo "bootstrap complete"
+}
+
+main "$@"

script/check

@@ -0,0 +1,21 @@
+#!/bin/sh
+# script/check: run all checks (test, lint, fmt-check). Our own
+# extension to scripts-to-rule-them-all. Must not modify any files.
+#
+# script/lint is a docker build (see Dockerfile.lint), so this script
+# requires a docker daemon. That is deliberate: it is the only way a
+# developer and the pre-commit hook get the same linter CI gets. It also
+# means this script must never be run from inside a build stage — see
+# the comment in Dockerfile, which runs the individual non-lint checks
+# for exactly that reason.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+
+main() {
+    "$SCRIPT_DIR/test"
+    "$SCRIPT_DIR/lint"
+    "$SCRIPT_DIR/fmt-check"
+}
+
+main "$@"

script/cibuild

@@ -0,0 +1,40 @@
+#!/bin/sh
+# script/cibuild: run the CI build. Two container builds, in order:
+# script/lint (Dockerfile.lint) and then the main image, which runs the
+# non-lint checks. Both only prove anything because each passes its own
+# fresh CHECK_EPOCH nonce: without it Docker serves the check layers
+# from cache on an unchanged tree and the build exits 0 without running
+# anything.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    # Lint first, for fail-fast feedback: it is its own container build
+    # and computes its own CHECK_EPOCH. It runs here rather than inside
+    # the main image because a docker build cannot run a docker build.
+    "$SCRIPT_DIR/lint"
+    # Assign on its own line: a failing command substitution inside an
+    # argument does not trip `set -e`, which would silently degrade the
+    # nonce to an empty constant. `$$` is required because busybox `date`
+    # drops %N without erroring.
+    epoch="$(date +%s%N)$$"
+    # VERSION must be computed here, on the host: .dockerignore excludes
+    # .git, so `git describe` cannot run in any build stage and fails
+    # quietly there rather than erroring. Same own-line discipline as the
+    # epoch. `|| true` keeps a failing describe from tripping `set -e`
+    # and leaves the value empty; the guard below is then the single
+    # place the fallback is applied, and it does fire — on an export with
+    # no .git, or a repo with no commits yet. `unknown` is visibly wrong
+    # in a binary in a way that an empty version is not.
+    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    [ -n "$version" ] || version="unknown"
+    docker build \
+        --build-arg CHECK_EPOCH="$epoch" \
+        --build-arg VERSION="$version" \
+        .
+}
+
+main "$@"

script/docker

@@ -0,0 +1,35 @@
+#!/bin/sh
+# script/docker: build the Docker image tagged with the project name.
+# Identical in all repos; the tag comes from script/projectname. The
+# Dockerfile's checks only actually run because CHECK_EPOCH is a fresh
+# nonce on every invocation; without it a warm cache turns this into a
+# green that proves nothing.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    # Assign on its own line: a failing command substitution inside an
+    # argument does not trip `set -e`, which would silently degrade the
+    # nonce to an empty constant. `$$` is required because busybox `date`
+    # drops %N without erroring.
+    epoch="$(date +%s%N)$$"
+    # VERSION must be computed here, on the host: .dockerignore excludes
+    # .git, so `git describe` cannot run in any build stage and fails
+    # quietly there rather than erroring. Same own-line discipline as the
+    # epoch. `|| true` keeps a failing describe from tripping `set -e`
+    # and leaves the value empty; the guard below is then the single
+    # place the fallback is applied, and it does fire — on an export with
+    # no .git, or a repo with no commits yet. `unknown` is visibly wrong
+    # in a binary in a way that an empty version is not.
+    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    [ -n "$version" ] || version="unknown"
+    docker build \
+        --build-arg CHECK_EPOCH="$epoch" \
+        --build-arg VERSION="$version" \
+        -t "$("$SCRIPT_DIR/projectname")" .
+}
+
+main "$@"

script/fmt

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/fmt: format all files (writes).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    yarn run prettier --write '**/*.md' --tab-width 4 --prose-wrap always
+}
+
+main "$@"

script/fmt-check

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/fmt-check: check formatting (read-only).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always
+}
+
+main "$@"

script/install-precommit

@@ -0,0 +1,16 @@
+#!/bin/sh
+# script/install-precommit: install the git pre-commit hook that runs
+# script/precommit. Our own extension to scripts-to-rule-them-all.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    hook=".git/hooks/pre-commit"
+    printf '#!/bin/sh\nset -e\nscript/precommit\n' > .git/hooks/pre-commit
+    chmod +x .git/hooks/pre-commit
+    echo "pre-commit hook installed: runs script/precommit"
+}
+
+main "$@"

script/lint

@@ -0,0 +1,27 @@
+#!/bin/sh
+# script/lint: run the linter. The linter is never installed on the host
+# and never invoked there — it runs in a container, one way, everywhere,
+# so a run cannot inherit another checkout's cache, another process's
+# lock, or a host toolchain that differs from the pinned one. Linting
+# happens as a build step (see Dockerfile.lint), so a successful build
+# is a clean lint, and it works where the docker daemon is remote and
+# bind mounts are impossible.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    # Assign on its own line: a failing command substitution inside an
+    # argument does not trip `set -e`, which would silently degrade the
+    # nonce to an empty constant. `$$` is required because busybox `date`
+    # drops %N without erroring. Without a fresh nonce the lint layer is
+    # served from cache and this script exits 0 having linted nothing.
+    epoch="$(date +%s%N)$$"
+    docker build \
+        --build-arg CHECK_EPOCH="$epoch" \
+        -f Dockerfile.lint \
+        .
+}
+
+main "$@"

script/precommit

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/precommit: run by the git pre-commit hook; fails the commit if
+# checks fail. Our own extension to scripts-to-rule-them-all.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+
+main() {
+    "$SCRIPT_DIR/check"
+}
+
+main "$@"

script/projectname

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/projectname: output the name of this project. Our own
+# extension to scripts-to-rule-them-all. Other scripts that need the
+# name (e.g. script/docker) call this, so they can stay identical
+# across all repos.
+set -eu
+
+main() {
+    echo "prompts"
+}
+
+main "$@"

script/setup

@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/setup: set up the repo for development after a fresh clone:
+# installs dependencies and the git pre-commit hook.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+
+main() {
+    "$SCRIPT_DIR/bootstrap"
+    "$SCRIPT_DIR/install-precommit"
+}
+
+main "$@"

script/test

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/test: run the test suite.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    echo "No tests defined."
+}
+
+main "$@"