decomposer: generate deliverable files for Implement the task REST API service with FastAPI, including standard CRUD endpoints, HTTP status semantics, request and response models, and structured error handling.; Add a PostgreSQL persistence layer for the task service using SQLAlchemy models, session management, database initialization or migrations, and durable task storage integrated with the existing API contract.; Define and integrate Pydantic request and response schemas for task fields, status values, identifiers, timestamps, and validation errors across the existing FastAPI service and persistence contract.; Add automated pytest coverage for the task API, including CRUD behavior, request and response validation failures, HTTP status semantics, and persistence interactions using isolated test data.; Containerize the FastAPI task service and PostgreSQL persistence service with Docker Compose, including environment-based configuration, health checks, networking, startup dependencies, and persistent database storage.; Create project documentation and operational guidance covering local setup, Docker Compose configuration, environment variables, API endpoints, validation and error responses, testing commands, persistence behavior, and relevant best-practice notes.

README.md

@@ -1,3 +1,58 @@
-# crucible-agent-build-lightweight-rest
+# Task API
 
-Auto-generated agent: build-lightweight-rest
+A containerized FastAPI task REST API backed by PostgreSQL and SQLAlchemy.
+
+## Quick start
+
+```bash
+cp .env.example .env
+docker compose up --build
+curl http://localhost:8000/health
+```
+
+The API is available at `http://localhost:8000`; interactive OpenAPI docs are at `/docs`.
+
+For local development, create a virtual environment and run:
+
+```bash
+pip install -r requirements.txt
+uvicorn app.main:app --reload
+pytest -q
+```
+
+The default local database URL is PostgreSQL. Tests override the database dependency with isolated SQLite databases, so no database server is required for the test suite.
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `DATABASE_URL` | `postgresql+psycopg2://tasks:tasks@db:5432/tasks` | SQLAlchemy database URL |
+| `APP_NAME` | `Task API` | API display name |
+| `LOG_LEVEL` | `INFO` | Uvicorn log level |
+
+Do not commit production secrets. The Compose database uses the `POSTGRES_*` variables from `.env` and persists data in the `postgres_data` volume.
+
+## API contract
+
+Tasks have a UUID `id`, required `title` (1–200 characters), optional `description` (maximum 5000), `status` (`pending`, `in_progress`, or `completed`), optional timezone-aware `due_at`, and server-managed UTC `created_at` and `updated_at` timestamps.
+
+- `POST /tasks` — create; returns `201`
+- `GET /tasks` — list, with optional `status`, `skip`, and `limit`; returns `200`
+- `GET /tasks/{id}` — fetch; returns `200`, or `404` if absent
+- `PATCH /tasks/{id}` — partial update; returns `200`, or `404`
+- `DELETE /tasks/{id}` — delete; returns `204`, or `404`
+- `GET /health` — database-backed readiness check; returns `200` or `503`
+
+Invalid JSON, fields, UUIDs, or query parameters return a structured `422` response:
+
+```json
+{"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[...]}}
+```
+
+Not-found and database failures use the same envelope with codes `TASK_NOT_FOUND` and `DATABASE_ERROR`. The API does not expose database internals.
+
+## Operations
+
+`docker compose up --build` waits for the PostgreSQL health check before starting the API. On startup the API calls `Base.metadata.create_all`; this is convenient for this small service. For production, replace it with reviewed Alembic migrations before deploying schema changes. `docker compose down` preserves data; `docker compose down -v` removes the database volume.
+
+Run `pytest -q` for CRUD, validation, status semantics, error envelopes, and persistence-isolation coverage.