Cuts history ("Both have produced wrong verdicts"), an example given
for a stated reason (the Go image's toolchain), the tag sentence that
the version snippet's comment states, and the short cache list that
the Go section gives in full; takes in the rule to keep the stage that
ships last, which the Go section's commit removes; every rule stays.
Model: opus-5-5
51 KiB
title, last_modified
| title | last_modified |
|---|---|
| Repository Policies | 2026-11-16 |
This document covers repository structure, tooling, and workflow standards. Code style conventions are in separate documents:
- Code Styleguide (general, bash, Docker)
- Go
- JavaScript
- Python
- Go HTTP Server Conventions
- API Policies
Pin external references by hash
-
External references must be pinned by cryptographic hash. This is the single most important rule in this document. It covers what we download and install ourselves in scripts and Dockerfiles. Reference each by its content hash:
- Docker base images:
@sha256:... - Go modules: the module hash in
go.sum - Python packages from PyPI: the package hash in
Pipfile.lock - npm packages: the
checksuminyarn.lock - GitHub Actions:
@<commit-sha> - release archives fetched with
curlorwget: a hash hardcoded in the Dockerfile or script
Packages from the distribution's own package manager are outside this rule. They need no version and no hash, because the distribution is trusted. In a
Dockerfile, it is the pinned base image's distribution. On a host, it is the host's. The host's package manager stands for its distribution, and that includes nix and brew. Updating the package index and upgrading installed packages are fine too. This command, for example, is allowed:apt update && apt upgrade -y && apt install -y build-essentialA package source that a
Dockerfileadds itself is not the distribution's own, so its packages are pinned like any other download.- A version tag such as
@v4,@latestor:3.21is server-mutable, and therefore a remote code execution vulnerability. - An unverified install script is arbitrary remote code execution. Never
curl | bashto install a tool such as rustup. Instead, download a specific release archive from GitHub, verify its hash, and only then install. - Docker Hub, PyPI, the npm registry and
go getare not trusted, so everything from them stays pinned by hash. - Above each image or package pinned by hash, add a comment with the version and date (YYYY-MM-DD).
- Double-check every external reference in every file before committing.
node, yarn, npm, python, pip and venv come from the distribution wherever possible:
- node means the distribution's newest Node package, such as
nodejs-currenton Alpine 3.24. - pip and venv are the installer tools bundled with python.
- If the distribution's version is too old, use a newer distribution, never
a download. That rules out nvm, pyenv, corepack and
npm install -g yarn.
yarn's release file is third-party code, and git pins it.
yarn set versionwrites it to.yarn/releases/once, given an exact version. - Docker base images:
Git and secrets
-
Never commit secrets.
.envfiles, credentials, API keys, and private keys must be in.gitignore. No exceptions. -
Make all changes on a feature branch. You can do whatever you want on a feature branch.
-
Never force-push to
main. -
Never use
git add -Aorgit add .. Always stage files explicitly by name. -
No build artifacts in version control. Code-derived data must never be committed to the repository if it can be avoided. Code-derived data includes:
- compiled bundles
- minified output
- generated assets
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 withgo get, which downloads code but does not execute code generation.
Entrypoints
-
Repos follow the Scripts to Rule Them All pattern. Every repo with software must have a root
Makefilewith the targets below. Each target is a thin shim that calls an executable script inscript/, where its implementation lives:make bootstrap:script/bootstrapinstalls all dependencies.make setup:script/setupreadies a fresh clone for development. It runsbootstrap, theninstall-precommit, plus any repo-specific initialization.make test:script/testmake lint:script/lintmake fmt:script/fmt(writes)make fmt-check:script/fmt-check(read-only)make check:script/checkrunsscript/test,script/lintandscript/fmt-check.make docker:script/dockermake hooks:script/install-precommitinstalls the git pre-commit hook.make update-policy:script/update-policyfetches the vendored policy files from thepromptsrepo, commits them and pushes.
Three more scripts have no required target:
script/precommitis what the pre-commit hook runs. It callsscript/check. Repo-type-specific extras belong in it, not in the hook itself;go mod tidyverification in Go repos is one. If local testing is not possible in the repo, it may skipscript/testand run onlyscript/lintandscript/fmt-check.script/cibuildruns the CI build, and the Gitea workflow calls it.script/projectname(literally that filename) outputs the project's name. Scripts that need the name call it, so they stay byte-identical across all repos.script/docker, for example, assembles its image tag from it.
From the standard's canonical set we use
bootstrap,setup,test, andcibuild.check,precommit,install-precommit,update-policyandprojectnameare our own extensions to the standard.The scripts must be POSIX sh (
#!/bin/sh,set -eu, no bashisms) so they run in minimal containers; alpine images, for example, have no bash. Locate the repo root with$(cd "$(dirname "$0")/.." && pwd -P), andcdthere before acting. A model Makefile is athttps://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile. Model scripts are athttps://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>. -
Run the repo's own entrypoints, never the underlying tools directly. The
script/scripts are the single source of truth for how each operation runs. Calling them directly is fine, and so is calling the Makefile targets. The Makefile targets must still exist, as the thin shims described above.An agent whose work is confined to one package may run
go testdirectly on that package's suite, or on individual tests in it, while iterating. This is the only exception to this rule.go build,go vetand the linter still go through the entrypoints. A run while iterating is not a gate, so the fullmake checkis still required before every push. -
The Makefile is authoritative documentation for how the repo is used. Beyond the required targets above, it should have targets for every common operation:
- running a local development server (
make run,make dev) - re-initializing or migrating the database (
make db-reset,make migrate) - building artifacts (
make build) - generating code
- seeding data
- anything else a developer would do regularly
Typing
make<tab>in a checkout should show every meaningful operation. A new contributor should be able to understand the entire development workflow by reading the Makefile. - running a local development server (
-
A repo updates its policy files with one command:
make update-policy. It runsscript/update-policy, which fetches each vendored file the repo carries from thepromptsrepo, commits them and pushes. It uses the head ofmain, or the commit given by a full hash:script/update-policy <hash>. The list of vendored files is at the top of that script. The script replaces each file and keeps only the repo's own entries:- in
.gitignore,.editorconfigand.dockerignore: the lines below the comment that ends the canonical file - in
.golangci.yml: the entries the repo added to thedenylist of thetest-supportdepguard rule
- in
Tests and checks
-
All repos with software must have tests that run via the platform-standard test framework (
go test,pytest,jest/vitest, etc.). There is no excuse formake testto be a no-op. If no meaningful tests exist yet, add the most minimal one: importing the module under test to verify it compiles/parses, for example. -
make testmust complete in under 60 seconds. That is the hard cap, and a suite that exceeds it fails. Under 20 seconds is the target. A suite between 20 and 60 seconds is still green, but the overage must be filed as an improvement bug against that repo. -
Add a 90-second timeout to the test invocation (
go test -timeout 90s). This backstop sits above the hard cap on purpose: it catches a hung test, not a merely slow one.-timeoutapplies to each package, so several hung packages can each use it. -
Docker builds must complete in under 5 minutes.
-
make checkmust not modify any files in the repo. Tests may use temporary directories. -
mainmust always passmake check, no exceptions. -
The test command should use the conditional verbose rerun pattern. Run tests without
-v(verbose) first. If they fail, rerun automatically with-v. Success then leaves CI logs anddocker buildoutput clean, with just package/suite summaries. Failure shows every test case and every assertion.- The rerun always ends in
exit 1. The first run already proved the tests are broken, so the build must not pass even if a flaky test succeeds on the second attempt. The rerun exists solely for diagnostic output. - A first run that timed out gets no rerun, which would only wait for the same hang. A hung package therefore uses the 90-second backstop once.
The command lives in the
testphase of theDockerfile, sincescript/testbuilds that phase.examples/go.Dockerfileandexamples/python-test-phase.Dockerfilein thepromptsrepo carry it. The Makefile form below is the same pattern for any repo-local invocation. In a Makefile, each$of those two commands is written$$.test: @<test-command> || \ { echo "--- Rerunning with -v for details ---"; \ <test-command-with-v>; exit 1; } - The rerun always ends in
script/bootstrap
script/bootstrapinstalls all dependencies idempotently and assumes nothing is present.- A tool from the distribution has no pin, so it is installed only when it is missing. make, git, node and yarn are such tools. They come from nix, apt, brew, or apk, detected in that order; apt runs noninteractive.
- A tool from outside the distribution is never installed as "latest" or "lts"; it is always an exact version.
node and yarn
-
Use
yarn, notnpm.script/bootstrapinstalls node, yarn and the node packages only whenyarn.lockis in the tree. ADockerfilestage that needs no yarn copies noyarn.lockbefore it runsscript/bootstrap, soscript/bootstrapinstalls no node and no yarn there. The stages in thepromptsrepo'sexamples/go.Dockerfileandexamples/python-test-phase.Dockerfileare such stages.script/bootstrapinstalls the node packages withyarn install --immutable, which fails when a package'schecksumis wrong, or whenpackage.jsonis out of step withyarn.lock.Each repository commits the yarn that runs.
yarnPathin.yarnrc.ymlpoints at the release file in.yarn/releases/. The distribution's yarn only starts that file, and that file does the work. So Alpine's yarn 1 and Debian 13's yarn 4.1 run the same committed yarn. Corepack never runs, and no yarn is downloaded..yarnrc.ymlholdsyarnPath,nodeLinker: node-modulesandenableTelemetry: false. Without the last, yarn sends usage reports from any host that is not CI.By default, yarn runs no dependency's install script. A dependency that must run one is named in
package.json, as"dependenciesMeta": { "<name>": { "built": true } }..gitattributescarries.yarn/releases/** binary, so diffs and merges treat the release file as one opaque file.yarn 1 ignores
--immutableand exits 0, so on a tree with no.yarnrc.ymlthe install is not frozen. A repository therefore re-vendorsscript/bootstrapand converts itsyarn.lockin one commit.Debian and Ubuntu name the yarn command
yarnpkg.script/bootstrap,script/fmtandscript/fmt-checkeach carry the same small function that runs whichever name is present. With neither name onPATH,script/fmtandscript/fmt-checkprint one line saying to runscript/bootstrap, and exit 1.A
Dockerfilestage that needs yarn may start from any distribution that packages node and yarn. Before it runsscript/bootstrap, it copiespackage.json,yarn.lock,.yarnrc.ymland.yarn/releases/. With only the first two, the install fails, and Alpine's yarn 1 says to enable corepack. Never do that; copy the missing files instead.
Pinned tools
-
script/bootstrapinstalls a pinned tool by comparing versions, never by testing presence. Anif ! command -v <tool>; then install; figuard testsPATHonly. On an already-provisioned machine the pin is then inert, and a version bump is a silent no-op. The Dockerfile's clean image still gets the pinned version, so a localmake checkandmake dockercan disagree about what the tool even is. The canonical form:-
compares the installed version against the pin over the whole version token. A parser that stops at the first
-reports2.12.2for a host running2.12.2-rc1and skips the install. -
treats
--versionoutput as a mismatch when it is any of these:- absent
- non-zero
- empty
- unrecognised
So a failure causes a redundant install, never a skipped one.
-
after installing, re-resolves the binary the way callers do:
hash -r, thenPATH, not the directory the installer wrote to. A shadowing binary can hide an install that reported success. In that case it fails and names the resolved path. -
is actually called, and prints the version on both success paths. A function defined and never invoked has the same exit status and the same empty output as one that worked.
-
stays POSIX sh: no arrays, no
[[, nogrep -P.
A Go tool a repo needs on the host is installed with
go installpinned to a commit hash (go install <package>@<commit hash>). It is never tracked as ago.modtool dependency or through atools.gofile, either of which pulls the tool's own dependencies into the repo'sgo.modandgo.sum. -
Dockerfile
-
Every repo should have a
Dockerfile, and it carries the repo's gates: alintphase and atestphase. The final stage depends on both, so the image cannot be built unless they pass. For non-server repos the final stage brings up a development environment; for server repos it is the runtime image. The gate phases and the build stage start from their pinned base images and install what those images lack in either of these ways:- inline, as the
promptsrepo'sexamples/go.Dockerfiledoes forgit - by running
script/bootstrap, as thepromptsrepo's ownDockerfiledoes for its yarn packages
The development environment stage installs development prerequisites by running
script/bootstrap. Only system packages may be installed inline above it, so that check builds keep them; thepromptsrepo's ownDockerfiledoes this. A stage that runsscript/bootstrapCOPYsscript/and the dependency manifests it needs before running it:go.modandgo.sum, for example, or the four yarn files named above. - inline, as the
-
The lint and test gates run in Docker, as phases of the
Dockerfile. There is no separate lint file.script/lintandscript/testeach build one phase and nothing else:docker build --target lint --output type=cacheonly . docker build --target test --output type=cacheonly .A stage that is not the last one in the file is built only when the final stage's chain depends on it, or when
--targetnames it. That is why the two gates are always invoked by name here, and why the final stage carries aCOPY --from=of a harmless file from each of them. Without those copies, a plaindocker build .builds the last stage's chain alone and exits 0 having linted and tested nothing. Keep the stage that ships last: the runtime image, or the development environment in a non-server repo. If you add a stage after it, give it the same two copies.The gate builds write no image. With
--output type=cacheonlythe phase runs and a failing step fails the build, but the result is not exported. Nothing uses those images, and writing one out is slow. A build given neither--outputnor-tleaves an untagged image dangling on every developer host and CI runner.script/cibuildandscript/dockertag the image that ships, so each build replaces the previous image.script/checkbuilds no image of its own.Inside a phase the tool is invoked directly:
golangci-lint,go test,eslint,prettier. It is never invoked throughmake lintorscript/test, which are themselves adocker buildand would recurse into a daemon that does not exist in a build step.Formatting is the exception and stays on the host.
script/fmtwrites the working tree, andscript/fmt-checkis its read-only twin.No lint verdict may come from a host invocation of the linter. On a shared host golangci-lint reads a result cache keyed on file content rather than location. A second checkout of the same content is therefore served the first one's findings. A host-global lock in
$TMPDIRalso makes concurrent runs exit non-zero withparallel golangci-lint is running, which a caller cannot tell from real findings. A container has its ownTMPDIR, out of the lock's reach. The lint phase does keep golangci-lint's cache between check builds, but it lints every checkout at/src. It reuses a finding only on the conditions listed under the canonical GoDockerfilebelow. -
Check builds use Docker's normal cache. On an unchanged tree Docker reuses each step's stored result, and it stores a result only for a step that succeeded. A step runs again when one of these changes:
- the base image
- its own line or a line above it
- the files copied before it
Nothing needs to run again on an unchanged tree. Never prune the build cache (
docker builder pruneand the like): it is shared with every other build on the host. When a check is added or changed, prove it works:- plant a defect it must catch
- watch the run fail on it
- revert the defect
A green run alone shows neither that the check ran nor that it covers what it should.
-
The gate phases are separate stages, and the build stage depends on both. The lint phase is based on the
golangci/golangci-lintimage (pinned by hash), so lint failures surface in seconds rather than after a full compile. The test phase is based on the Debian Go image. The canonical Go repoDockerfileis athttps://git.eeqj.de/sneak/prompts/raw/branch/main/examples/go.Dockerfile.Key points:
- The lint phase uses the
golangci/golangci-lintimage directly, so nothing needs installing: it has both Go and the linter. COPY --from=<phase> /src/go.sum /dev/nullis a no-op copy whose only purpose is the dependency on that phase. BuildKit runs stages in parallel by default, and a stage nothing depends on is not built at all. Without these two lines a red gate would not fail the build.- Keep the runtime stage last. If you add a stage after it, give it the same
two copies. A plain
docker build .builds the last stage's chain and nothing else. - Check builds keep these, and none of them can hand back a stale result:
- The layers of the system packages and Go's modules. Docker installs
the packages again when the base image or the install line changes.
Docker downloads the modules again when
go.modorgo.sumchanges. Go checks every module againstgo.sumas it downloads it, and no later build can change a kept layer. The modules are kept in a layer rather than a cache mount. A cache mount is shared by every build on the host, and Go builds from whatever files the mount holds without checking them again (onlygo mod verifydoes). A file changed there would go unnoticed. - Go's build cache (
/root/.cache/go-build, where Go keeps it for root), mounted on the steps that compile:golangci-lint run, bothgo testruns andgo build. Go reuses a compiled package only when all its inputs are unchanged. The cache also holds test results, which is why bothgo testruns carry-count=1. - golangci-lint's cache (
/root/.cache/golangci-lint, where the pinned image keeps it), mounted ongolangci-lint run. golangci-lint reuses a package's findings only when all of these are unchanged:- the package's files and those of every package it imports
go.mod- the linters and their settings in
.golangci.yml - the golangci-lint version
- In a Python
testphase, the layer of the step that runsscript/bootstrapto install the packages fromPipfile.lock, as described for that phase below.
- The layers of the system packages and Go's modules. Docker installs
the packages again when the base image or the install line changes.
Docker downloads the modules again when
- If the project uses
//go:embeddirectives that reference build artifacts, the lint phase must create placeholder files so the embed directives resolve. A web frontend compiled in a separate stage is such an artifact. Example:RUN mkdir -p web/dist && touch web/dist/index.html web/dist/style.css. - If the project requires CGO or system libraries for linting, install them
in the lint phase. The
golangci/golangci-lintimage is Debian-based and has noapk. So install withapt-getunder the Debian package name (libvips-dev, where alpine saysvips-dev), and delete the package lists in the sameRUN, so the layer does not keep them. The test phase, on the Debian Go image, installs the libraries its tests need the same way. Either install goes right afterFROM, so Docker keeps it until the base image or the install line changes. The first lines of a lint phase that installs system libraries are athttps://git.eeqj.de/sneak/prompts/raw/branch/main/examples/go-lint-system-libraries.Dockerfile.
Go example:
test: @status=0; \ output=$$(go test -count=1 -timeout 90s -race -cover ./... 2>&1) || status=$$?; \ printf '%s\n' "$$output"; \ test "$$status" -eq 0 && exit 0; \ case "$$output" in \ *"panic: test timed out"*|*"*** Test killed"*) exit 1 ;; \ esac; \ echo "--- Rerunning with -v for details ---"; \ go test -count=1 -timeout 90s -race -v ./...; \ exit 1The first run's output is kept so that the recipe can look in it for what Go prints for a hang:
panic: test timed outmeans the test's own timer fired.*** Test killedmeansgo teststopped a test that ignored that timer, about a minute later.
Go prints the goroutine stacks with either line, as long as the test can still respond. A rerun would only wait for the same hang, so the recipe exits 1. A failure with neither line in its output reruns with
-v. The kept output prints when the first run ends, not while it runs.-count=1is required on both invocations. It defeats Go's test result cache, so neither run can report a stored pass in place of running the tests. It leaves the build cache alone, so it costs the runtime of the suite and no recompilation.That cache is Go's own, separate from Docker's layer cache. Go stores a passing result in its cache directory (
GOCACHE). When the same tests run again on unchanged code, it prints that result, marked(cached), without running them. The directory lasts from one run to the next on a developer's machine, where this target runs. The directory also lasts in thetestphase of theDockerfile, which mounts it to keep compiled packages between check builds, so the phase'sgo testruns carry-count=1too. - The lint phase uses the
-
A Python
testphase that installs its packages fromPipfile.lockdoes it beforeCOPY . ., so check builds keep them. The steps are:COPY script/ script/COPY Pipfile Pipfile.lock ./RUN script/bootstrap
Docker keeps what that
RUNinstalled until one of these changes:- the base image
script/PipfilePipfile.lock- a line up to and including the
RUN
The tests run after
COPY . ..-
When
script/bootstrapruns in that step, it installs nothing beyond these:- system packages
- pipenv and its dependencies
- the packages from
Pipfile.lock
script/bootstrapinstalls no Python there: the tests use the distribution's Python, which a step above it installs. -
Debian's Python refuses a system-wide
pip install, so pipenv goes in a virtual environment at$HOME/.pipenv.script/bootstrapcreates it withpython3 -m venvwhen it is missing, then uses that environment'spipandpipenv. On a host, it first installs the distribution's python and venv packages when they are missing. One script then works on a host and in aDockerfile.Pipfilenames nopython_version, becausepipenv install --deploystops when the distribution's Python differs from it. -
PyPI is not trusted, so
script/bootstrapinstalls pipenv and its dependencies by hash. It does so withpip install --require-hashes -rand a requirements file inscript/that lists each of them with==and its--hash. pip refuses to install a dependency the file does not list. -
script/bootstrapthen runspipenv install --deploy, with--devwhen the tests need the development packages.--deploydoes all of these:- installs only what
Pipfile.locknames - checks every package against the lockfile's hashes
- fails when the lockfile is out of date with
Pipfile
- installs only what
-
script/bootstrapsetsPIP_ONLY_BINARY=:all:for both installs, and pipenv passes it on to pip. A package with no ready-built wheel for the image then stops the install. Without the setting, pip builds that package from source and downloads the build tools without a hash check. -
A kept layer holds nothing a new install would refuse: pip checked the hashes of pipenv and its dependencies, and pipenv checked the hashes of the lockfile's packages. pipenv creates its virtual environment with the
virtualenvpackage. The packages thatvirtualenvadds come from wheels inside that package, so the hash pip checked for it covers them. System packages, Python among them, are not fixed by a hash. They keep the versions the package manager gave when the layer was built; a new install may get newer ones. -
As with Go's modules, the packages are kept in a layer, not a cache mount. A cache mount is shared by every build on the host, and nothing checks its files again.
A Python repository's
script/bootstrapadds these lines inmain, above the lastecho. Theensurepiptest fails when python is missing, and also when Debian's venv package is missing:if [ ! -x "$HOME/.pipenv/bin/pip" ]; then if ! python3 -m ensurepip --version >/dev/null 2>&1; then pkg_install python3 python3-venv python3 python3 fi python3 -m venv "$HOME/.pipenv" fi export PIP_ONLY_BINARY=:all: "$HOME/.pipenv/bin/pip" install --require-hashes -r script/requirements.txt "$HOME/.pipenv/bin/pipenv" install --dev --deployMake
script/requirements.txtonce, withecho pipenv | pip-compile --generate-hashes --allow-unsafe -o script/requirements.txt -.pip-compilecomes from Alpine'spy3-pip-toolspackage; Debian and Ubuntu do not packagepip-tools. Make the firstPipfile.lockwith$HOME/.pipenv/bin/pipenv lock, after thepip installline has installed pipenv.In
examples/python-test-phase.Dockerfile,script/bootstrapfindsmake,git, python and venv already installed. The example copies noyarn.lock, soscript/bootstrapinstalls no node and no yarn. The Pythontestphase example is athttps://git.eeqj.de/sneak/prompts/raw/branch/main/examples/python-test-phase.Dockerfile.Python example:
test: @timeout 90 sh -c 'pipenv run pytest || { \ echo "--- Rerunning with -v for details ---"; \ pipenv run pytest -v; exit 1; }'Both pytest runs share that one 90-second timeout, as in the
promptsrepo'sexamples/python-test-phase.Dockerfile, so a hang uses it once and gets no rerun. Ctrl-C does not stop a runningmake test, which goes on until the tests end or the 90 seconds run out. On a Mac withouttimeout, the target fails until it is installed. On a host, the target needs$HOME/.pipenv/binonPATH. -
A plain
docker build .of a clone stamps the version thatgit describe --tags --alwaysgives. The version is derived from the.gitin the build context, as thepromptsrepo'sexamples/go.Dockerfileshows. Without its failure check, a missinggitor an unreadable checkout would leave-X main.Version=empty, and the build would still exit 0.script/dockerandscript/cibuildpass the version they compute on the host; it takes precedence. They do this byte-identically across repos:# The version and the tag each get their own line: a failing command # substitution inside an argument does not trip `set -e`, so the inline # form degrades to an empty constant. version="$(git describe --tags --always --dirty 2>/dev/null || true)" [ -n "$version" ] || version="unknown" tag="$(script/projectname)" docker build --build-arg VERSION="$version" -t "$tag" .--alwaysmakes an untagged repo yield an abbreviated commit hash rather than failing. The[ -n "$version" ]line is the single place the fallback is applied. That line is a live check that fires on a build from an export with no.git, and on a repository with no commits yet. Do not fold it into the substitution as|| echo unknown, which makes the guard unreachable. The Dockerfile's side isARG VERSIONin the stage that compiles, declared there becauseARGis stage-scoped. PassingVERSIONto a repo whose Dockerfile declares no suchARGis ignored and costs nothing, which is why the scripts stay byte-identical. One consequence for CI: the standard checkout action clones shallow and fetches no tags, so the canonical.gitea/workflows/check.ymlsetsfetch-depth: 0on its checkout step.-
.dockerignorelets.gitinto the build context. It keeps out every gitconfigat any depth (**/.git/config,**/.git/modules/**/config):- the repository's own
- each submodule's under
.git/modules/ - that of a submodule keeping its own
.gitdirectory
git describedoes not need them, and each can hold a credential: a password in a remote URL, or the token the CI checkout step stores there. Some submodule names have aconfigsegment, as inconfig,deploy/configorconfig/lib. Such a submodule loses its whole git directory to**/.git/modules/**/config, and Go's version stamping then fails the build. Give it a name without that segment (git submodule add --name). The stage that compiles hasgit: the Debian Go image has it, and an alpine one needsapk add --no-cache git. That stage takes the version from theVERSIONbuild argument when one is given, otherwise fromgit describe --tags --always. That gives:- the tag, on a tagged commit
- the tag, the number of commits since it and the short commit
(
v1.2.3-4-gabc1234), on a later commit - the short commit, when no tag is reachable
The stage that compiles also marks its working directory safe for git (
git config --system --add safe.directory /src). A context sent as a tar stream keeps the sender's file owners, and git refuses a checkout owned by another user, so the version would come out empty.ARG VERSIONhas no default. The build fails if the context carries.gitand the version still comes out empty,devorunknown. A plaindocker build .with no build arguments must succeed; a Dockerfile that refuses an empty build argument drops that refusal and keeps the argument. A checkout whose.gitis a file is the exception: a linked worktree, or a repository checked out as a submodule. That file points to a git directory outside the build context, so the build cannot read the version and a plaindocker build .fails. Pass the version with--build-arg VERSION=..., asscript/dockerandscript/cibuildalready do.
-
-
Every repo should have a Gitea Actions workflow (
.gitea/workflows/) that runsscript/cibuildon push. The workflow's only other step checks out the repo, withpersist-credentials: false.script/cibuildneeds no token, and without that setting the checkout leaves the job's token in.git/configfor every later step. The checkout step also setsfetch-depth: 0, which fetches the tagsgit describeneeds. By default it clones shallow with no tags, and a tagged repository's CI build would stamp a bare short commit id. The workflow'sconcurrencyblock groups runs by workflow and branch (${{ github.workflow }}-${{ github.ref }}) withcancel-in-progress: true. A new push then cancels the older run on the same branch, queued or running, and no other: runs for replaced commits do not hold up the shared runner.script/cibuildbootstraps, runs the gate phases, and then builds the image, so a successful run means every check passed. The image build reuses the gate phases that the check has just built. Thecheckjob setstimeout-minutes: 20, so a hung build frees the shared runner after 20 minutes. That allows for the three Docker builds described above, each held to the 5-minute Docker build limit below, plus the bootstrap. Those builds are the test phase, the lint phase, then the image. A separate workflow limited tomainby abrancheslist underon: pushcannot be checked by review. To try a change to it, add the feature branch to that list and push, then remove the branch from the list again before merging. Keep any job in it that publishes behindif: github.ref_name == 'main', so the run from the feature branch publishes nothing.script/cibuildruns the CI build, and the Gitea workflow calls it. The script changes to the repo root, runsscript/bootstrap, runsscript/check, and builds the image with the version.script/cibuildrunsscript/bootstrapfirst, because the workflow checks out the repo and runs nothing else, whilescript/fmt-checkruns the formatter on the host. On a pristine checkout with nothing installed, the run dies there, after the containerised gates have passed. -
.gitignoreshould be comprehensive from the start:- OS files (
.DS_Store) - editor files (
.swp,*~) - in-repo agent scratch directories (
.claude/) node_modules/.yarn/*, with!.yarn/releasesso that git keeps yarn's release file- the repo's own build outputs
Fetch the standard
.gitignorefromhttps://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignorewhen setting up a new repo. A repo's.gitignoreis the standard file followed by the repo's own entries, such as its binaries. A re-vendor replaces the standard part and keeps those entries. These patterns are written to.gitignore's own semantics, in which an unanchored pattern already matches at every depth. They are not a.dockerignoreand must not be transplanted into one unmodified. - OS files (
-
.dockerignoredoes not use.gitignoresemantics, and copying patterns across unmodified leaves secrets in the build context. Docker matches withmoby/patternmatcher:filepath.Matchsemantics plus a**extension. So*does not cross/, and a pattern without a leading**/is anchored at the build-context root. A.dockerignorelisting.env,*.pemand*.keytherefore excludes only the copies at the repository root.config/.envandcerts/server.keystill reach the context and can land in an image layer. Such a.dockerignoreis more dangerous than a short file with no secret patterns at all, because it reads as solved and stops anyone looking. Give every depth-independent pattern the**/prefix, and leave only genuinely root-anchored entries unprefixed. Those are.claude,.yarn/*,!.yarn/releases, and the repo's own host-built binary. The binary is written/myappand never**/myapp, which would also matchcmd/myapp/and delete the package directory from the context. Matching is case-sensitive, and an all-caps copy of each pattern still missesServer.Key. So secret names use character ranges:**/*.[kK][eE][yY],**/*.[pP][eE][mM], and likewise for.envrcand the extensionless SSH keys. Where such a pattern also catches something the build needs, re-include it with a negation (!docs/example.env). Deleting the pattern reopens the exposure for every other file it covers. Fetch the standard.dockerignorefromhttps://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignoreand extend it with the repo's own artifacts. -
In-repo agent scratch belongs in both files, written to each file's own semantics.
.claude/holds one worktree per in-flight agent, an entire additional checkout of the repo. UnderCOPY . .the build context therefore inflates by a multiple of the repo, and another session's unreviewed work can be copied into an image layer. In.gitignorethe entry is.claude/, unanchored. In.dockerignoreit is.claude, anchored and with no**/prefix, because the prefixed form would also delete any nested directory of that name from the build. Anchoring carries a known gap. The canonical.dockerignorestates the gap in its own comment, since consuming repos receive the file and not the tracker. The gap is that the directory is created in the agent's working directory. A repo running agents in subdirectories therefore still shipsservices/api/.claude/and must add its own anchored entry there. -
Verify
.dockerignoreby enumerating the image, not by reading the patterns. Plant files at the root and at least two directories deep. Build a probe image that doesCOPY . ., and list what actually landed (docker run --rm --entrypoint find IMAGE /app). Thetransferring contextsize is not a substitute: a nested secret is a few bytes, and BuildKit transfers only the delta from the previous build. -
.golangci.ymlis standardized. The vendored copy in a consuming repo must NEVER be modified by an agent. Fetch it fromhttps://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.ymland keep it byte-identical, so that no repo can quietly loosen its own linting. Linter configuration changes are made to the canonical copy in thepromptsrepo and reach consuming repos by re-vendoring. An agent may open a PR against canonical, which only the user merges. One list is exempt from byte-identity, because it cannot be written once for every repo: thedenylist of thetest-supportdepguard rule. There a repo names its own test-support packages by full import path. A repo adds entries there and changes nothing else, and a re-vendor carries its entries forward. The canonical golangci-lint version is v2.15.0 (released 2026-10-16). The version is pinned as the digest of the lint phase's base image,golangci/golangci-lint@sha256:fbfcfd12a6f8d7f1b97b3362ca80fc2a244d46863148c73cb88e7793af96c481, which reports2.15.0 built with go1.27.0 from 25c5369a. A module'sgodirective must not name a newer Go minor version than the one golangci-lint was built with, or golangci-lint refuses to lint it. This release lintsgo 1.27.1but notgo 1.28. That digest is the only pin, since no repo installs golangci-lint on the host. A repo sets the lint phase digest to the one named here and re-vendors.golangci.ymlin the same commit, whichever of the two prompted the change. The canonical copy can name linters that an older golangci-lint rejects. A newer golangci-lint can add linters thatdefault: allswitches on until the canonical copy disables them. -
Use platform-standard formatters:
blackfor Pythonprettierfor JS/CSS/Markdown/HTMLgofmt, thengolines -m 77, for Go
Always use default configuration, with three exceptions:
- four-space indents (except Go)
proseWrap: alwaysfor Markdown (hard-wrap at 80 columns)- a 77-column limit for Go, set by
golines -m 77
script/fmtrunsgofmtand thengolines -m 77on Go code.script/fmt-checkfails when either of them would change a file.golinescomes fromgithub.com/segmentio/golines.script/bootstrapinstalls it withgo install, pinned to a commit hash as below:# golines v0.13.0, 2025-08-21 go install github.com/segmentio/golines@8f32f0f7e89c30f572c7f2cd3b2a48016b9d8bbfscript/bootstrapreads the installed version from themodline ofgo version -m "$(command -v golines)", which reportsv0.13.0. It does not usegolines --version, which printsgolines vdevfor a binary thatgo installbuilt.golinescannot shorten every line: long string literals and comments stay as they are. golangci-lint'sllllimit therefore stays at 88 columns, so it fails only lines far past the formatter's limit.Documentation and writing repos (Markdown, HTML, CSS) should also have
.prettierrcand.prettierignore. -
All repos should have an
.editorconfigenforcing the project's indentation settings. It is the standard file fromhttps://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig, followed by the repo's own sections, such as one for another language it uses. The standard file sets tabs forMakefileand Go files. A re-vendor replaces the standard part and keeps those sections. -
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) withmax-ageof at least one year andincludeSubDomains.Content-Security-Policy(CSP) with a restrictive default policy (default-src 'self'as a baseline, tightened per-resource as needed). Never useunsafe-inlineorunsafe-evalunless unavoidable, and document the reason.X-Frame-Options: DENY(orSAMEORIGINif framing is required). Prefer theframe-ancestorsCSP directive as the primary control.X-Content-Type-Options: nosniff.Referrer-Policy: strict-origin-when-cross-origin(or stricter).Permissions-Policyrestricting 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).
ReadTimeoutandReadHeaderTimeouton thehttp.Serverto defend against slowloris attacks.WriteTimeouton thehttp.Server.IdleTimeouton thehttp.Server.- Per-handler execution time limits via
context.WithTimeoutor chi/stdlibmiddleware.Timeout.
- Maximum request body size enforced on all endpoints (e.g. Go
-
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
Authorizationheader (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, andSameSite=Lax(orStrict) 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 trustX-Forwarded-Forunconditionally.
- True client IP detection when behind a reverse proxy
(
-
CORS:
- Authenticated endpoints must restrict
Access-Control-Allow-Originto an explicit allowlist of known origins. Wildcard (*) is acceptable only for public, unauthenticated read-only APIs.
- Authenticated endpoints must restrict
-
Error handling:
-
Internal errors must never leak implementation details to the client. Those details include:
- stack traces
- SQL queries
- file paths
Return generic error messages in production; detailed errors only when
DEBUGis 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
Securecookie flags must still be set by the application so that the browser enforces HTTPS end-to-end.
- 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
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.
-
-
Database migrations live in
internal/db/migrations/and must be embedded in the binary.000_migration.sql— contains ONLY the creation of the migrations tracking table itself. Nothing else.001_schema.sql— the full application schema.- Pre-1.0.0: never add additional migration files (002, 003, etc.).
There is no installed base to migrate. Edit
001_schema.sqldirectly. - Post-1.0.0: add new numbered migration files for each schema change. Never edit existing migrations after release.
-
README.mdis the primary documentation. Required sections:-
Description: First line must include:
- the project name
- purpose
- category (web server, SPA, CLI tool, etc.)
- license
- 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 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 the todo list in the README so a new agent can pick up where the last one left off.
-
License: MIT, GPL, or WTFPL. Ask the user for new projects. Include a
LICENSEfile in the repo root and a License section in the README. -
Author: @sneak.
-
-
Avoid putting files in the repo root unless necessary. Root should contain only project-level config files:
README.mdAGENTS.mdMakefileDockerfileLICENSE.gitignore.editorconfigREPO_POLICIES.md- language-specific config
Everything else goes in a subdirectory. Canonical subdirectory names:
bin/— executable scripts and toolscmd/— Go command entrypoints; thin only: onemain.goper binary whose body is a single call intointernal/orpkg/, no project logic incmd/configs/— configuration templates and examplesdeploy/— deployment manifests (k8s, compose, terraform)docs/— documentation and markdown (README.md stays in root)internal/— Go internal packagesinternal/db/migrations/— database migrationspkg/— Go library packagesshare/— systemd units, data filesstatic/— static assets (images, fonts, etc.)web/— web frontend source
-
Guidance for coding agents lives in one
AGENTS.mdat the repository root. It is never committed under a file or directory named after one agent tool, such asCLAUDE.mdor.claude/, and never split into separate memory files. -
New repos must contain at minimum:
README.md,.git,.gitignore,.editorconfigLICENSE,REPO_POLICIES.md(copy from thepromptsrepo)Makefilescript/entrypoints (bootstrap,setup,projectname,test,lint,fmt,fmt-check,check,docker,cibuild,precommit,install-precommit,update-policy)Dockerfile,.dockerignore.gitea/workflows/check.yml- Go:
go.mod,go.sum,.golangci.yml - JS:
package.json,yarn.lock,.yarnrc.yml,.yarn/releases/,.gitattributes,.prettierrc,.prettierignore - Python:
pyproject.toml
-
When setting up a new repo, files from the
promptsrepo may be used as templates. Fetch them fromhttps://git.eeqj.de/sneak/prompts/raw/branch/main/<path>. -
First commit of a new repo should contain only
README.md. -
Write all dates as YYYY-MM-DD (ISO 8601).
-
Cross-project documentation (such as this file) must include
last_modified: YYYY-MM-DDin the YAML front matter so it can be kept in sync with the authoritative source as policies evolve. -
Use SemVer.
-
Go module root:
sneak.berlin/go/<name>. Always rungo mod tidybefore committing. -
Simple projects should be configured with environment variables.