# Migration lifecycle

The states, trust boundaries, and human decision points in one PatchFlow run.

```
migrating → pr_opened → testing → ready
                         ↘ retrying → testing
                         ↘ needs_attention
                         ↘ error
```

## 1. Detect and constrain

PatchFlow resolves the target version, classifies the semantic update type, applies package and update-type policies, and creates a run record.

## 2. Migrate

The agent receives one package, one version transition, the available evidence, the repository base branch, and a strict instruction to avoid unrelated refactors.

## 3. Draft PR

The agent opens a pull request. PatchFlow converts it to draft when draftPullRequests is enabled, then reads the exact head SHA to gate.

## 4. Prove and label

Required GitHub Checks must appear and succeed. Local mode clones the branch, completes repository setup, and then runs the configured test command. Setup failure is a gate failure.

## 5. Human review

PatchFlow never merges. A ready label means the configured evidence and checks are ready for a human decision.