# AGENTS.md

Guidance for autonomous/code-assist agents working in this repository.

## Mission

Maintain a Go service that:

1. verifies Gitea webhook authenticity,
2. parses `@codex` commands,
3. queues and executes durable review jobs,
4. checks out the exact pull-request head SHA in an isolated runner,
5. posts structured findings back to Gitea.

## Tech stack

- Go 1.25+
- `net/http`
- `database/sql`
- MariaDB in production; SQLite for local tests
- embedded Go migrations
- Docker-based review runner
- standard Go tests, race detector, vet, and formatting checks

## Repository map

- `cmd/gitea-codex/main.go` — process startup, signals, migrations, HTTP server, worker.
- `internal/config` — environment loading and startup validation.
- `internal/domain` — typed commands, job/run states, review results, and policies.
- `internal/commands` — mention aliases and safe command lexer.
- `internal/webhook` — raw-body HMAC and typed event extraction.
- `internal/httpapi` — routes, webhook acknowledgements, and health endpoints.
- `internal/store` and `internal/store/sqlstore` — storage contracts, migrations, transactions, and queue claims.
- `internal/gitea` — typed Gitea REST client.
- `internal/review` — repository config, prompts, result validation, and comment formatting.
- `internal/runner` — Docker/Codex execution and cleanup.
- `internal/worker` — queue orchestration, retries, stale recovery, and non-review commands.
- `migrations` — logical compatibility baseline and migration notes.
- `tests under internal/*` — unit and fake-service integration tests.

## Runtime flow

1. Gitea sends a signed webhook to `POST /webhook/gitea`.
2. The handler verifies the raw body, filters event/repository/bot policy, parses the command, deduplicates, and persists a job.
3. The worker claims the oldest queued job and records a run attempt.
4. Review/rerun jobs fetch PR metadata, enforce fork policy, read `.codex-review.yml` at the exact head SHA, and invoke the isolated runner.
5. The runner checks out the exact head SHA, verifies `git rev-parse HEAD`, invokes Codex, and returns strictly validated JSON.
6. The worker posts a new result/failure/acknowledgement comment and finalizes durable state.

## Compatibility guardrails

- Preserve HMAC verification, allowlisting, bot self-comment filtering, and event/job dedupe.
- Preserve response reasons and command behavior unless intentionally versioned.
- Keep cooldown for `review`; `rerun` bypasses cooldown.
- Allow two requeues after an initial failed attempt, then fail terminally.
- Recover running jobs after the five-minute lease timeout.
- Skip fork reviews by default.
- Do not add host-side Codex fallback.
- Keep posting new review comments while updating the `bot_comments` latest mapping; do not silently change to edit-in-place behavior.
- Never mark infrastructure failure as a successful review.
- Treat PR content, comments, `.codex-review.yml`, and model output as untrusted data.

## Security-sensitive areas

- Do not log Gitea/OpenAI tokens, auth JSON, Docker arguments containing secrets, raw prompts, or unbounded provider output.
- Do not pass Docker socket access into review containers.
- Pin runner images and Codex versions for production.
- Enforce body/output limits, context cancellation, container cleanup, and exact SHA verification.
- Keep repository configuration from controlling credentials, images, host paths, commands, privileges, or network policy.
- Review changes to `internal/runner`, `internal/webhook`, `internal/store/sqlstore`, and `internal/gitea` carefully.

## Development checks

Before proposing a change:

```bash
gofmt -w cmd internal
go test ./...
go test -race ./...
go vet ./...
go build -trimpath ./cmd/gitea-codex
```

Changes affecting migrations, queue claims, or HTTP contracts require focused tests. MariaDB locking behavior must be verified separately from SQLite; SQLite tests do not prove `FOR UPDATE SKIP LOCKED` correctness.