# AGENTS.md

Rules for any AI coding agent working in this repository (Claude Code, Cursor, Codex, Copilot, and similar). Read this file first. If a change cannot follow these rules, stop and ask instead of working around them.

## Ownership
- Every change you produce is submitted under a human's name, and that human owns the merge. Optimize for a change they can defend in an incident review, not one that merely runs.

## Scope: keep it small
- One logical change per PR. If the diff is more than ~200 lines of real code, split it into separate PRs.
- Touch only the files the task requires. Do not rename, reformat, or "clean up" unrelated code.
- If the task genuinely needs a larger change, propose the split first and wait for a go-ahead.

## Before you write
- Read the files you will change and the ones beside them. Match their patterns, error handling, logging style, and naming.
- Restate the task as explicit acceptance criteria in the PR description. Build to those and nothing more.

## Tests: prove it, do not fake it
- Write the test before the implementation. Show it fail, then make it pass.
- A test must fail when the logic is wrong. After you write one, break the code on purpose and confirm the test catches it. If it still passes, the test is worthless.
- Never make a test pass by mocking, stubbing, or deleting the thing under test. Never weaken or remove an assertion to get to green.
- Cover the failure paths, not just the happy path: null, empty, large input, and an error returned from every external call.

## Dependencies: verify before you add
- Do not add a package unless you have confirmed it exists on the real registry (npm, PyPI, crates.io, and so on). If you are not certain it exists, do not use it and say so.
- Prefer the standard library and dependencies already in this repo. A new dependency needs a one-line justification in the PR.
- Pin versions. Never invent a package name, an import, an API method, or a config key.

## Security: safe by default at every boundary
- Validate and type every input at its boundary. Escape output. Use parameterized queries, never string-concatenated SQL.
- No hardcoded secrets, keys, or tokens. Read them from the environment.
- Do not disable a security control (authentication, authorization, TLS verification, CSRF protection, rate limits) to make something work. If a control blocks you, stop and ask.

## Simplicity
- Solve the task in front of you. Do not add abstraction, configuration, or "extensibility" for a use case that does not exist today.
- If you introduce an interface, factory, or wrapper, name the second concrete caller. If there is not one, inline it.

## What goes in the PR
- A small diff, the acceptance criteria, and two lines on intent (why, not just what).
- A list of any new dependencies, with confirmation that each one exists.
- A note that the change was AI-assisted, so the reviewer calibrates.

## Never
- Skip an authorization or validation check to make a test pass.
- Call a service, endpoint, or SDK method you have not confirmed exists.
- Bundle unrelated changes into one PR.
- Submit code you cannot explain.

## Known mistakes (append your own)
Add a bullet here each time a review catches the agent doing something wrong, so it stops recurring. This section is what makes the file get better over time.
- (example) Do not use `db.query` with string interpolation; use the `sql` tagged template already in `src/db`.
- (add the next one the moment you catch it)