Harden CI and switch release builds to tagged immutable images

docs/development.md

@@ -0,0 +1,37 @@
+# Development guide
+
+## Structure
+
+- `cmd/drive` owns process startup and CLI dispatch.
+- `internal/domain` contains dependency-free business rules.
+- `internal/application` coordinates use cases through interfaces.
+- `internal/adapters` implements PostgreSQL, storage, and external-service ports.
+- `internal/transport` maps HTTP contracts to application calls.
+- `internal/workers` executes persistent leased jobs.
+- `web/src/features` owns frontend product features; `web/src/shared` contains reusable primitives.
+- `api/openapi.yaml`, migrations, and sqlc queries are reviewed source contracts.
+
+## Canonical checks
+
+Native:
+
+```text
+go test ./cmd/... ./internal/...
+npm --prefix web ci
+npm --prefix web run check
+```
+
+Containerized:
+
+```text
+docker compose run --rm verify
+docker compose up --build
+```
+
+## Contract workflow
+
+Do not add an API handler before its OpenAPI operation exists. Do not write SQL directly in transport or application code; add a named sqlc query. Generated files are outputs and are never edited by hand. CI will add strict generation-drift checks when the first generated client and repository are introduced in Phase 1.
+
+## Architectural changes
+
+Create an ADR before changing storage semantics, public API conventions, package boundaries, deployment topology, or approved dependencies. An ADR records context, decision, consequences, and superseded decisions.