update README: reference REPO_POLICIES.md, add License/Author sections, document new Makefile targets

.dockerignore

@@ -0,0 +1,6 @@
+.git
+bin
+data
+.env
+.DS_Store
+*.exe

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.go]
+indent_style = tab
+
+[Makefile]
+indent_style = tab

CLAUDE.md

@@ -1,68 +0,0 @@
-# Repository Rules
-
-Last Updated 2026-01-08
-
-These rules MUST be followed at all times, it is very important.
-
-* Never use `git add -A` - add specific changes to a deliberate commit. A
-  commit should contain one change. After each change, make a commit with a
-  good one-line summary.
-
-* NEVER modify the linter config without asking first.
-
-* NEVER modify tests to exclude special cases or otherwise get them to pass
-  without asking first. In almost all cases, the code should be changed,
-  NOT the tests. If you think the test needs to be changed, make your case
-  for that and ask for permission to proceed, then stop. You need explicit
-  user approval to modify existing tests. (You do not need user approval
-  for writing NEW tests.)
-
-* When linting, assume the linter config is CORRECT, and that each item
-  output by the linter is something that legitimately needs fixing in the
-  code.
-
-* When running tests, use `make test`.
-
-* Before commits, run `make check`. This runs `make lint` and `make test`
-  and `make check-fmt`. Any issues discovered MUST be resolved before
-  committing unless explicitly told otherwise.
-
-* When fixing a bug, write a failing test for the bug FIRST. Add
-  appropriate logging to the test to ensure it is written correctly. Commit
-  that. Then go about fixing the bug until the test passes (without
-  modifying the test further). Then commit that.
-
-* When adding a new feature, do the same - implement a test first (TDD). It
-  doesn't have to be super complex. Commit the test, then commit the
-  feature.
-
-* When adding a new feature, use a feature branch. When the feature is
-  completely finished and the code is up to standards (passes `make check`)
-  then and only then can the feature branch be merged into `main` and the
-  branch deleted.
-
-* Write godoc documentation comments for all exported types and functions as
-  you go along.
-
-* ALWAYS be consistent in naming. If you name something one thing in one
-  place, name it the EXACT SAME THING in another place.
-
-* Be descriptive and specific in naming. `wl` is bad;
-  `SourceHostWhitelist` is good. `ConnsPerHost` is bad;
-  `MaxConnectionsPerHost` is good.
-
-* This is not prototype or teaching code - this is designed for production.
-  Any security issues (such as denial of service) or other web
-  vulnerabilities are P1 bugs and must be added to TODO.md at the top.
-
-* As this is production code, no stubbing of implementations unless
-  specifically instructed. We need working implementations.
-
-* Avoid vendoring deps unless specifically instructed to.  NEVER commit
-  the vendor directory, NEVER commit compiled binaries.  If these
-  directories or files exist, add them to .gitignore (and commit the
-  .gitignore) if they are not already in there.  Keep the entire git
-  repository (with history) small - under 20MiB, unless you specifically
-  must commit larger files (e.g. test fixture example media files).  Only
-  OUR source code and immediately supporting files (such as test examples)
-  goes into the repo/history.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sneak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -1,4 +1,4 @@
-.PHONY: all build lint fmt test check clean
+.PHONY: all build lint fmt fmt-check test check clean docker hooks
 
 BINARY := dnswatcher
 VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
@@ -17,21 +17,26 @@ fmt:
 	gofmt -s -w .
 	goimports -w .
 
+fmt-check:
+	@test -z "$$(gofmt -l .)" || (echo "Files not formatted:" && gofmt -l . && exit 1)
+
 test:
-	go test -v -race -cover ./...
+	go test -v -race -cover -timeout 30s ./...
 
 # Check runs all validation without making changes
 # Used by CI and Docker build - fails if anything is wrong
-check:
-	@echo "==> Checking formatting..."
-	@test -z "$$(gofmt -l .)" || (echo "Files not formatted:" && gofmt -l . && exit 1)
-	@echo "==> Running linter..."
-	golangci-lint run --config .golangci.yml ./...
-	@echo "==> Running tests..."
-	go test -v -race ./...
+check: fmt-check lint test
 	@echo "==> Building..."
 	go build -ldflags "$(LDFLAGS)" -o /dev/null ./cmd/dnswatcher
 	@echo "==> All checks passed!"
 
+docker:
+	docker build .
+
+hooks:
+	@printf '#!/bin/sh\nset -e\nmake check\n' > .git/hooks/pre-commit
+	@chmod +x .git/hooks/pre-commit
+	@echo "Pre-commit hook installed."
+
 clean:
 	rm -rf bin/

README.md

@@ -327,10 +327,13 @@ tracks reachability:
 
 ```sh
 make build      # Build binary to bin/dnswatcher
-make test       # Run tests with race detector
+make test       # Run tests with race detector and 30s timeout
 make lint       # Run golangci-lint
-make fmt        # Format code
-make check      # Run all checks (format, lint, test, build)
+make fmt        # Format code (writes)
+make fmt-check  # Read-only format check
+make check      # Run all checks (fmt-check, lint, test, build)
+make docker     # Build Docker image
+make hooks      # Install pre-commit hook
 make clean      # Remove build artifacts
 ```
 
@@ -385,7 +388,17 @@ docker run -d \
 
 ## Project Structure
 
-Follows the conventions defined in `CONVENTIONS.md`, adapted from the
+Follows the conventions defined in `REPO_POLICIES.md`, adapted from the
 [upaas](https://git.eeqj.de/sneak/upaas) project template.  Uses uber/fx
 for dependency injection, go-chi for HTTP routing, slog for logging, and
 Viper for configuration.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Author
+
+[@sneak](https://sneak.berlin)

REPO_POLICIES.md

@@ -0,0 +1,188 @@
+---
+title: Repository Policies
+last_modified: 2026-02-22
+---
+
+This document covers repository structure, tooling, and workflow standards. Code
+style conventions are in separate documents:
+
+- [Code Styleguide](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE.md)
+  (general, bash, Docker)
+- [Go](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_GO.md)
+- [JavaScript](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_JS.md)
+- [Python](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_PYTHON.md)
+- [Go HTTP Server Conventions](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/GO_HTTP_SERVER_CONVENTIONS.md)
+
+---
+
+- Cross-project documentation (such as this file) must include
+  `last_modified: YYYY-MM-DD` in the YAML front matter so it can be kept in sync
+  with the authoritative source as policies evolve.
+
+- **ALL external references must be pinned by cryptographic hash.** This
+  includes Docker base images, Go modules, npm packages, GitHub Actions, and
+  anything else fetched from a remote source. Version tags (`@v4`, `@latest`,
+  `:3.21`, etc.) are server-mutable and therefore remote code execution
+  vulnerabilities. The ONLY acceptable way to reference an external dependency
+  is by its content hash (Docker `@sha256:...`, Go module hash in `go.sum`, npm
+  integrity hash in lockfile, GitHub Actions `@<commit-sha>`). No exceptions.
+  This also means never `curl | bash` to install tools like pyenv, nvm, rustup,
+  etc. Instead, download a specific release archive from GitHub, verify its hash
+  (hardcoded in the Dockerfile or script), and only then install. Unverified
+  install scripts are arbitrary remote code execution. This is the single most
+  important rule in this document. Double-check every external reference in
+  every file before committing. There are zero exceptions to this rule.
+
+- Every repo with software must have a root `Makefile` with these targets:
+  `make test`, `make lint`, `make fmt` (writes), `make fmt-check` (read-only),
+  `make check` (prereqs: `test`, `lint`, `fmt-check`), `make docker`, and
+  `make hooks` (installs pre-commit hook). A model Makefile is at
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`.
+
+- Always use Makefile targets (`make fmt`, `make test`, `make lint`, etc.)
+  instead of invoking the underlying tools directly. The Makefile is the single
+  source of truth for how these operations are run.
+
+- The Makefile is authoritative documentation for how the repo is used. Beyond
+  the required targets above, it should have targets for every common operation:
+  running a local development server (`make run`, `make dev`), re-initializing
+  or migrating the database (`make db-reset`, `make migrate`), building
+  artifacts (`make build`), generating code, seeding data, or anything else a
+  developer would do regularly. If someone checks out the repo and types
+  `make<tab>`, they should see every meaningful operation available. A new
+  contributor should be able to understand the entire development workflow by
+  reading the Makefile.
+
+- Every repo should have a `Dockerfile`. All Dockerfiles must run `make check`
+  as a build step so the build fails if the branch is not green. For non-server
+  repos, the Dockerfile should bring up a development environment and run
+  `make check`. For server repos, `make check` should run as an early build
+  stage before the final image is assembled.
+
+- Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
+  runs `docker build .` on push. Since the Dockerfile already runs `make check`,
+  a successful build implies all checks pass.
+
+- Use platform-standard formatters: `black` for Python, `prettier` for
+  JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
+  two exceptions: four-space indents (except Go), and `proseWrap: always` for
+  Markdown (hard-wrap at 80 columns). Documentation and writing repos (Markdown,
+  HTML, CSS) should also have `.prettierrc` and `.prettierignore`.
+
+- Pre-commit hook: `make check` if local testing is possible, otherwise
+  `make lint && make fmt-check`. The Makefile should provide a `make hooks`
+  target to install the pre-commit hook.
+
+- All repos with software must have tests that run via the platform-standard
+  test framework (`go test`, `pytest`, `jest`/`vitest`, etc.). If no meaningful
+  tests exist yet, add the most minimal test possible — e.g. importing the
+  module under test to verify it compiles/parses. There is no excuse for
+  `make test` to be a no-op.
+
+- `make test` must complete in under 20 seconds. Add a 30-second timeout in the
+  Makefile.
+
+- Docker builds must complete in under 5 minutes.
+
+- `make check` must not modify any files in the repo. Tests may use temporary
+  directories.
+
+- `main` must always pass `make check`, no exceptions.
+
+- Never commit secrets. `.env` files, credentials, API keys, and private keys
+  must be in `.gitignore`. No exceptions.
+
+- `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
+  editor files (`.swp`, `*~`), language build artifacts, and `node_modules/`.
+  Fetch the standard `.gitignore` from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up
+  a new repo.
+
+- Never use `git add -A` or `git add .`. Always stage files explicitly by name.
+
+- Never force-push to `main`.
+
+- Make all changes on a feature branch. You can do whatever you want on a
+  feature branch.
+
+- `.golangci.yml` is standardized and must _NEVER_ be modified by an agent, only
+  manually by the user. Fetch from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`.
+
+- When pinning images or packages by hash, add a comment above the reference
+  with the version and date (YYYY-MM-DD).
+
+- Use `yarn`, not `npm`.
+
+- Write all dates as YYYY-MM-DD (ISO 8601).
+
+- Simple projects should be configured with environment variables.
+
+- Dockerized web services listen on port 8080 by default, overridable with
+  `PORT`.
+
+- `README.md` is the primary documentation. Required sections:
+    - **Description**: First line must include the project name, purpose,
+      category (web server, SPA, CLI tool, etc.), license, and author. Example:
+      "µPaaS is an MIT-licensed Go web application by @sneak that receives
+      git-frontend webhooks and deploys applications via Docker in realtime."
+    - **Getting Started**: Copy-pasteable install/usage code block.
+    - **Rationale**: Why does this exist?
+    - **Design**: How is the program structured?
+    - **TODO**: Update meticulously, even between commits. When planning, put
+      the todo list in the README so a new agent can pick up where the last one
+      left off.
+    - **License**: MIT, GPL, or WTFPL. Ask the user for new projects. Include a
+      `LICENSE` file in the repo root and a License section in the README.
+    - **Author**: [@sneak](https://sneak.berlin).
+
+- First commit of a new repo should contain only `README.md`.
+
+- Go module root: `sneak.berlin/go/<name>`. Always run `go mod tidy` before
+  committing.
+
+- Use SemVer.
+
+- Database migrations live in `internal/db/migrations/` and must be embedded in
+  the binary.
+  - `000_migration.sql` — contains ONLY the creation of the migrations tracking
+    table itself. Nothing else.
+  - `001_schema.sql` — the full application schema.
+  - **Pre-1.0.0:** never add additional migration files (002, 003, etc.). There
+    is no installed base to migrate. Edit `001_schema.sql` directly.
+  - **Post-1.0.0:** add new numbered migration files for each schema change.
+    Never edit existing migrations after release.
+
+- All repos should have an `.editorconfig` enforcing the project's indentation
+  settings.
+
+- Avoid putting files in the repo root unless necessary. Root should contain
+  only project-level config files (`README.md`, `Makefile`, `Dockerfile`,
+  `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, and
+  language-specific config). Everything else goes in a subdirectory. Canonical
+  subdirectory names:
+    - `bin/` — executable scripts and tools
+    - `cmd/` — Go command entrypoints
+    - `configs/` — configuration templates and examples
+    - `deploy/` — deployment manifests (k8s, compose, terraform)
+    - `docs/` — documentation and markdown (README.md stays in root)
+    - `internal/` — Go internal packages
+    - `internal/db/migrations/` — database migrations
+    - `pkg/` — Go library packages
+    - `share/` — systemd units, data files
+    - `static/` — static assets (images, fonts, etc.)
+    - `web/` — web frontend source
+
+- When setting up a new repo, files from the `prompts` repo may be used as
+  templates. Fetch them from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/<path>`.
+
+- New repos must contain at minimum:
+    - `README.md`, `.git`, `.gitignore`, `.editorconfig`
+    - `LICENSE`, `REPO_POLICIES.md` (copy from the `prompts` repo)
+    - `Makefile`
+    - `Dockerfile`, `.dockerignore`
+    - `.gitea/workflows/check.yml`
+    - Go: `go.mod`, `go.sum`, `.golangci.yml`
+    - JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
+    - Python: `pyproject.toml`

internal/resolver/iterative.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"math/rand"
 	"net"
 	"sort"
 	"strings"
@@ -41,6 +42,22 @@ func rootServerList() []string {
 	}
 }
 
+const maxRootServers = 3
+
+// randomRootServers returns a shuffled subset of root servers.
+func randomRootServers() []string {
+	all := rootServerList()
+	rand.Shuffle(len(all), func(i, j int) {
+		all[i], all[j] = all[j], all[i]
+	})
+
+	if len(all) > maxRootServers {
+		return all[:maxRootServers]
+	}
+
+	return all
+}
+
 func checkCtx(ctx context.Context) error {
 	err := ctx.Err()
 	if err != nil {
@@ -227,7 +244,7 @@ func (r *Resolver) followDelegation(
 
 		authNS := extractNSSet(resp.Ns)
 		if len(authNS) == 0 {
-			return r.resolveNSIterative(ctx, domain)
+			return r.resolveNSRecursive(ctx, domain)
 		}
 
 		glue := extractGlue(resp.Extra)
@@ -291,84 +308,60 @@ func (r *Resolver) resolveNSIPs(
 	return ips
 }
 
-// resolveNSIterative queries for NS records using iterative
-// resolution as a fallback when followDelegation finds no
-// authoritative answer in the delegation chain.
-func (r *Resolver) resolveNSIterative(
+// resolveNSRecursive queries for NS records using recursive
+// resolution as a fallback for intercepted environments.
+func (r *Resolver) resolveNSRecursive(
 	ctx context.Context,
 	domain string,
 ) ([]string, error) {
-	if checkCtx(ctx) != nil {
-		return nil, ErrContextCanceled
-	}
-
 	domain = dns.Fqdn(domain)
-	servers := rootServerList()
+	msg := new(dns.Msg)
+	msg.SetQuestion(domain, dns.TypeNS)
+	msg.RecursionDesired = true
 
-	for range maxDelegation {
+	for _, ip := range randomRootServers() {
 		if checkCtx(ctx) != nil {
 			return nil, ErrContextCanceled
 		}
 
-		resp, err := r.queryServers(
-			ctx, servers, domain, dns.TypeNS,
-		)
+		addr := net.JoinHostPort(ip, "53")
+
+		resp, _, err := r.client.ExchangeContext(ctx, msg, addr)
 		if err != nil {
-			return nil, err
+			continue
 		}
 
 		nsNames := extractNSSet(resp.Answer)
 		if len(nsNames) > 0 {
 			return nsNames, nil
 		}
-
-		// Follow delegation.
-		authNS := extractNSSet(resp.Ns)
-		if len(authNS) == 0 {
-			break
-		}
-
-		glue := extractGlue(resp.Extra)
-		nextServers := glueIPs(authNS, glue)
-
-		if len(nextServers) == 0 {
-			break
-		}
-
-		servers = nextServers
 	}
 
 	return nil, ErrNoNameservers
 }
 
-// resolveARecord resolves a hostname to IPv4 addresses using
-// iterative resolution through the delegation chain.
+// resolveARecord resolves a hostname to IPv4 addresses.
 func (r *Resolver) resolveARecord(
 	ctx context.Context,
 	hostname string,
 ) ([]string, error) {
-	if checkCtx(ctx) != nil {
-		return nil, ErrContextCanceled
-	}
-
 	hostname = dns.Fqdn(hostname)
-	servers := rootServerList()
+	msg := new(dns.Msg)
+	msg.SetQuestion(hostname, dns.TypeA)
+	msg.RecursionDesired = true
 
-	for range maxDelegation {
+	for _, ip := range randomRootServers() {
 		if checkCtx(ctx) != nil {
 			return nil, ErrContextCanceled
 		}
 
-		resp, err := r.queryServers(
-			ctx, servers, hostname, dns.TypeA,
-		)
+		addr := net.JoinHostPort(ip, "53")
+
+		resp, _, err := r.client.ExchangeContext(ctx, msg, addr)
 		if err != nil {
-			return nil, fmt.Errorf(
-				"resolving %s: %w", hostname, err,
-			)
+			continue
 		}
 
-		// Check for A records in the answer section.
 		var ips []string
 
 		for _, rr := range resp.Answer {
@@ -380,24 +373,6 @@ func (r *Resolver) resolveARecord(
 		if len(ips) > 0 {
 			return ips, nil
 		}
-
-		// Follow delegation if present.
-		authNS := extractNSSet(resp.Ns)
-		if len(authNS) == 0 {
-			break
-		}
-
-		glue := extractGlue(resp.Extra)
-		nextServers := glueIPs(authNS, glue)
-
-		if len(nextServers) == 0 {
-			// Resolve NS IPs iteratively — but guard
-			// against infinite recursion by using only
-			// already-resolved servers.
-			break
-		}
-
-		servers = nextServers
 	}
 
 	return nil, fmt.Errorf(
@@ -427,7 +402,7 @@ func (r *Resolver) FindAuthoritativeNameservers(
 		candidate := strings.Join(labels[i:], ".") + "."
 
 		nsNames, err := r.followDelegation(
-			ctx, candidate, rootServerList(),
+			ctx, candidate, randomRootServers(),
 		)
 		if err == nil && len(nsNames) > 0 {
 			sort.Strings(nsNames)