test: add Locust performance-test harness (#3)

[Ayushhh26]

Related Issue

• Closes Add Locust performance testing #3

Change Summary

• tests/perf/locustfile.py — Locust harness with three scenarios: an always-on customer auth flow (/v1/auth/register → /v1/auth/me → /v1/auth/refresh, /v1/auth/logout on stop), always-on concurrent health reads (/health and /health/db as separate stat rows), and an env-gated admin CRUD flow on /v1/user (paginated list + create → read → update → delete with grouped /v1/user/[id] stats and self-cleanup)
• make perf-test — headless run against a local server; PERF_HOST / PERF_USERS / PERF_SPAWN_RATE / PERF_RUN_TIME overridable; exits non-zero if any request failed
• docs/operations/performance-locust.md — how to run, how to read the output, the one-time admin provisioning flow, a measured illustrative local baseline, and limitations (quickstart-local, illustrative only, no CI — per the scoping comment)
• Index updates: docs/README.md Operations table row + roadmap checkbox in docs/reference.md
• No src/ changes, no new dependencies (locust was already in the dev group), no CI wiring

Type of Change

• test: Tests
• docs: Documentation

Checklist

• Architecture rules followed (no Domain -> Infrastructure imports) — no src/ changes
• Tests pass — 1371 passed; one pre-existing failure unrelated to this PR (see Notes)
• Linting passes (ruff check src/) — plus ruff check tests/perf/ and all pre-commit hooks on the changed files

How to Test

make quickstart      # terminal 1
make perf-test       # terminal 2 — 30s headless run, exits 0 with a stats summary

• Default run needs zero setup (customer + health scenarios). Measured here: 327 requests / 0 failures, 10.9 RPS, p50 3 ms / p95 25 ms / p99 220 ms — recorded in the docs as an illustrative baseline.
• Admin scenario: provision a real admin once via the dashboard (documented three-step flow), then LOCUST_ADMIN_USERNAME=… LOCUST_ADMIN_PASSWORD=… make perf-test.
• Negative probe: LOCUST_ADMIN_USERNAME=admin LOCUST_ADMIN_PASSWORD=admin make perf-test — the bootstrap admin is rejected by the token API, the login failure shows loudly in Locust's error report, and make exits non-zero.

Scenario shape — as requested, pinging for your input (@Mr-DooSun)

• The requested "auth + CRUD flow on /v1/user" hit a wall: all /v1/user routes are admin-realm-gated (feat(auth): server-route RBAC for /v1/* endpoints #199/refactor(auth): separate admin identity into a dedicated bounded context with its own token realm (C-lite) #218), and the bootstrap admin is setup-only (rejected by POST /v1/admin/login). So the CRUD scenario is env-gated behind LOCUST_ADMIN_* credentials, and I added an always-on customer-realm auth scenario so the default make perf-test produces useful output with zero manual setup. Happy to reshape if you prefer a different split.
• Optional follow-up question: a dev-only admin seed script could make the admin scenario turnkey. There is an in-repo precedent (_seed_real_admin e2e fixture), but it bypasses the normal first-admin lifecycle (in-process DI, no setup gate), so I left it out pending your call.

Notes

• Drift (deferred): .claude/rules/commands.md does not yet list make perf-test. Deliberately left out to keep this PR non-governor-changing — happy to include it or leave it for a follow-up /sync-guidelines, your preference.
• Pre-existing test failure (unrelated): tests/unit/agents_shared/test_antigravity_hardening.py::test_native_write_file_edit_is_formatted fails identically on current main in my environment (formatting-hook subprocess appears environment-dependent). Not touched by this PR.