REPO_POLICIES: move the example Dockerfiles into examples/

Each fenced dockerfile block moves byte for byte into its own file
under examples/, and one sentence links it where the block stood.
Phrases that pointed at a block by position now name the file. Both
checklists name the files. Rules keep their wording.

As #159 (comment) says.

Model: opus-5-5

examples/go.Dockerfile

@@ -0,0 +1,85 @@
+# In every stage ARG CACHEBUST comes right after the steps that install
+# system packages and download Go's modules, or right after FROM in a
+# stage with neither, and every step that lints, tests or compiles
+# comes after it. script/ passes a new value on every build, which
+# reruns every RUN step after it. Docker keeps the layers above it
+# until the base image, their own lines or go.mod and go.sum change.
+# The steps that compile mount Go's build cache, and golangci-lint run
+# also mounts golangci-lint's; both survive from build to build.
+
+# Lint phase
+# golangci/golangci-lint:v2.x.x, YYYY-MM-DD
+FROM golangci/golangci-lint@sha256:... AS lint
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+ARG CACHEBUST
+COPY . .
+RUN --mount=type=cache,target=/root/.cache/go-build \
+    --mount=type=cache,target=/root/.cache/golangci-lint \
+    golangci-lint run --config .golangci.yml ./...
+
+# Test phase. -race needs cgo and so a C compiler, which the Debian Go
+# image ships and the alpine one does not. -count=1 because the mounted
+# cache also holds test results, which go test would otherwise replay.
+# A first run that timed out gets no rerun, because a rerun would only
+# wait for the same hang.
+# golang:1.x, YYYY-MM-DD
+FROM golang@sha256:... AS test
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+ARG CACHEBUST
+COPY . .
+RUN --mount=type=cache,target=/root/.cache/go-build \
+    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 1
+
+# Build stage. Nothing is wanted from either phase above; the copies
+# are what make BuildKit build them first, so nothing after them can
+# run unless lint and test passed.
+# golang:1.x-alpine, YYYY-MM-DD
+FROM golang@sha256:... AS builder
+# git comes from the base image's own distribution package index, which
+# is trusted, so it needs no version and no hash.
+RUN apk add --no-cache git
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+ARG CACHEBUST
+COPY --from=lint /src/go.sum /dev/null
+COPY --from=test /src/go.sum /dev/null
+# A tar-stream context keeps the sender's file owners, which git refuses.
+RUN git config --system --add safe.directory /src
+COPY . .
+
+# The VERSION build arg when one is given, otherwise
+# `git describe --tags --always` on the .git in the build context. With
+# .git present, a version that is still empty, dev or unknown fails the
+# build: git is missing or could not read the checkout.
+ARG VERSION
+RUN --mount=type=cache,target=/root/.cache/go-build \
+    VERSION="${VERSION:-$(git describe --tags --always)}"; \
+    if [ -e .git ]; then \
+        case "$VERSION" in ""|dev|unknown) \
+            echo "version is '$VERSION' although .git is present" >&2; \
+            exit 1 ;; \
+        esac; \
+    fi; \
+    CGO_ENABLED=0 go build -trimpath \
+        -ldflags="-s -w -X main.Version=${VERSION}" \
+        -o /app ./cmd/app/
+
+# Runtime stage, and the last one
+FROM alpine@sha256:...
+ARG CACHEBUST
+COPY --from=builder /app /usr/local/bin/app
+ENTRYPOINT ["app"]