# PipelineStage

## Description

PipelineStage represents a single step within a pipeline. Each stage has a name, an integer position for ordering, a category (NOT_STARTED, IN_PROGRESS, DONE, or CANCELED) that enables cross-pipeline reporting, and an optional color for visual presentation. Stages are per-pipeline -- they are not shared globally. Position determines the visual ordering in the pipeline view, and category classifies the stage's semantic meaning regardless of its display name.

## Domain Model Definitions

### Model type

Standard

### Command Definitions

- [CreatePipelineStage](../command/CreatePipelineStage.md) - Create a new stage on a pipeline with a name, position, and category
- [UpdatePipelineStage](../command/UpdatePipelineStage.md) - Update mutable fields (name, category, color) of an existing stage
- [DeletePipelineStage](../command/DeletePipelineStage.md) - Remove a stage that has no items assigned to it
- [ReorderPipelineStage](../command/ReorderPipelineStage.md) - Change the position of a stage within a pipeline

### Query Definitions

- [ListPipelineStagesByPipeline](../query/ListPipelineStagesByPipeline.md) - List all stages belonging to a pipeline, ordered by position

### Models

- PipelineStage

### Invariants

- Pipeline ID is required and must reference an existing pipeline
- PipelineStage name is required and must be non-empty
- PipelineStage name must be unique within the same pipeline (backed by a unique index, with a friendly duplicate check in the create/update commands)
- Position is required; create/reorder commands treat it as a 1-based slot index and keep sibling positions contiguous, so stages managed through commands never share a position
- Category is required and must be one of NOT_STARTED, IN_PROGRESS, DONE, or CANCELED
- A stage cannot be deleted if it has any items assigned to it

### Relationships

- **Belongs To Pipeline**: Each stage belongs to a pipeline via `pipelineId`
- **Has Many PipelineItem**: A stage contains items via `stageId` on PipelineItem
- **Referenced By PipelineStageTransition**: Stages are referenced as fromStage and toStage in transition records
