# ListPipelineItemsByStage

## Overview

ListPipelineItemsByStage retrieves all items within a specific stage, ordered by their position. This supports rendering the items inside a pipeline column in the correct top-to-bottom order.

**Input:** stageId (uuid, required) — the ID of the stage to list items for.

**Output:** List of PipelineItem records ordered by position ascending.

## Business Rules

- stageId is required and must reference an existing PipelineStage record
- Results are ordered by position ascending to reflect item ordering within the column
- Returns an empty list when the stage has no items
- Items of all lifecycles (DRAFT, OPEN, CLOSED) are returned; consumers rendering operational boards filter on the `lifecycle` field themselves (e.g. show OPEN only)
- Query: `SELECT * FROM PipelineItem WHERE stageId = input.stageId ORDER BY position ASC`

## Process Flow

```mermaid
flowchart TD
    A[Receive input with stageId] --> B{PipelineStage exists?}
    B -->|No| C[Return error: STAGE_NOT_FOUND]
    B -->|Yes| D[SELECT * FROM PipelineItem WHERE stageId = input.stageId ORDER BY position ASC]
    D --> E[Return item list]
```

## External Dependencies

- None

## Error Scenarios

- **STAGE_NOT_FOUND**: Specified stage ID does not exist

## Test Cases

- returns items ordered by position ascending
- returns empty list when stage has no items
- filters items to the specified stage only
- returns error when stage does not exist
