# 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).