# Workflow State Machine

## States

| State | Meaning |
|---|---|
| `PLANNING` | Architect prepares an approved instruction |
| `CODEX_READY` | A build or correction job is queued |
| `CODEX_RUNNING` | A Codex adapter run is active |
| `VALIDATING` | Independent validation is queued or running |
| `ARCHITECT_REVIEWING` | Architect reviews structured results |
| `CORRECTIONS_REQUIRED` | Review or validation requires another pass |
| `OWNER_GATE` | Protected judgment/action awaits owner approval |
| `BLOCKED` | Retry exhaustion or a non-recoverable condition stopped progress |
| `APPROVED` | Architect approved the build |
| `INTEGRATING` | Approved result is being integrated |
| `COMPLETE` | Build is complete and next-build planning is dispatched |

## Allowed transitions

```text
PLANNING -> CODEX_READY | OWNER_GATE | BLOCKED
CODEX_READY -> CODEX_RUNNING | BLOCKED
CODEX_RUNNING -> VALIDATING | CODEX_READY | BLOCKED
VALIDATING -> ARCHITECT_REVIEWING | CORRECTIONS_REQUIRED | BLOCKED
ARCHITECT_REVIEWING -> CORRECTIONS_REQUIRED | OWNER_GATE | APPROVED | BLOCKED
CORRECTIONS_REQUIRED -> CODEX_READY | OWNER_GATE | BLOCKED
OWNER_GATE -> PLANNING | CODEX_READY | APPROVED | BLOCKED
BLOCKED -> PLANNING | CODEX_READY | VALIDATING | ARCHITECT_REVIEWING | OWNER_GATE
APPROVED -> INTEGRATING | BLOCKED
INTEGRATING -> COMPLETE | BLOCKED
COMPLETE -> terminal (a separate planning job selects the next build)
```

Every transition appends one immutable event. Invalid or repeated transition
delivery cannot mutate state.

## Live worker evidence

`CODEX_RUNNING -> VALIDATING` occurs only after the supervisor observes CLI
exit zero and parses a schema-valid completion. This is Codex-reported
completion, not approval. `VALIDATING -> ARCHITECT_REVIEWING` requires an
independent validator result. The Architect then independently chooses
correction, owner gate, block, or approval. Correction dispatch preserves the
original external thread ID.
