# ReorderPipelineStage

## Permission Scope

stage

## Overview

Moves a stage to a new position within its pipeline. Other stages shift their positions to accommodate the change, maintaining a consistent ordering.

## Business Rules

- PipelineStage must exist
- PipelineStage's pipeline must not be locked — locked pipelines keep the lane template seeded at creation
- New position is required; it is 1-based and clamped to the inclusive range `[1, stageCount]` (zero or negative values move the stage to the front, values past the end to the back)
- Other stages on the pipeline shift positions to accommodate the move; positions are renumbered to a contiguous `1..N` sequence

## Process Flow

```mermaid
flowchart TD
    A[Receive reorderPipelineStage input] --> B{PipelineStage exists?}
    B -->|No| C[Return STAGE_NOT_FOUND]
    B -->|Yes| BB{Pipeline is locked?}
    BB -->|Yes| CC[Return PIPELINE_LOCKED]
    BB -->|No| D[Calculate position shifts]
    D --> E[Update target stage position]
    E --> F[Shift affected stages]
    F --> G[Return reordered PipelineStage]
```

## External Dependencies

- None

## Error Scenarios

- **STAGE_NOT_FOUND**: Specified stage ID does not exist
- **PIPELINE_LOCKED**: Locked pipeline lanes are fixed to the template seeded at creation and cannot be modified

## Test Cases

- moves stage to a new position
- shifts other stages when reordering
- clamps position to the end when input exceeds stage count
- clamps position to 1 when input is zero or negative
- returns error when stage not found
- returns error when pipeline is locked
