# Backend Agent Operating Contract

## Phase gate

This repository is in specification mode. Do not create `go.mod`, application packages, migrations, containers, or executable code until the relevant capability spec is approved.

For every Go-related task, always invoke and follow the `golang-how-to` skill, then the secondary Go skills it routes to. Before creating the Go project layout, ask the user to approve the architecture style and dependency-injection approach in that order.

## Product invariants

- The backend is the authority for authentication, authorization, tenant isolation, metric definitions, and data provenance.
- Every merchant-scoped query derives merchant identity from the authenticated server-side session; never trust a client-supplied merchant identifier as authorization.
- Cross-merchant results are minimum-cohort, anonymized aggregates only.
- Use integer minor currency units or an explicitly documented fixed-precision representation; never floating point for money.
- Preserve source timestamps and document their timezone assumptions. Normalize operational timestamps consistently.
- Raw imports are immutable inputs; corrections are new import versions, not silent mutation.
- `adjusted_fee` is obfuscated and may be used only for relative analysis.

## Go baseline after approval

- Keep `main` packages thin under `cmd/`; business code lives under `internal/`.
- Wire dependencies manually with explicit constructors at the composition root. Do not introduce a DI container or code generator unless a later ADR documents measured wiring/lifecycle complexity.
- Use explicit constructors; avoid `init()` side effects and mutable globals.
- Configuration comes from validated environment variables. Logs go to stdout as structured records without credentials, card keys, or sensitive payloads.
- Propagate `context.Context`; bound external calls, queues, batches, and database pools.
- Use parameterized queries and transactions with explicit boundaries. Stream/bulk-load the multi-million-row input instead of holding it in memory.
- Passwords use an approved adaptive hash (Argon2id or bcrypt per the approved auth spec); sessions use secure, HttpOnly cookies and server-side revocation.
- Required verification includes unit/integration tests, race detection where applicable, `go vet`, `golangci-lint`, `govulncheck`, and migration/import tests.

## Git and documentation

- Use atomic Conventional/Commitizen commits.
- Track specs, ERD/schema definitions, migrations, importer code, validation rules, manifests/templates, and runbooks.
- Ignore raw CSV archives, database volumes/dumps, credentials, and generated runtime data.
- Changes to a metric, API, schema, authorization rule, or AI data boundary require the corresponding spec/ADR update.

## AI boundary (post-MVP)

AvalAI is accessed only from the backend using a server-held API key. Prefer the simplest bounded LLM call/workflow that satisfies the approved use case. Send minimized, sanitized aggregates with explicit budgets/timeouts; persist trace metadata and deterministic inputs, not unnecessary sensitive prompts. AI output is advisory and must cite underlying deterministic metrics.