# Workflow State Machine

This file defines the linear progression of a task in automaton. The Orchestrator uses this to determine the next phase.

## Single Source of Truth: `.state` File

The `.state` file in each task folder is the canonical indicator of a task's current phase. It takes precedence over artifact-based heuristic.

- **Location**: `tasks/{task-name}/.state`
- **Content**: A single phase name (e.g., `research`, `research:awaiting_approval`, `implement`, `complete`)
- **Atomic writes**: Written to `.state.tmp` first, then renamed to `.state`
- **If `.state` is missing**: Fall back to artifact-based heuristic and write `.state` with the inferred phase

### `.state.approvals` Log

Each task has a `.state.approvals` file recording all user approvals:

- **Location**: `tasks/{task-name}/.state.approvals`
- **Format**: One line per approval: `{phase}:approved|{ISO-8601-timestamp}|{approver}`
- **Append-only**: Approvals are never deleted
- **Metadata**: Not a phase deliverable, excluded from artifact checks

### `.state.lock` (Multi-Agent Mode Only)

When `Mode: multi-agent` is set in `.agent.md`, a `.state.lock` file tracks which agent has claimed the task:

- **Location**: `tasks/{task-name}/.state.lock`
- **Format**: `agent: {id}`, `phase: {current}`, `claimed: {timestamp}`, `expires: {timestamp}`
- **Atomic writes**: Same `.tmp` pattern as `.state`
- **Default timeout**: 30 minutes (configurable in `.agent.md`)
- **Metadata**: Not a phase deliverable, excluded from artifact checks

## Task Lifecycle

| Current State | Signal | Next Phase | Action |
| :--- | :--- | :--- | :--- |
| **New Task** | `status.py --create-task {name} --project {project}` creates folder with `.state` = `new` | Research | Generate `SPEC.md` |
| **Research** | Has `.state` = `research` | research:awaiting_approval | Present SPEC.md draft for user sign-off |
| **research:awaiting_approval** | Has `.state` = `research:awaiting_approval` | research:approved | User says "APPROVED", call `status.py --approve` |
| **research:approved** | Has `.state` = `research:approved` | Decomposition (optional) or Design (optional) or Implement | Transition via `status.py --transition` |
| **Decomposition** | Has `.state` = `decomposition` | decomposition:awaiting_approval | Present DECOMPOSITION.md draft for user sign-off |
| **decomposition:awaiting_approval** | Has `.state` = `decomposition:awaiting_approval` | decomposition:approved | User says "APPROVED", call `status.py --approve` |
| **decomposition:approved** | Has `.state` = `decomposition:approved` | Sub-task Research | Orchestrator creates sub-task folders |
| **Design** | Has `.state` = `design` | design:awaiting_approval | Present DESIGN.md draft for user sign-off |
| **design:awaiting_approval** | Has `.state` = `design:awaiting_approval` | design:approved | User says "APPROVED", call `status.py --approve` |
| **design:approved** | Has `.state` = `design:approved` | Test Design (optional) or Implement | Transition via `status.py --transition` |
| **Test Design** | Has `.state` = `test_design` | test_design:awaiting_approval | Present TEST_PLAN.md draft for user sign-off |
| **test_design:awaiting_approval** | Has `.state` = `test_design:awaiting_approval` | test_design:approved | User says "APPROVED", call `status.py --approve` |
| **test_design:approved** | Has `.state` = `test_design:approved` | Implement | Transition via `status.py --transition` |
| **Implementation** | Has `.state` = `implement` | Code Review | Generate `CODE_REVIEW.md` |
| **Code Review** | Has `.state` = `code_review` | code_review:awaiting_approval | Present CODE_REVIEW.md draft for user sign-off |
| **code_review:awaiting_approval** | Has `.state` = `code_review:awaiting_approval` | code_review:approved | User says "APPROVED", call `status.py --approve` |
| **code_review:approved** | Has `.state` = `code_review:approved` | Bug Find | Transition via `status.py --transition` |
| **Bug Find** | Has `.state` = `bug_find` | Adversarial Bug Find | Generate `ADVERSARIAL_BUG_REPORT.md` |
| **Adversarial Bug Find** | Has `.state` = `adversarial_bug_find` | Doc Review | Generate `DOC_REVIEW.md` |
| **Doc Review** | Has `.state` = `doc_review` | Referee | Generate `VERDICT.md` |
| **Referee** | Has `.state` = `referee` | Complete / Human Intervention | Finalize or request user intervention |

### Phases Without Approval Gates

The following phases do **not** have `:awaiting_approval` sub-states because they do not require interactive user sign-off:
- `implement`, `bug_find`, `adversarial_bug_find`, `doc_review`, `referee`
- These transition directly to the next phase upon producing their artifact and calling `status.py --transition`

Phases with approval gates (require user sign-off):
- `research`, `decomposition`, `design`, `test_design`, `code_review`

## Task Creation (via `status.py`)

New tasks MUST be created via `status.py --create-task {name} --project {project}`. This creates the folder, `.state` = `new`, and an empty `.state.approvals` file.

Manual task folder creation (`mkdir tasks/my-task`) is flagged as a violation by `status.py --audit` and `status.py --validate-folder`.

Tasks without `.state` files are UNTRACKED. All commands (`--transition`, `--can-edit`, `--task`, `--approve`) refuse to operate on them. Run `status.py --upgrade --project {project}` to bootstrap `.state` files for pre-v2.0 tasks.

### Task creation from bugs
When the Orchestrator detects a `VERDICT.md` with `FAIL` or `NEEDS_REVIEW`, it uses `status.py --create-task --project {project}` to create fix/review/tiebreak tasks. The Orchestrator also copies relevant artifacts (SPEC.md, BUG_REPORT.md, etc.) and sets `.state` to the appropriate phase (e.g., `bug_find` for fix tasks).

## Enforcement via `status.py`

### Phase-Gated Transitions
All transitions go through `status.py --transition {phase} --project {project}`:
- Only legal transitions are allowed (defined in LEGAL_TRANSITIONS)
- `:awaiting_approval` phases can only transition to `:approved` via `status.py --approve --project {project}`
- Required artifacts must exist and be non-empty before transitioning
- Forbidden artifacts (from future phases) block transitions

### Folder Validation
`status.py --validate-folder --task {name} --project {project}` checks for:
- Out-of-order artifacts (artifacts from future phases)
- Missing `.state` file (manually created task)
- Phase-artifact inconsistency

### Audit
`status.py --audit --project {project}` checks all tasks for:
- Category 1: Out-of-order artifacts
- Category 2: State-artifact inconsistency
- Category 3: Unauthorized git modifications (if git repo)
- Category 4: Manually created task folders (no `.state`)

### Approval Gates
`status.py --approve --task {name} --project {project}` transitions from `:awaiting_approval` to `:approved`:
- Records approval in `.state.approvals` with timestamp and approver
- Refuses if not in an `:awaiting_approval` sub-state
- Refuses for phases that don't require approval

## Autopilot Rules

1. **Linear Progression**: Never skip a phase. Each transition must go through `status.py --transition --project {project}`.
2. **Approval Gates**: Research, Decomposition, Design, Test Design, and Code Review phases require explicit user approval before proceeding. The autopilot MUST pause at `:awaiting_approval` sub-states.
3. **Artifact Check**: A phase is only considered "complete" if its corresponding artifact exists, is non-empty, AND the `.state` file reflects the completed phase.
4. **Folder Validation**: Before each phase transition, run `status.py --validate-folder --project {project}`. Do not proceed past violations.
5. **Human Intervention**: If the Referee marks a task as `FAIL`, `NEEDS_REVIEW`, or identifies "Tie-Breaks", the Autopilot pauses and waits for user input.
6. **Task Creation**: Always use `status.py --create-task --project {project}` to create new tasks. Never create task folders manually.
7. **Forbidden Actions**: Respect the ALLOWED/FORBIDDEN sections in each phase prompt. Even in autopilot, the Orchestrator must not perform forbidden actions.