# CreatePipelineItem

## Permission Scope

item

## Overview

Creates a new item on a pipeline. The item is automatically placed in the pipeline's first stage (lowest position) at the last position within that stage. The item is initialized with OPEN lifecycle and a default priority of MEDIUM if not specified. Callers may set `asDraft=true` to create the item in DRAFT lifecycle instead — useful for preparing items that should not yet appear in operational lists.

## Business Rules

- Pipeline must exist
- Pipeline must be ACTIVE (not ARCHIVED)
- Title is required and must be non-empty
- The pipeline must have at least one stage; creation fails with STAGE_NOT_FOUND on a stage-less pipeline
- PipelineItem is automatically placed in the first stage of the pipeline
- Position is set to the last position within the target stage
- An auto-incremented `itemNumber` is assigned from the pipeline's monotonic counter (`Pipeline.itemNumberSeq`), so numbers are never reused after deletions; `MAX(itemNumber) + 1` is used only as a fallback when the counter is unset
- Lifecycle is initialized to OPEN (default) or DRAFT when `asDraft=true`
- Priority defaults to MEDIUM if not provided; a provided priority must be one of LOW, MEDIUM, HIGH, or URGENT
- AssigneeId, description, dueDate, and asDraft are optional
- When the `getUser` dep is supplied and `assigneeId` is provided, the assignee must exist in user-management

## Process Flow

```mermaid
flowchart TD
    A[Receive createPipelineItem input] --> B{Pipeline exists?}
    B -->|No| C[Return PIPELINE_NOT_FOUND]
    B -->|Yes| D{Pipeline ACTIVE?}
    D -->|No| E[Return PIPELINE_ARCHIVED]
    D -->|Yes| F{Title non-empty?}
    F -->|No| G[Return INVALID_TITLE]
    F -->|Yes| R{Priority valid or omitted?}
    R -->|No| S[Return INVALID_PRIORITY]
    R -->|Yes| O{getUser dep supplied and assigneeId provided?}
    O -->|Yes| P{Assignee exists?}
    P -->|No| Q[Return USER_NOT_FOUND]
    P -->|Yes| H{Pipeline has a stage?}
    O -->|No| H
    H -->|No| H2[Return STAGE_NOT_FOUND]
    H -->|Yes| I[Place in first stage, set position to last in stage]
    I --> I2[Assign next itemNumber per pipeline]
    I2 --> J{asDraft?}
    J -->|Yes| K[Create item with lifecycle DRAFT]
    J -->|No| L[Create item with lifecycle OPEN]
    K --> M[Return created PipelineItem]
    L --> M
```

## External Dependencies

- `user-management.getUser` (optional dep): cross-module existence check for `assigneeId`

## Error Scenarios

- **PIPELINE_NOT_FOUND**: Specified pipeline ID does not exist
- **PIPELINE_ARCHIVED**: Pipeline is archived
- **INVALID_TITLE**: PipelineItem title is empty or blank
- **INVALID_PRIORITY**: Provided priority is not a valid enum value
- **USER_NOT_FOUND**: Specified user ID does not exist in the user-management module
- **STAGE_NOT_FOUND**: Specified stage ID does not exist

## Test Cases

- creates item on active pipeline with lifecycle OPEN by default
- creates item with lifecycle DRAFT when asDraft is true
- places item in first stage automatically
- sets position to last in stage
- assigns itemNumber from the pipeline's monotonic counter
- falls back to MAX(itemNumber) when the counter is unset
- passes consumer extension fields through to the insert
- defaults priority to MEDIUM
- returns error when priority is invalid
- returns error when pipeline not found
- returns error when pipeline is archived
- returns error when title is empty
- returns USER_NOT_FOUND when getUser dep returns null for assigneeId
- accepts assigneeId when getUser dep resolves the user
- returns STAGE_NOT_FOUND when the pipeline has no stages