# `Agentic.Loop.Phase`

Phase state machine with per-mode validated transitions.

All phase transitions in stages go through `transition/2` — never direct
`ctx.phase` mutation. This gives compile-time safety via `transition!/2` in
hot paths and `{:error, _}` returns for graceful handling elsewhere.

No external dependencies — plain data + pattern matching.

# `mode`

```elixir
@type mode() :: :agentic | :agentic_planned | :turn_by_turn | :conversational
```

# `phase`

```elixir
@type phase() :: :init | :plan | :execute | :review | :verify | :done
```

# `initial_phase`

```elixir
@spec initial_phase(mode()) :: phase()
```

Return the initial phase for a given mode.

# `mode_transitions`

# `phases`

# `transition`

Attempt a phase transition. Returns `{:ok, updated_context}` or `{:error, {:invalid_transition, mode, from, to}}`.

# `transition!`

Same as `transition/2` but raises on invalid transition.

# `valid?`

Check if a transition is valid without performing it.

---

*Consult [api-reference.md](api-reference.md) for complete listing*