# State machine workflow and approval gates

LEGAL_TRANSITIONS in status.py:85-108 defines phase flow:

```
new → research → research:awaiting_approval → research:approved
  → decomposition → decomposition:awaiting_approval → decomposition:approved
  → design → design:awaiting_approval → design:approved
  → test_design → test_design:awaiting_approval → test_design:approved
  → implement → code_review → code_review:awaiting_approval → code_review:approved
  → bug_find → adversarial_bug_find → doc_review → referee → complete
```

## Key points
- Approval gates exist for: research, decomposition, design, test_design, code_review
- To approve: must first transition to `{phase}:awaiting_approval`, then `--approve`, then transition to next phase
- `implement → code_review → bug_find → adversarial_bug_find → doc_review → referee → complete` has NO approval gates (direct transitions)
- All transitions must go through `status.py --transition`
- `.state` file is the single source of truth for current phase
- `--upgrade` bootstraps `.state` for pre-v2.0 tasks using artifact heuristic