# Sprint Lifecycle Rules

This document defines sprint status transitions, edit permissions, delete permissions, archive rules, and restore rules enforced by the API (`SprintLifecycleService`) and reflected in the UI.

## Sprint Statuses

| Status | Value | Description |
|--------|-------|-------------|
| Draft | `draft` | New sprint; full editing; safe to delete |
| Planned | `planned` | Committed plan; full editing with audit trail |
| Active | `active` | In execution; limited edits |
| Completed | `completed` | Sprint closed; read-only |
| Cancelled | `cancelled` | Abandoned; read-only; may be restored |
| Archived | `archived` | Long-term storage; fully read-only |

Legacy `closed` values are migrated to `completed`.

## Status Transitions

```
Draft ──plan──► Planned ──start──► Active ──complete──► Completed ──archive──► Archived
  │                │                    │                      │
  │                │                    └──cancel──► Cancelled ──archive──► Archived
  │                │                                          │
  │                └──────────────────cancel──────────────────┘
  │                                                             │
  └─────────────────────────cancel──────────────────────────────┘
                                                              restore
                                                                 │
                                                                 ▼
                                                              Planned
```

| Action | Endpoint | From | To |
|--------|----------|------|-----|
| Plan | `PATCH /sprints/{id}/plan` | Draft | Planned |
| Start | `PATCH /sprints/{id}/start` | Planned | Active |
| Complete | `PATCH /sprints/{id}/close` | Active | Completed |
| Cancel | `PATCH /sprints/{id}/cancel` | Draft, Planned, Active | Cancelled |
| Archive | `PATCH /sprints/{id}/archive` | Completed, Cancelled | Archived |
| Restore | `PATCH /sprints/{id}/restore` | Cancelled | Planned |
| Duplicate | `POST /sprints/{id}/duplicate` | Draft, Planned, Cancelled | New Draft |

**Notes**

- Only one sprint may be `active` per project. Starting a sprint demotes any other active sprint to `planned`.
- Moving backlog items into a `draft` sprint automatically promotes it to `planned`.
- Completing a sprint runs the existing closure checklist (`SprintClosureValidator`).

## Edit Permissions

| Status | Can edit? | Allowed fields |
|--------|-----------|----------------|
| Draft | Yes | All metadata: name, goal, dates, capacity, sort order |
| Planned | Yes (audited) | All metadata: name, goal, dates, capacity, sort order |
| Active | Limited | `name`, `goal` only |
| Completed | No | — |
| Cancelled | No | — |
| Archived | No | — |

### Active sprint constraints

While a sprint is **active**, the API additionally blocks:

- Changing `start_date`
- Changing capacity fields (`capacity_md`, `capacity_points`, `capacity_hours`) — velocity manipulation
- Deleting the sprint
- Removing completed work items from the sprint

Allowed during active execution (via work-item endpoints, not sprint PATCH):

- Assignee changes on sprint work items
- Adding backlog items to the sprint (returns a lifecycle warning in API metadata)

## Delete Permissions

Permanent delete is allowed only when:

1. **Status = Draft**, or
2. **Status = Planned** AND there is **no execution history** AND **no work logs** AND **no reports**

Otherwise delete is rejected with:

> This sprint contains execution history and cannot be deleted. Cancel or archive the sprint instead.

### Execution history

A sprint has execution history when any of the following is true:

- Current status is `active`, `completed`, `cancelled`, or `archived`
- `completed_at` is set
- Audit logs show the sprint was started
- Any sprint work item has `completed_at` set

### Work logs

Time entries (`ticket_time_entries`) exist for tickets assigned to the sprint.

### Reports

Health snapshots (`project_health_snapshots`) or velocity snapshots (`project_velocity_snapshots`) reference the sprint.

## Archive Rules

- Only **completed** or **cancelled** sprints may be archived.
- Archiving sets `status = archived` and `archived_at = now()`.
- Archived sprints are fully read-only and hidden from active planning views.
- Archiving preserves all tickets, audit history, and report data.

## Restore Rules

- Only **cancelled** sprints may be restored.
- Restore sets `status = planned` and clears `cancelled_at`.
- Restored sprints regain full planned-state edit permissions.
- Restored sprints do not automatically become active; use **Start** after re-planning if needed.

## Audit

- All sprint model changes use the `Auditable` trait on `ProjectSprint`.
- **Planned** sprint edits are recorded in `audit_logs` like any other update.
- Sprint completion overrides are logged explicitly by `SprintClosureValidator`.
- UI must not bypass these rules; the API enforces them via `SprintLifecycleService`.

## API Lifecycle Metadata

Each `ProjectSprint` resource includes a `lifecycle` object:

```json
{
  "can_edit": true,
  "can_delete": false,
  "delete_blocked_reason": "This sprint contains execution history...",
  "editable_fields": ["name", "goal"],
  "read_only": false,
  "can_restore": false,
  "available_actions": ["view", "edit", "manage_backlog", "capacity", "complete", "cancel"],
  "warnings": []
}
```

The UI uses this object to drive the sprint actions menu, edit form field visibility, and delete button tooltips.