Adopt the scripts-to-rule-them-all layout and the canonical Docker gates

script/ holds the entrypoints and the Makefile targets shim to them.
Linting and testing are phases of the Dockerfile, built alone by
script/lint and script/test with a fresh CACHEBUST value and cache
mounts for Go's build cache and golangci-lint's; the build stage
depends on both, and the runtime stage ships the binary and the source
without .git. Formatting stays on the host in script/fmt and
script/fmt-check (gofmt and the prettier pinned in yarn.lock).
script/cibuild bootstraps, runs script/check and builds the tagged
image, and the Gitea workflow calls it. script/precommit refuses a
commit whose go.mod or go.sum is not tidy.

cgo stays off, so the test phase runs on the alpine Go image without
-race; that is the one departure from the canonical Go Dockerfile.

Re-vendored from the prompts repository's next branch: REPO_POLICIES.md
(2026-11-04), .golangci.yml (byte-identical, so the local
exhaustruct_v5 addition is gone now that canonical carries it),
.gitea/workflows/check.yml, .editorconfig, .gitignore and .dockerignore,
the last two followed by this repository's own entries. AGENTS.md holds
the repository-specific guidance for agents. The README gains the
Entrypoints section and describes the new gates.

Dockerfile

@@ -1,56 +1,95 @@
-# The checks behind `make check` are split across independent stages so that
-# formatting and lint failures surface in seconds, before any compilation:
+# 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    - gofmt and golangci-lint (make fmt-check-go, make lint)
-#   docs    - prettier check of all markdown (make fmt-check-md)
-#   builder - tests (make test) and the release build
-#
-# The builder stage declares explicit dependencies on lint and docs so
-# BuildKit cannot finish the build unless every check passed.
+# This repository keeps cgo off, so its test phase departs from the
+# canonical Go Dockerfile in REPO_POLICIES.md in one way: it runs on the
+# alpine Go image without -race, which needs a C toolchain. Everything
+# else follows the canonical file.
 
-# Lint stage: fast feedback on Go formatting and lint issues
-# golangci/golangci-lint:v2.15.0, 2026-10-16 (keep in sync with Makefile)
+# Lint phase
+# golangci/golangci-lint:v2.15.0, 2026-10-16
 FROM golangci/golangci-lint@sha256:fbfcfd12a6f8d7f1b97b3362ca80fc2a244d46863148c73cb88e7793af96c481 AS lint
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
+ARG CACHEBUST
 COPY . .
-RUN make fmt-check-go
-RUN make lint
+RUN --mount=type=cache,target=/root/.cache/go-build \
+    --mount=type=cache,target=/root/.cache/golangci-lint \
+    golangci-lint run --config .golangci.yml ./...
 
-# Docs stage: markdown formatting check with the pinned prettier
-# node:24-alpine, 2026-10-28
-FROM node@sha256:8a32c8cf649a49915a66e81e7a609223c708d0adabf288ee3f4077d765542f85 AS docs
-RUN apk add --no-cache make
-WORKDIR /src
-COPY package.json yarn.lock ./
-RUN yarn install --frozen-lockfile
-COPY . .
-RUN make fmt-check-md
-
-# Build stage
+# Test phase. -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.26-alpine, 2026-10-27
-FROM golang@sha256:a2012b4a1d1f9f7e9f44e0d39b805a901e856b1dd80b4e6ee4338db547050308 AS builder
-RUN apk add --no-cache make
+FROM golang@sha256:a2012b4a1d1f9f7e9f44e0d39b805a901e856b1dd80b4e6ee4338db547050308 AS test
+ENV CGO_ENABLED=0
 WORKDIR /src
-
-# Force BuildKit to run the lint and docs stages before proceeding
-COPY --from=lint /src/go.sum /dev/null
-COPY --from=docs /src/package.json /dev/null
-
 COPY go.mod go.sum ./
 RUN go mod download
+ARG CACHEBUST
 COPY . .
-RUN make test
+RUN --mount=type=cache,target=/root/.cache/go-build \
+    status=0; \
+    output=$(go test -count=1 -timeout 90s -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 -v ./...; \
+    exit 1
 
-ARG VERSION=dev
-RUN CGO_ENABLED=0 go build -trimpath \
-    -ldflags="-s -w -X main.Version=${VERSION}" \
-    -o /sutil ./cmd/sutil
+# 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.26-alpine, 2026-10-27
+FROM golang@sha256:a2012b4a1d1f9f7e9f44e0d39b805a901e856b1dd80b4e6ee4338db547050308 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 . .
 
-# Runtime stage: the binary plus the full source it was built from
+# 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 /sutil ./cmd/sutil
+# The runtime stage ships the source; the repository history is not
+# part of it.
+RUN rm -rf /src/.git
+
+# Runtime stage, and the last one: the binary plus the source it was
+# built from.
 # alpine:3.24, 2026-10-23
 FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a
+ARG CACHEBUST
 COPY --from=builder /sutil /usr/local/bin/sutil
 COPY --from=builder /src /usr/local/src/x
 ENTRYPOINT ["sutil"]