prompts/prompts/REPO_POLICIES.md

title, last_modified

title	last_modified
Repository Policies	2026-08-09

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

---

• Cross-project documentation (such as this file) must include last_modified: YYYY-MM-DD in the YAML front matter so it can be kept in sync with the authoritative source as policies evolve.

• ALL external references must be pinned by cryptographic hash. This includes Docker base images, Go modules, npm packages, GitHub Actions, and anything else fetched from a remote source. Version tags (@v4, @latest, :3.21, etc.) are server-mutable and therefore remote code execution vulnerabilities. The ONLY acceptable way to reference an external dependency is by its content hash (Docker @sha256:..., Go module hash in go.sum, npm integrity hash in lockfile, GitHub Actions @<commit-sha>). No exceptions. This also means never curl | bash to install tools like pyenv, nvm, rustup, etc. Instead, download a specific release archive from GitHub, verify its hash (hardcoded in the Dockerfile or script), and only then install. Unverified install scripts are arbitrary remote code execution. This is the single most important rule in this document. Double-check every external reference in every file before committing. There are zero exceptions to this rule.

• Every repo with software must have a root Makefile with these targets: make bootstrap, make setup, make test, make lint, make fmt (writes), make fmt-check (read-only), make check (runs test, lint, fmt-check), make docker, and make hooks (installs pre-commit hook). A model Makefile is at https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile.

• Repos follow the 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 and runs docker build --build-arg CHECK_EPOCH="$epoch" ., where epoch is a per-invocation nonce (see the CHECK_EPOCH 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 source of truth for how these operations are run.

• 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, or anything else a developer would do regularly. If someone checks out the repo and types make<tab>, they should see every meaningful operation available. A new contributor should be able to understand the entire development workflow by reading the Makefile.

• Every repo should have a Dockerfile. All Dockerfiles must run make check as a build step so the build fails if the branch is not green. For non-server repos, the Dockerfile should bring up a development environment and run make check. For server repos, make check should run as an early build stage before the final image is assembled. Dockerfiles install development prerequisites by running script/bootstrap rather than duplicating installs inline; COPY script/ and the dependency manifests (package.json + yarn.lock, go.mod + go.sum, etc.) before running it so the bootstrap layer stays cached until dependencies change.

• Every 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 RUN make 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. The canonical form, in every stage containing a check-running RUN:

  ARG CHECK_EPOCH
  RUN [ -n "$CHECK_EPOCH" ] || exit 1
  RUN echo "check epoch: ${CHECK_EPOCH}" && make check
  

  and in both script/cibuild and script/docker:

  epoch="$(date +%s%N)$$"
  docker build --build-arg CHECK_EPOCH="$epoch" .
  

  All four 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 (observed as RUN [ -n "1786287053..." ] || 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 also works but is wasteful and can blow that ceiling.

• Dockerfiles must use a separate lint stage for fail-fast feedback. Go repos use a multistage build where linting runs in an independent stage based on the golangci/golangci-lint image (pinned by hash). This stage runs make fmt-check and make lint before the full build begins. The build stage then declares an explicit dependency on the lint stage via COPY --from=lint /src/go.sum /dev/null, which forces BuildKit to complete linting before proceeding to compilation and tests. This ensures lint failures surface in seconds rather than minutes, without blocking on dependency download or compilation in the build stage.

  The standard pattern for a Go repo Dockerfile is:

  # Lint stage — fast feedback on formatting and lint issues
  # golangci/golangci-lint:v2.x.x, YYYY-MM-DD
  FROM golangci/golangci-lint@sha256:... AS lint
  WORKDIR /src
  COPY go.mod go.sum ./
  RUN go mod download
  COPY . .
  ARG CHECK_EPOCH
  RUN [ -n "$CHECK_EPOCH" ] || exit 1
  RUN echo "check epoch: ${CHECK_EPOCH}" && make fmt-check
  RUN make lint
  
  # Build stage
  # golang:1.x-alpine, YYYY-MM-DD
  FROM golang@sha256:... AS builder
  WORKDIR /src
  
  # Force BuildKit to run the lint stage before proceeding
  COPY --from=lint /src/go.sum /dev/null
  
  COPY go.mod go.sum ./
  RUN go mod download
  COPY . .
  ARG CHECK_EPOCH
  RUN [ -n "$CHECK_EPOCH" ] || exit 1
  RUN echo "check epoch: ${CHECK_EPOCH}" && make test
  
  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:

  • The lint stage uses the golangci/golangci-lint image directly (it includes both Go and the linter), so there is no need to install the linter separately.
  • COPY --from=lint /src/go.sum /dev/null is a no-op file copy that creates a stage dependency. BuildKit runs stages in parallel by default; without this line, the build stage would not wait for lint to finish and a lint failure might not fail the overall build.
  • If the project uses //go:embed directives that reference build artifacts (e.g. a web frontend compiled in a separate stage), the lint stage must create placeholder files so the embed directives resolve. Example: RUN mkdir -p web/dist && touch web/dist/index.html web/dist/style.css. The lint stage should not depend on the actual build output — it exists to fail fast.
  • If the project requires CGO or system libraries for linting (e.g. vips-dev), install them in the lint stage with apk add.
  • The build stage runs make test after compilation setup. Tests run in the build stage, not the lint stage, because they may require compiled artifacts or heavier dependencies.
  • ARG CHECK_EPOCH appears in both stages, because ARG is stage-scoped: declaring it only in the lint stage leaves make test frozen at the last cached result. In each stage the guard sits immediately below the ARG so a bare docker build . fails instead of reusing the empty cache key, and the value is expanded into the first check RUN so the cache miss does not rely on BuildKit's unreferenced-ARG handling. Both of those lines reference $CHECK_EPOCH, so both are value-keyed: each stage is invalidated at two independent points. The later RUNs in the same stage need no expansion of their own: they are already invalidated by their busted parent layer.

• Every repo should have a Gitea Actions workflow (.gitea/workflows/) that runs script/cibuild (which runs docker build --build-arg CHECK_EPOCH="$epoch" .) on push. The Dockerfile runs make check, so a successful build implies all checks pass — but that implication holds only because of the CHECK_EPOCH cache-bust described above. Without it, an unchanged tree serves the check layer from cache and the build reports a green it never earned. A bare docker build . fails closed by design, on the [ -n "$CHECK_EPOCH" ] guard; always go through script/cibuild or script/docker. Never accept a script/cibuild pass as evidence without confirming it ran: a sub-second wall time, or CACHED on the check 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 two exceptions: four-space indents (except Go), and proseWrap: always for Markdown (hard-wrap at 80 columns). Documentation and writing repos (Markdown, HTML, CSS) should also have .prettierrc and .prettierignore.

• Pre-commit hook: runs script/precommit, which calls script/check. If local testing is not possible in the repo, script/precommit may skip script/test 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 tests exist yet, add the most minimal test possible — e.g. importing the module under test to verify it compiles/parses. There is no excuse for make test to be a no-op.

• make test must complete in under 20 seconds. Add a 30-second timeout in the Makefile.

• make test 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:

  test:
  	@<test-command> || \
  		{ echo "--- Rerunning with -v for details ---"; \
  		  <test-command-with-v>; exit 1; }
  

  Go example:

  test:
  	@go test -timeout 30s -race -cover ./... || \
  		{ echo "--- Rerunning with -v for details ---"; \
  		  go test -timeout 30s -race -v ./...; exit 1; }
  

  Python example:

  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 directories.

• main must always pass make check, no exceptions.

• Never commit secrets. .env files, credentials, API keys, and private keys must be in .gitignore. No exceptions.

• .gitignore should be comprehensive from the start: OS files (.DS_Store), editor files (.swp, *~), language build artifacts, and node_modules/. Fetch the standard .gitignore from https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore when setting up a new repo.

• 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.

• Never force-push to main.

• Make all changes on a feature branch. You can do whatever you want on a feature branch.

• .golangci.yml is standardized and must NEVER be modified by an agent, only manually by the user. Fetch from https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml. The canonical golangci-lint version is v2.12.2 (released 2026-05-06), installed commit-pinned via go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@c0d3ddc9cf3faa61a4e378e879ece580256d76e5.

• When pinning images or packages by hash, add a comment above the reference with the version and date (YYYY-MM-DD).

• Use yarn, not npm.

• Write all dates as YYYY-MM-DD (ISO 8601).

• Simple projects should be configured with environment variables.

• 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 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 LICENSE file in the repo root and a License section in the README.
  • Author: @sneak.

• First commit of a new repo should contain only README.md.

• Go module root: sneak.berlin/go/<name>. Always run go mod tidy before committing.

• Use SemVer.

• 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.sql directly.
  • Post-1.0.0: add new numbered migration files for each schema change. Never edit existing migrations after release.

• All repos should have an .editorconfig enforcing the project's indentation settings.

• Avoid putting files in the repo root unless necessary. Root should contain only project-level config files (README.md, Makefile, Dockerfile, LICENSE, .gitignore, .editorconfig, REPO_POLICIES.md, and language-specific config). Everything else goes in a subdirectory. Canonical subdirectory names:

  • bin/ — executable scripts and tools
  • cmd/ — Go command entrypoints
  • configs/ — configuration templates and examples
  • deploy/ — deployment manifests (k8s, compose, terraform)
  • docs/ — documentation and markdown (README.md stays in root)
  • internal/ — Go internal packages
  • internal/db/migrations/ — database migrations
  • pkg/ — Go library packages
  • share/ — systemd units, data files
  • static/ — static assets (images, fonts, etc.)
  • web/ — web frontend source

• When setting up a new repo, files from the prompts repo may be used as templates. Fetch them from https://git.eeqj.de/sneak/prompts/raw/branch/main/<path>.

• New repos must contain at minimum:

  • 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
  • JS: package.json, yarn.lock, .prettierrc, .prettierignore
  • Python: pyproject.toml