Rename kit/ to rules/

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

rules/patterns/go-database/contract.md

@@ -0,0 +1,110 @@
+# Contract: Database Patterns (Go / MySQL / MariaDB)
+
+## MySQL Transaction Cursor Safety (CRITICAL)
+
+**Never execute SQL on the same transaction while iterating over a query result cursor.**
+
+This is the most common source of `invalid connection` and `unexpected EOF` driver panics.
+
+### Rule
+
+Use a two-phase approach: read all rows first, close the cursor, then execute writes.
+
+```go
+// WRONG — executes SQL inside rows.Next() loop on the same tx
+rows, _ := tx.Query("SELECT id FROM machines")
+for rows.Next() {
+    var id string
+    rows.Scan(&id)
+    tx.Exec("UPDATE machines SET processed=1 WHERE id=?", id) // DEADLOCK / driver panic
+}
+
+// CORRECT — collect IDs first, then write
+rows, _ := tx.Query("SELECT id FROM machines")
+var ids []string
+for rows.Next() {
+    var id string
+    rows.Scan(&id)
+    ids = append(ids, id)
+}
+rows.Close() // explicit close before any write
+
+for _, id := range ids {
+    tx.Exec("UPDATE machines SET processed=1 WHERE id=?", id)
+}
+```
+
+This applies to:
+- `database/sql` with manual transactions
+- GORM `db.Raw().Scan()` inside a `db.Transaction()` callback
+- Any loop that calls a repository method while a cursor is open
+
+## Soft Delete / Archive Pattern
+
+Do not use hard deletes for user-visible records. Use an archive flag.
+
+```go
+// Schema: is_active bool DEFAULT true
+// "Delete" = set is_active = false
+// Restore = set is_active = true
+
+// All list queries must filter:
+WHERE is_active = true
+```
+
+- Never physically delete rows that have foreign key references or history.
+- Hard delete is only acceptable for orphaned/temporary data with no audit trail requirement.
+- Archive operations must be reversible from the UI.
+
+## GORM Virtual Fields
+
+Use the correct tag based on whether the field should exist in the DB schema:
+
+```go
+// Field computed at runtime, column must NOT exist in DB (excludes from migrations AND queries)
+Count int `gorm:"-"`
+
+// Field computed at query time via JOIN/SELECT, column must NOT be in migrations
+// but IS populated from query results
+DisplayName string `gorm:"-:migration"`
+```
+
+- `gorm:"-"` — fully ignored: no migration, no read, no write.
+- `gorm:"-:migration"` — skip migration only; GORM will still read/write if the column exists.
+- Do not use `gorm:"-"` for JOIN-populated fields — the value will always be zero.
+
+## Fail-Fast DB Check on Startup
+
+Always verify the database connection before starting the HTTP server.
+
+```go
+sqlDB, err := db.DB()
+if err != nil || sqlDB.Ping() != nil {
+    log.Fatal("database unavailable, refusing to start")
+}
+// then: run migrations, then: start gin/http server
+```
+
+Never start serving traffic with an unverified DB connection. Fail loudly at boot.
+
+## N+1 Query Prevention
+
+Use JOINs or batch IN queries. Never query inside a loop over rows from another query.
+
+```go
+// WRONG
+for _, pricelist := range pricelists {
+    items, _ := repo.GetItems(pricelist.ID) // N queries
+}
+
+// CORRECT
+items, _ := repo.GetItemsByPricelistIDs(ids) // 1 query with WHERE id IN (...)
+// then group in Go
+```
+
+## Migration Policy
+
+- Migrations are numbered sequentially and never modified after merge.
+- Each migration must be reversible where possible (document rollback in a comment).
+- Never rename a column in one migration step — add new, backfill, drop old across separate deploys.
+- Auto-apply migrations on startup is acceptable for internal tools; document if used.