docs(adr): add 0004-status-enum-mapping

docs/adr/0004-status-enum-mapping.md

@@ -0,0 +1,28 @@
+# ADR-0004: DB enums UPPER_SNAKE, API enums lowercase, mapped exclusively via lib/task-status.ts
+
+## Status
+
+accepted
+
+## Context
+
+Prisma generates TypeScript types from PostgreSQL enum values verbatim. Our DB enums use `UPPER_SNAKE_CASE` (e.g. `TO_DO`, `IN_PROGRESS`, `DONE`) because that is the PostgreSQL convention and it keeps Prisma-generated code readable. However, REST API consumers — including Claude Code via MCP and frontend fetch calls — expect lowercase, underscore-separated values (`todo`, `in_progress`, `done`). Without a single conversion boundary, ad-hoc `.toLowerCase()` calls scattered across route handlers and actions introduce silent mapping bugs when enum values change.
+
+## Decision
+
+- The database retains `UPPER_SNAKE_CASE` enum values. Prisma schema is the source of truth.
+- The REST API (route handlers) and MCP server always expose and accept **lowercase** enum strings.
+- All conversion happens exclusively in `lib/task-status.ts` via named mapper functions. No `.toLowerCase()`, `.toUpperCase()`, or inline string mapping anywhere else.
+
+## Consequences
+
+### Positive
+
+- A single file to audit when enum values change.
+- TypeScript types catch missing branches in mapper exhaustive checks.
+- API contract is stable and grep-friendly.
+
+### Negative
+
+- Every developer (and AI agent) must know to use the mappers rather than string coercion. Violations compile fine but break the API contract at runtime.
+- Mitigated by an ESLint rule that flags direct `.toLowerCase()` on known enum types (pending implementation).