# ListPipelineStageTransitionsByItem

## Overview

ListPipelineStageTransitionsByItem retrieves the full stage transition history for a specific item, ordered by when each transition occurred. This supports displaying the audit trail of an item's movement across pipeline stages.

**Input:** itemId (uuid, required) — the ID of the item to list transitions for.

**Output:** List of PipelineStageTransition records ordered by createdAt ascending.

## Business Rules

- itemId is required and must reference an existing PipelineItem record
- Results are ordered by createdAt ascending to show chronological transition history
- Returns an empty list when the item has no recorded transitions
- Query: `SELECT * FROM PipelineStageTransition WHERE itemId = input.itemId ORDER BY createdAt ASC`

## Process Flow

```mermaid
flowchart TD
    A[Receive input with itemId] --> B{PipelineItem exists?}
    B -->|No| C[Return error: ITEM_NOT_FOUND]
    B -->|Yes| D[SELECT * FROM PipelineStageTransition WHERE itemId = input.itemId ORDER BY createdAt ASC]
    D --> E[Return transition list]
```

## External Dependencies

- None

## Error Scenarios

- **ITEM_NOT_FOUND**: Specified item ID does not exist

## Test Cases

- returns transitions ordered by createdAt ascending
- returns empty list when item has no transitions
- filters transitions to the specified item only
- returns error when item does not exist
