build: make a failing golden readable and approvable

AGENTS.md

@@ -25,6 +25,10 @@ file is the short version of what trips agents up.
   checked-in `.yaml`, which tooling silently normalises.
 - Run before opening a PR: `make test`, `go vet ./...`, `gofmt -l .` (empty),
   `go test -race ./...`.
+- Intended output changes: `make test` prints received vs approved for each
+  failure, `make approve` accepts them. Read the diff first and describe it in
+  the PR body — a golden diff **is** the behaviour change, so never approve one
+  just to clear a red test.
 
 ## Commits & PRs
 

CONTRIBUTING.md

@@ -12,6 +12,27 @@ gofmt -l .   # should print nothing
 CI runs `gofmt`, `go vet`, `go mod tidy` verification, and `go test -race`, so
 run them locally before opening a pull request.
 
+## Approving changed golden output
+
+Behaviour is pinned by approval tests (ADR 0004/0005), so a change to what `kir`
+prints shows up as failing goldens. A failing test leaves what it produced beside
+its golden as `*.received.txt` and `make test` prints both files' contents; a
+passing test deletes its own received file. When the new output is what you
+meant:
+
+```shell
+make test      # prints received vs approved for each failure
+make approve   # renames every *.received.txt over its *.approved.txt
+```
+
+`make approve` accepts every received file it finds, so run it after a full
+`make test` — a filtered `go test -run ...` leaves the untouched tests' files
+behind.
+
+Read the output before approving. A golden diff *is* the behaviour change, so it
+belongs in the pull request description; approving one to clear a red test hides
+the very thing review needs to see.
+
 ## Architecture decisions
 
 Design decisions are recorded as ADRs in [`docs/adr/`](docs/adr/). Read them

Makefile

@@ -1,5 +1,22 @@
 build:
 	go build -o bin/ ./...
 
+# go-approval-tests dropped its console reporter in v1.13.0, so a failing golden
+# now reports only "received does not match approved" — no diff, no file names.
+# The Systemout reporter prints both files and their contents. CI needs no such
+# setting: GitHub Actions sets CI=true, which selects an equivalent reporter.
 test:
-	go test ./... -v
+	APPROVAL_TESTS_USE_REPORTER=SystemoutReporter go test ./... -v
+
+# Accept the current output as the goldens. A failing approval test leaves what
+# it produced beside its golden as *.received.txt; a passing one deletes its own,
+# so the files left over are exactly the failures. Read what `make test` printed
+# before running this, and run it after a full `make test` — a filtered
+# `go test -run ...` leaves other tests' received files behind, and this accepts
+# every one it finds.
+approve:
+	@for f in approvals/*.received.txt; do \
+		[ -e "$$f" ] || continue; \
+		mv "$$f" "$${f%.received.txt}.approved.txt"; \
+		echo "approved $$(basename $${f%.received.txt})"; \
+	done