# Requirements Document: Custom Task Status Management

## Introduction

This feature enables project managers, coordinators, and administrators to define and manage custom task statuses at the project level. Currently, the system uses a fixed set of task statuses (not_started, in_progress, submitted, approved, retake) defined as an enum. This enhancement will allow each project to define its own set of statuses with custom names and colors, providing flexibility to match different production workflows while maintaining backward compatibility with existing tasks.

## Glossary

- **Task Status**: A state indicator for a task representing its current progress in the production workflow
- **Custom Status**: A user-defined task status with a custom name, color, and order within a project
- **Status Color**: A hexadecimal color code used to visually distinguish different task statuses in the UI
- **Status Order**: The sequence position of a status in the workflow, determining its display order
- **Default Status**: The initial status assigned to newly created tasks
- **System Status**: The original hardcoded statuses (not_started, in_progress, submitted, approved, retake)
- **Project Settings**: Configuration interface where project-level customizations are managed
- **Status Migration**: The process of converting existing tasks from system statuses to custom statuses

## Requirements

### Requirement 1

**User Story:** As a project manager, I want to create custom task statuses for my project, so that I can match the status workflow to my team's specific production pipeline.

#### Acceptance Criteria

1. WHEN a user with coordinator, project manager, or admin role accesses the project settings tasks tab THEN the system SHALL display a task status management section
2. WHEN a user clicks the "Add Status" button THEN the system SHALL display a form to create a new custom status
3. WHEN a user submits a new status with a name and color THEN the system SHALL validate the name is unique within the project and create the status
4. WHEN a user creates a status without specifying a color THEN the system SHALL assign a default color from a predefined palette
5. WHEN a user attempts to create a status with a duplicate name THEN the system SHALL prevent creation and display an error message

### Requirement 2

**User Story:** As a project manager, I want to edit existing task statuses, so that I can refine status names and colors as the project evolves.

#### Acceptance Criteria

1. WHEN a user clicks the edit button on a status THEN the system SHALL display a form pre-filled with the current status name and color
2. WHEN a user updates a status name THEN the system SHALL validate uniqueness and update all tasks using that status
3. WHEN a user updates a status color THEN the system SHALL immediately reflect the new color across all UI components displaying that status
4. WHEN a user attempts to rename a status to a duplicate name THEN the system SHALL prevent the update and display an error message
5. WHEN a status is updated THEN the system SHALL maintain all task associations with that status

### Requirement 3

**User Story:** As a project manager, I want to delete custom task statuses, so that I can remove statuses that are no longer needed in my workflow.

#### Acceptance Criteria

1. WHEN a user clicks the delete button on a status THEN the system SHALL check if any tasks are currently using that status
2. WHEN a status has no associated tasks THEN the system SHALL allow deletion and remove the status from the project
3. WHEN a status has associated tasks THEN the system SHALL prevent deletion and display the count of affected tasks
4. WHEN a status has associated tasks THEN the system SHALL offer to reassign those tasks to a different status before deletion
5. WHEN a user confirms reassignment and deletion THEN the system SHALL update all affected tasks and remove the status

### Requirement 4

**User Story:** As a project manager, I want to reorder task statuses, so that they appear in a logical workflow sequence in the UI.

#### Acceptance Criteria

1. WHEN a user views the status management section THEN the system SHALL display statuses in their defined order
2. WHEN a user drags a status to a new position THEN the system SHALL update the order and persist the change
3. WHEN statuses are reordered THEN the system SHALL update the display order in all dropdowns and filters
4. WHEN a new status is created THEN the system SHALL add it to the end of the current order
5. WHEN the order is changed THEN the system SHALL maintain the order across all project views

### Requirement 5

**User Story:** As a project manager, I want to designate a default status for new tasks, so that tasks are automatically assigned an appropriate initial state.

#### Acceptance Criteria

1. WHEN a user views the status list THEN the system SHALL indicate which status is the default
2. WHEN a user clicks "Set as Default" on a status THEN the system SHALL mark that status as the default and remove the default flag from other statuses
3. WHEN a new task is created without an explicit status THEN the system SHALL assign the project's default status
4. WHEN no custom statuses exist THEN the system SHALL use "not_started" as the default status
5. WHEN a default status is deleted THEN the system SHALL automatically assign the first status in the list as the new default

### Requirement 6

**User Story:** As a developer, I want the system to maintain backward compatibility with existing tasks, so that current production data remains intact during the migration to custom statuses.

#### Acceptance Criteria

1. WHEN the custom status feature is deployed THEN the system SHALL continue to support existing tasks with system statuses
2. WHEN a project has no custom statuses defined THEN the system SHALL use the original system status enum values
3. WHEN a project defines custom statuses THEN the system SHALL migrate existing tasks to use custom status references
4. WHEN displaying a task status THEN the system SHALL resolve both system statuses and custom statuses correctly
5. WHEN querying tasks by status THEN the system SHALL support filtering by both system and custom status identifiers

### Requirement 7

**User Story:** As an artist, I want to see task statuses with their custom colors throughout the application, so that I can quickly identify task states visually.

#### Acceptance Criteria

1. WHEN a task is displayed in any view THEN the system SHALL show the status with its configured color
2. WHEN a status badge is rendered THEN the system SHALL apply the custom color as the background or border color
3. WHEN a status dropdown is displayed THEN the system SHALL show each status option with its color indicator
4. WHEN filtering by status THEN the system SHALL display status options with their colors
5. WHEN a status color is updated THEN the system SHALL reflect the change immediately without requiring a page refresh

### Requirement 8

**User Story:** As a project manager, I want to see which statuses are actively in use, so that I can make informed decisions about status management.

#### Acceptance Criteria

1. WHEN viewing the status management section THEN the system SHALL display the count of tasks using each status
2. WHEN a status has zero tasks THEN the system SHALL indicate it is safe to delete
3. WHEN a status has tasks THEN the system SHALL display the task count prominently
4. WHEN hovering over a task count THEN the system SHALL optionally show a preview of affected tasks
5. WHEN attempting to delete a status with tasks THEN the system SHALL require explicit confirmation with task count displayed

### Requirement 9

**User Story:** As a system administrator, I want custom statuses to be project-specific, so that different projects can have different workflows without interfering with each other.

#### Acceptance Criteria

1. WHEN custom statuses are created THEN the system SHALL associate them with a specific project ID
2. WHEN displaying statuses for a task THEN the system SHALL only show statuses from the task's project
3. WHEN a user switches between projects THEN the system SHALL display the appropriate status set for each project
4. WHEN querying tasks across projects THEN the system SHALL correctly resolve statuses from their respective projects
5. WHEN a project is deleted THEN the system SHALL cascade delete all associated custom statuses

### Requirement 10

**User Story:** As a coordinator, I want to bulk update task statuses, so that I can efficiently manage status changes across multiple tasks.

#### Acceptance Criteria

1. WHEN a user selects multiple tasks THEN the system SHALL display available custom statuses for the project
2. WHEN a user applies a bulk status update THEN the system SHALL update all selected tasks to the chosen status
3. WHEN tasks from different projects are selected THEN the system SHALL only show statuses common to all projects or handle per-project
4. WHEN a bulk update is performed THEN the system SHALL create activity log entries for each task
5. WHEN a bulk update fails for some tasks THEN the system SHALL report which tasks succeeded and which failed
