docs: add a root CLAUDE.md with the build, test and lint setup

[dobby-coder]

Closes #641.

Adds a root CLAUDE.md covering the layout, build, tests, lint gates and the changelog requirement. Documentation only; no code or CI changes.

Every command in the file was run in a checkout of this repo, with one exception that the file marks explicitly: this container has the Docker client but no Docker daemon, so docker compose run test -v ./... and docker compose up could not be executed. What the file says about those services is read off docker-compose.yml, Dockerfile.test and .github/workflows/status-checks.yml.

Things found while verifying, worth a look

Three of these contradict what the issue or the README says, so flagging them rather than burying them in the file.

--tags=local_tests ./... from the README does not build. internal/sessiontest/irma_issuance_test.go (untagged) calls startRevocationServer, which lives in revocation_test.go behind //go:build !local_tests:

internal/sessiontest/irma_issuance_test.go:67:16: undefined: startRevocationServer
FAIL	github.com/privacybydesign/irmago/internal/sessiontest [build failed]

Everything else passes with no services running. CLAUDE.md documents the workaround (go test -p 1 --tags=local_tests $(go list ./... | grep -v /internal/sessiontest)) and names the cause, but the fix is behavioral and out of scope for a docs PR. Happy to send it separately if you want the README command to work again.

Redis is not a test dependency. The issue asked for the "Postgres/Redis services from docker-compose.yml", but there is no Redis service in docker-compose.yml, and both Redis test sites (internal/sessiontest/redis_test.go, irma/server/keyshare/myirmaserver/session_test.go) use in-process miniredis. The docker run redis snippet in the README is for running a server by hand. The file says this so a later reader does not go hunting for a container.

staticcheck needs a toolchain at least as new as go.mod. go install honnef.co/go/tools/cmd/staticcheck@2025.1.1 compiles staticcheck with whatever go is on PATH. If that is older than 1.26, staticcheck reports nothing useful:

-: module requires at least go1.26.0, but Staticcheck was built with go1.24.2 (compile)

CI is unaffected (actions/setup-go uses go-version-file: go.mod), but it bites locally. GOTOOLCHAIN=go1.26.4 go install ... fixes it.

Verified locally

go build ./...
CGO_ENABLED=0 go build -o /tmp/yivi ./yivi && /tmp/yivi version
pkg-config --libs sqlcipher
go test -p 1 --tags=local_tests $(go list ./... | grep -v /internal/sessiontest)   # all ok
gofmt -d -e . | (! grep ^)
go vet ./... ; go fix -diff ./... ; ineffassign ./...
find . -type f -not -path './testdata/*.json' | xargs misspell -error -i "adres,instelling,relatie"
staticcheck -checks "all,-ST1000,-ST1003,-SA1019,-SA1029" ./...   # clean

The SQLCipher claim was checked by rebuilding with an empty PKG_CONFIG_LIBDIR on a cold GOCACHE: go build ./client fails on eudi/storage/db/sqlcipher, go build ./yivi succeeds.

Notes

• PR feat(eudi): optional DNSSEC check for did:web verifier domains #621 also adds a 6-line CLAUDE.md as a side change. Whichever merges second will conflict on the file; the content here is a superset.
• Labelled skip-changelog: a contributor-facing notes file does not belong in the user-facing changelog. Remove the label and I will add an entry if you would rather have one.

[dobby-coder]

VERDICT: approve

Rules Dobby 2 — consolidated review (rule sweep + handed-forward review findings).

One blocking finding, fixed on the branch

The postgres-init claim was factually wrong. It said the container "creates the irma schema; without it the keyshare and myirma database tests fail". Neither half of the consequence holds:

• The tests create the schema themselves. keyshareserver/postgresdb_test.go:171, myirmaserver/postgresdb_test.go:239 and tasks/tasks_test.go:308 each define SetupDatabase(t) as RunScriptOnDB(t, "../cleanup.sql", true) then RunScriptOnDB(t, "../schema.sql", false), and every Postgres test calls it first (keyshareserver/postgresdb_test.go:20,61,141 and the equivalents in the other two packages). schema.sql opens with CREATE SCHEMA irma;.
• CI never runs postgres-init. The test service's depends_on (docker-compose.yml:89-108) lists postgres, mysql, sqlserver, mailhog, eudi_openid4vp, eudi_openid4vp_jwt, veramo_openid4vp, tls_proxy and statuslist_agent, and not postgres-init. postgres-init appears only under the yivi service (docker-compose.yml:127-130). docker compose run test starts a service's own dependencies, so the exact CI command never brings it up, and the suite is green.

This is the same class of thing the PR already got right for Redis: a convenience for the run-a-server-by-hand path, not a test prerequisite. Since it is a two-sentence reword on a self-authored draft with no human review to dismiss, I pushed the correction rather than looping: fb7ee8f.

Rule sweep

Per-rule check over the rules that apply to a docs-only Go-repo diff. All clean:

• writing-rules — no banned vocabulary, openers or phrases; em-dash and bold counts both under the 1-per-1,000-words cap.
• irmago-lint-job-gates-on-misspell — misspell -error -i "adres,instelling,relatie" run against the file, clean. The CI lint job is green.
• staticcheck-needs-a-toolchain-as-new-as-go-mod — the file documents the GOTOOLCHAIN pin correctly, which is the point of the rule.
• patch-in-comment-gate-is-not-live-yet — no CI job or gate is described as live that is not. The PR adds no workflow files.
• no-justification-paragraphs-for-simple-changes, cross-repo-link-format, conventional-commit-pr-titles (no pr-title.yml in this repo, so it does not apply), pr-close-issue-keywords (Closes #641, own line, correct form), pr-review-assignments (@kamphuisem requested) — all clean.
• irmamobile-claude-md-gitignored does not extend here. That rule is scoped to privacybydesign/irmamobile, which gitignores its CLAUDE.md; irmago does not.

Other claims, verified against the tree

Checked the rest of the file rather than trusting it, since a wrong line in CLAUDE.md is auto-loaded context for every later run. All accurate: the lint step order and exact commands against .github/workflows/status-checks.yml; staticcheck.conf keeping SA1019 on while CI adds -SA1019; changelog.yml's base-to-head diff plus skip-changelog escape; the testdata/configurations/ file list; ports 5432/3306/1433/1025 and the postgres.localhost / mailhog.localhost aliases; the 8443/8444/8445 tls_proxy mapping; go.mod's go 1.26.0 / toolchain go1.26.4; the root being package irmago with only Version; CGO_ENABLED=0 in .github/actions/build/action.yml:35 and the Dockerfile; go list -deps ./client pulling in both sqlcipher packages while ./yivi pulls in neither; internal/sessiontest/irma_issuance_test.go:67 calling startRevocationServer, defined at revocation_test.go:909 behind //go:build !local_tests; and no Redis service in docker-compose.yml with miniredis at exactly the two named sites.

One thing worth a maintainer's eye, not blocking: the PR body flags that the README's go test -p 1 --tags=local_tests ./... does not build. That is a real pre-existing breakage this PR only documents, and worth its own issue.

[dobby-coder]

Corrected in fb7ee8f. The previous wording said this step "creates the irma schema; without it the keyshare and myirma database tests fail" — the tests create the schema themselves via each package's SetupDatabase(t) (cleanup.sql then schema.sql), and postgres-init is in the yivi service's depends_on, not the test service's, so docker compose run test never starts it. Left here as the record of what changed and why.