From 5d75b5ce0296eebad88ad8a880a39fd7463b3414 Mon Sep 17 00:00:00 2001 From: clawbot Date: Mon, 9 Nov 2026 18:16:08 +0000 Subject: [PATCH] Add AGENTS.md with the repository's rules for agents (closes #246) AGENTS.md holds the branching model, the entrypoints, the editing rule and two iron rules: query strings are logged as received, and the trusted-proxy default is the RFC 1918 set. README links it; SPEC.md step 2 now states that default and that a given list replaces it. Model: opus-5-5 --- AGENTS.md | 39 +++++++++++++++++++++++++++++++++++++++ README.md | 1 + SPEC.md | 2 ++ 3 files changed, 42 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b20f223 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,39 @@ +# Agents + +These are the rules for agents working on this repository. + +## Branches + +- `main` is the stable branch, and `next` is the development branch. +- Every PR is cut from `next` and targets `next`. +- Only sneak merges `next` into `main`. +- Each issue lands on `next` as one squashed commit whose title ends + ` (closes #N)`. A PR of exactly two commits lands as both commits: first tests + that fail against the current code, then the fix with no test assertion + changed. + +## Entrypoints + +- Work through the `Makefile` targets, which call the scripts in `script/`. The + README's [Entrypoints](README.md#entrypoints) section lists them. +- Never run `go`, `golangci-lint` or prettier directly. +- `make check` passes before every push. + +## Editing + +- Edit files by hand. +- Format only with `make fmt`, and run it before committing any change. + +## Iron rules + +- The request log records query strings exactly as received. + - Secrets belong in POST data. An app that puts a secret in a query string + is fixed in the app. + - Never propose redacting a query string, Gitea's `?token=` included. +- The default of `SWRP_TRUSTED_PROXIES` is the RFC 1918 set. + - The set is: + - `10.0.0.0/8`; + - `172.16.0.0/12`; + - `192.168.0.0/16`. + - `SPEC.md` states that default. + - Forwarded headers count only when the peer is a trusted proxy. diff --git a/README.md b/README.md index 1061d5f..2234b57 100644 --- a/README.md +++ b/README.md @@ -746,6 +746,7 @@ on the host. - [`EVALUATION.md`](EVALUATION.md): what already exists, what each tool covers and misses, and why none was adopted. - [`REPO_POLICIES.md`](REPO_POLICIES.md): the policies this repository follows. +- [`AGENTS.md`](AGENTS.md): the rules for agents working on this repository. - [`docs/settings.md`](docs/settings.md): every setting and the values it takes. - [`docs/rules.md`](docs/rules.md): the rule file format and the default file. - [`docs/admin-endpoints.md`](docs/admin-endpoints.md): the endpoints under diff --git a/SPEC.md b/SPEC.md index 797a742..e20c71f 100644 --- a/SPEC.md +++ b/SPEC.md @@ -133,6 +133,8 @@ request log's `heuristic` field gives that name. `refusal_limit` and 1. `GET /_sww/healthz` is answered at once by `rproxy`, before any check, so a health checker never needs an exemption and is never refused. 2. The client is identified. + - `SWRP_TRUSTED_PROXIES` is `10.0.0.0/8`, `172.16.0.0/12` and + `192.168.0.0/16` by default. A list given replaces them. - If the TCP peer is inside `SWRP_TRUSTED_PROXIES`, `X-Forwarded-For` is walked from the right, and the first address outside those netblocks is the client. If every address is inside them, the leftmost is, so that a