build: unify the gate so root make check covers the backend (closes #16)

Root make check, and with it the pre-commit hook, now gates the Go
backend too. The backend's Makefile targets are shims over
backend/script/*; script/cibuild builds both images and is the
workflow's only build step. Root make test runs both halves within one
30-second timeout.

Root make lint runs golangci-lint only in Docker, by building the lint
stage of Dockerfile.backend without the cache; the .golangci.yml drift
check moved into backend/script/lint. script/bootstrap installs no
linter: it reuses a Go at least as new as backend/go.mod asks for,
otherwise installs the pinned, hash-verified release, linked into
~/.local/bin without replacing anything it did not create. With VERSION
unset or empty, the backend version falls back to git describe inside a
git checkout, then to dev.

Model: opus-5-5

backend/Makefile

@@ -1,69 +1,30 @@
-# VERSION is overridable (the Dockerfile passes its ARG VERSION in) and
-# degrades to "dev" when git is unavailable or there is no .git — the
-# build must not depend on the repository history being in the build
-# context.
-VERSION ?= $(shell { git describe --always --dirty; } 2>/dev/null || echo dev)
-BUILDARCH := $(shell uname -m)
-BINARY := netwatch-server
+# Thin shims; the implementations live in backend/script/ (see the
+# Entrypoints section of README.md). There is no check, hooks or docker
+# target here: the root Makefile's check covers this directory, its
+# hooks target installs the repo's only pre-commit hook, and its docker
+# target builds this image, whose build context is the repo root.
 
-GOLDFLAGS += -s -w
-GOLDFLAGS += -X main.Version=$(VERSION)
-GOLDFLAGS += -X main.Buildarch=$(BUILDARCH)
-
-# macOS ships shasum rather than sha256sum.
-SHA256SUM := $(shell command -v sha256sum >/dev/null 2>&1 && echo sha256sum || echo shasum -a 256)
-
-# .golangci.yml is standardized org-wide and must never be edited here
-# (REPO_POLICIES.md). Its last silent drift replaced the v2 schema with
-# v1 keys, which left every threshold in the file inert while the build
-# stayed green. The lint target therefore asserts the file still matches
-# the canonical copy byte for byte. The check is a local hash comparison:
-# no network, no remote schema, nothing unpinned in the build path.
-GOLANGCI_CONFIG_SHA256 := 021cc83f4e6fc7c31b95b34b846723dfcf20b66b7baeea1dc40406e643346bcb
-
-.PHONY: all build test lint fmt fmt-check check docker hooks run clean
+.PHONY: all build test lint fmt fmt-check run clean
 
 all: build
 
 build:
-	CGO_ENABLED=0 go build -trimpath -ldflags "$(GOLDFLAGS)" \
-		-o ./$(BINARY) ./cmd/netwatch-server/
+	@script/build
 
 test:
-	timeout 30 go test ./...
+	@script/test
 
 lint:
-	@actual=$$($(SHA256SUM) .golangci.yml | cut -d' ' -f1); \
-	if [ "$$actual" != "$(GOLANGCI_CONFIG_SHA256)" ]; then \
-		echo ".golangci.yml has drifted from the org standard."; \
-		echo "  expected $(GOLANGCI_CONFIG_SHA256)"; \
-		echo "  actual   $$actual"; \
-		echo "Restore it verbatim from sneak/prompts; do not edit it."; \
-		exit 1; \
-	fi
-	golangci-lint run ./...
+	@script/lint
 
 fmt:
-	go fmt ./...
+	@script/fmt
 
 fmt-check:
-	@test -z "$$(gofmt -l .)" || \
-		(echo "Files not formatted:"; gofmt -l .; exit 1)
+	@script/fmt-check
 
-check: test lint fmt-check
-
-docker:
-	timeout 300 docker build -t netwatch-server -f ../Dockerfile.backend ..
-
-hooks:
-	@printf '#!/bin/sh\ncd backend && make check\n' > \
-		$$(git rev-parse --show-toplevel)/.git/hooks/pre-commit
-	@chmod +x \
-		$$(git rev-parse --show-toplevel)/.git/hooks/pre-commit
-	@echo "Pre-commit hook installed"
-
-run: build
-	./$(BINARY)
+run:
+	@script/run
 
 clean:
-	rm -f ./$(BINARY)
+	@script/clean

backend/README.md

@@ -4,18 +4,50 @@ SPA and persists them as zstd-compressed JSONL files on disk.
 
 ## Getting Started
 
+From this directory:
+
 ```bash
 # Build and run locally
 make run
+```
 
-# Run tests, lint, and format check
+From the repo root, which is also the build context of `Dockerfile.backend`:
+
+```bash
+# Run tests, lint, and format check over the frontend and this backend
 make check
 
-# Docker
-docker build -t netwatch-server .
+# Build both images, including netwatch-server
+make docker
 docker run -p 8080:8080 netwatch-server
 ```
 
+## Entrypoints
+
+This directory follows the same
+[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+pattern as the repo root: the targets in `backend/Makefile` are thin shims over
+`backend/script/`. `Dockerfile.backend` runs them, and the root scripts call
+`test`, `fmt` and `fmt-check`:
+
+- `script/build` — compile the static `netwatch-server` binary with its version
+  and architecture stamped in. The version is `VERSION` from the environment;
+  when that is unset or empty, it falls back to `git describe` inside a git
+  checkout, then to `dev`
+- `script/test` — run the Go tests under a 30-second timeout
+- `script/lint` — check `.golangci.yml` against its pinned sha256, then run
+  golangci-lint. It runs inside the golangci-lint image of the lint stage of
+  `Dockerfile.backend`; from a checkout, run `make lint` at the repo root, which
+  builds that stage
+- `script/fmt` — format the Go sources (writes)
+- `script/fmt-check` — check Go formatting (read-only)
+- `script/run` — build and run the server locally
+- `script/clean` — remove build artifacts
+
+There is no `check`, `hooks` or `docker` target here: the root `make check`
+covers this directory, the root `make hooks` installs the repo's only pre-commit
+hook, and the root `make docker` builds this image.
+
 ## Rationale
 
 The NetWatch frontend collects latency measurements from the browser but has no

backend/script/build

@@ -0,0 +1,21 @@
+#!/bin/sh
+# script/build: compile the static netwatch-server binary into the
+# backend project root, with its version and architecture stamped in.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+
+    # VERSION comes from the environment (Dockerfile.backend passes its
+    # ARG VERSION in). Unset or empty, it is git describe, or "dev" where
+    # there is no git or no repository history.
+    version="${VERSION:-$(git describe --always --dirty 2>/dev/null || echo dev)}"
+
+    CGO_ENABLED=0 go build -trimpath \
+        -ldflags "-s -w -X main.Version=$version -X main.Buildarch=$(uname -m)" \
+        -o netwatch-server ./cmd/netwatch-server/
+}
+
+main "$@"

backend/script/clean

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/clean: remove build artifacts.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    rm -f netwatch-server
+}
+
+main "$@"

backend/script/fmt

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/fmt: format the Go sources (writes).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    go fmt ./...
+}
+
+main "$@"

backend/script/fmt-check

@@ -0,0 +1,18 @@
+#!/bin/sh
+# script/fmt-check: check Go formatting (read-only). Same scope as
+# script/fmt, but fails instead of writing.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    unformatted="$(gofmt -l .)"
+    if [ -n "$unformatted" ]; then
+        echo "Files not formatted:" >&2
+        echo "$unformatted" >&2
+        exit 1
+    fi
+}
+
+main "$@"

backend/script/lint

@@ -0,0 +1,32 @@
+#!/bin/sh
+# script/lint: run golangci-lint over the backend. This runs inside the
+# lint stage of Dockerfile.backend, whose digest-pinned golangci-lint
+# image provides the linter; nothing installs golangci-lint on the host.
+# From a checkout, run `make lint` at the repo root, which builds that
+# stage.
+#
+# .golangci.yml is standardized org-wide and must never be edited here
+# (REPO_POLICIES.md). Its last silent drift replaced the v2 schema with
+# v1 keys, which left every threshold in the file inert while the build
+# stayed green. So the file is first checked against the canonical
+# copy's sha256: a local comparison, no network, nothing unpinned.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+GOLANGCI_CONFIG_SHA256="021cc83f4e6fc7c31b95b34b846723dfcf20b66b7baeea1dc40406e643346bcb"
+
+main() {
+    cd "$ROOT"
+    actual="$(sha256sum .golangci.yml | cut -d' ' -f1)"
+    if [ "$actual" != "$GOLANGCI_CONFIG_SHA256" ]; then
+        echo ".golangci.yml has drifted from the org standard." >&2
+        echo "  expected $GOLANGCI_CONFIG_SHA256" >&2
+        echo "  actual   $actual" >&2
+        echo "Restore it verbatim from sneak/prompts; do not edit it." >&2
+        exit 1
+    fi
+    golangci-lint run ./...
+}
+
+main "$@"

backend/script/run

@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/run: build and run netwatch-server locally.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    "$ROOT/script/build"
+    exec ./netwatch-server "$@"
+}
+
+main "$@"

backend/script/test

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