# How It Works

The AGENTS.md contract: stop conditions, blast-radius limits, and the one-thing-at-a-time rule.

AGENTS.md is the primary instruction set for anyone (human or AI) making changes to YotoShelf. It exists because the codebase has several interconnected frameworks that must be kept in sync — changing one without updating the others causes subtle build or runtime failures.

## The one-thing-at-a-time rule

Each merge request does exactly one thing. A MR that adds a new API endpoint should not also refactor unrelated code. This is enforced by the MR size gate in CI (`scripts/check-file-size.sh`).

## Stop conditions

AGENTS.md lists explicit stop conditions — situations where an automated contributor must stop and request human review rather than proceeding:

- Any change to the database schema (`internal/db/migrations/`)
- Any change to the auth middleware or session handling
- Any change to the Yoto API client (`go-yoto` module)
- Any new dependency not already in `go.mod` or `package.json`
- Any change to the container build (`Containerfile`, `Dockerfile`)
- Any change to CI configuration (`.gitlab-ci.yml`, `ci/`)

## Blast radius limits

Changes are scoped to minimise risk:

- **API changes:** One new operation per MR. New operations must not modify existing handler signatures.
- **Frontend changes:** One component or page per MR. Design token changes require a separate MR.
- **Database changes:** One migration file per MR. Migrations must be additive (no column drops, no renames).

## Validation checklist

Every MR must pass `just check` locally before submission. This runs:

1. `go vet` and `golangci-lint`
2. `go test ./...`
3. `sqlc vet` (schema/query consistency)
4. `npm run build` (frontend build)
5. File size gate (no file over 500 lines of prose)