# Drive v2 agent instructions

`Drive_v2_final_plan.md` is the product and architecture baseline. ADRs in `docs/adr/` supersede it only where they explicitly say so.

## Required commands

- Backend: `go test ./cmd/... ./internal/...`
- Frontend: `npm --prefix web run check`
- Full validation: `docker compose run --rm verify`
- Container build: `docker build -t drive-v2:dev .`

## Non-negotiable rules

- Preserve the invariants in Section 2 of `Drive_v2_final_plan.md`.
- Domain code must not import HTTP, SQL, PostgreSQL, or filesystem adapters.
- Transport handlers parse, call one application service, and serialize; they do not contain persistence or filesystem logic.
- Only the storage adapter may access managed storage paths.
- Every metadata mutation and its change event must commit in one PostgreSQL transaction.
- Committed blobs are immutable. All transfers stream and all sizes/offsets use 64-bit types.
- Do not add endpoints outside `api/openapi.yaml` or queries outside `db/queries/`.
- Preserve the baseline/change guarantees in ADR-0008; cursors, scoped projections, and resulting-state events are one contract.
- External gateways follow ADR-0009 and may never access managed objects or repositories directly.
- Do not edit generated files directly. Regenerate them and commit source and output together.
- Do not add dependencies or change architecture without owner approval and an ADR.
- Keep frontend features isolated. Never create a global event bus, central extension switch, or all-purpose file-manager component.
- Never discard errors silently or weaken a test to make a change pass.

Keep changes small and scoped. Read the relevant ADR and module documentation before editing.