# Tasks Specification

> Generated by openlore v1.0.0 on 2025-06-15
> Source files: src/tasks/task-model.ts, src/tasks/task-service.ts, src/tasks/task-routes.ts

## Purpose

Manages the full lifecycle of tasks: creation, retrieval, updates (including status
transitions), deletion, and filtered listing within projects.

## Entities

### Task

| Property | Type | Description |
|----------|------|-------------|
| id | string | Unique task identifier (format: task_{timestamp}) |
| title | string | Task title (required, trimmed) |
| description | string | Detailed description (defaults to "") |
| status | TaskStatus | One of: todo, in_progress, done, cancelled |
| priority | TaskPriority | One of: low, medium, high, urgent |
| assigneeId | string \| null | User ID of assignee |
| projectId | string | Parent project ID (required) |
| createdBy | string | User ID of creator |
| dueDate | Date \| null | Optional due date |
| tags | string[] | User-defined tags |

## Requirements

### Requirement: TaskCreation

The system SHALL create tasks with a required title and projectId, defaulting status to "todo" and priority to "medium".

#### Scenario: ValidCreation
- **GIVEN** a valid title and projectId
- **WHEN** POST /api/tasks is called
- **THEN** the system creates the task with default status "todo" and returns it with status 201

#### Scenario: MissingTitle
- **GIVEN** a request body without a title
- **WHEN** POST /api/tasks is called
- **THEN** the system returns status 400 with error "Task title is required"

### Requirement: TaskStatusTransitions

The system SHALL enforce valid status transitions:
- todo → in_progress, cancelled
- in_progress → done, todo, cancelled
- done → todo
- cancelled → todo

#### Scenario: ValidTransition
- **GIVEN** a task with status "todo"
- **WHEN** the status is updated to "in_progress"
- **THEN** the transition succeeds

#### Scenario: InvalidTransition
- **GIVEN** a task with status "todo"
- **WHEN** the status is updated to "done"
- **THEN** the system throws "Cannot transition from todo to done"

### Requirement: TaskCRUD

The system SHALL support Get, Update (PATCH), Delete, and List operations for tasks. All task routes require authentication.

#### Scenario: TaskNotFound
- **GIVEN** a non-existent task ID
- **WHEN** GET /api/tasks/:id is called
- **THEN** the system returns status 404

### Requirement: TaskFiltering

The system SHALL support filtering tasks by projectId (required), status, and assigneeId via query parameters.

## Technical Notes

- **Implementation**: `src/tasks/task-model.ts`, `src/tasks/task-service.ts`, `src/tasks/task-routes.ts`
- **Dependencies**: auth domain (requireAuth middleware)