# Work Queue

**Last Updated:** 2025-01
**Confidence:** High (Planned - see address-the-gaps.md)

## Summary

Work queue enables worker pool architecture. Workers poll for tasks, execute them, and report results. Supports async build orchestration for bot-driven development.

**Key Facts:**
- Tasks enqueued via `POST /work/enqueue`
- Workers dequeue via `GET /work/dequeue?worker_id=X`
- Status transitions: `pending` → `running` → `completed` | `failed`
- Callback URLs for bot notification on completion
- PostgreSQL-backed with atomic dequeue

**File Pointers:**
- Port: `internal/port/work_queue.go`
- Adapter: `internal/adapter/postgres/work_queue.go`
- Handler: `internal/handlers/work.go`
- Migration: `internal/db/migrations/011_work_queue.sql`

## Port Interface

```go
type WorkQueue interface {
    Enqueue(ctx context.Context, task WorkTask) (string, error)
    Dequeue(ctx context.Context, workerID string) (*WorkTask, error)
    Complete(ctx context.Context, taskID string, result WorkResult) error
    Fail(ctx context.Context, taskID string, err error) error
    GetStatus(ctx context.Context, taskID string) (*WorkTaskStatus, error)
}
```

## Task Types

| Type | Description |
|------|-------------|
| `build` | Run Claude Code with prompt, commit result |
| `test` | Run test suite |
| `deploy` | Trigger Kubernetes deployment |

## API Endpoints

```
POST /work/enqueue          - Add task to queue
GET  /work/dequeue          - Worker gets next task
POST /work/{id}/complete    - Worker reports success
POST /work/{id}/fail        - Worker reports failure
GET  /work/{id}/status      - Check task status
GET  /work/stats            - Queue statistics
```

## Related Topics

- [Worker Pool](./worker-pool.md)
- [Build Orchestration](../features/build-orchestration.md)