Automaton is a **contract-based, state-enforced workflow framework** for LLM agents. The framework enforces disciplined engineering workflows computationally via `.state` files, `status.py` phase gates, and approval gates — not just via prompts.
- **State enforcement** — all phase transitions must go through `status.py --transition`. All task creation must go through `status.py --create-task`. All approvals must go through `status.py --approve`.
## State Enforcement (v2.0)
The framework enforces the state machine computationally:
- **`.state` file**: Each task has a `.state` file that is the single source of truth for its current phase
- **`status.py --transition`**: All phase transitions must go through this command; illegal transitions are refused
- **Approval gates**: Research, Decomposition, Design, and Test Design phases require explicit user approval before proceeding (`:awaiting_approval` → `:approved`)
- **`status.py --audit`**: Comprehensive audit across all tasks for violations
- **`status.py --create-task`**: The only valid way to create task folders
- **`status.py --upgrade`**: Bootstraps `.state` files for pre-v2.0 tasks that lack them
- **FORBIDDEN actions in prompts**: Each phase prompt explicitly lists what agents cannot do
- **Untracked tasks**: Tasks without `.state` files are UNTRACKED. All commands (`--transition`, `--can-edit`, `--task`) refuse to operate on them. Run `--upgrade` to bootstrap `.state` files.
Loops add a parallel concept: each loop has a `.state.loop` JSON file at `{project}/.automaton/loops/<name>/.state.loop` (framework-internal: `~/.automaton/loops/<name>/`). It is the single source of truth for loop runtime state.
- **`--create-loop NAME [--from-template T]`**: The only valid way to bootstrap a loop dir + `.state.loop` + `loop.json`.
- **`--check-gate NAME`**: Runs all 6 brake gates (status, iterations, budget, task phase, worktree drift, score plateau). First failure halts the loop and best-effort disables the OS schedule unit.
- **`--approve --loop NAME`**: The only way to clear a halt. Increments `resumed_count`. No auto-approve path in v1.
- **`--transition`**: Refuses to transition any task owned by a HALTED loop until `--approve --loop` clears the halt.
- **Untracked loops**: Loop dirs without `.state.loop` are UNTRACKED. All `--loop` commands refuse; `--audit` flags them.
- **`.state.lock` (v1.1)**: Cross-process file lock serializes read-modify-write cycles on `.state.loop`. POSIX `fcntl.flock`, Windows `msvcrt.locking`. Per-loop granularity (`<loop_path>/.state.lock`), blocking acquire, no timeout in v1.1. The runner holds the lock across the entire tick (gate → harness → state write). `--pause-loop`, `--resume-loop`, `--approve --loop`, `--check-gate` in status.py each acquire the lock around their read-modify-write blocks. `--create-loop` is unwrapped. The runner sets `$AUTOMATON_NO_LOOP_LOCK=1` in the `--check-gate` subprocess env ONLY (avoids self-deadlock on the parent's held flock); harness subprocesses do NOT inherit the env var. See `design/loops/technical.md` §7 "Lock serialization".
- **Loop runner**: `scripts/loop-runner.py --mode tick --loop <name> --project <p>` is the per-tick engine. Called by the `automaton-loop-tick.{sh,bat}` stub that `--install-schedule` generates. It calls `--check-gate` first; any non-ok gate exits 0 (clean scheduler exit). Also supports `--mode daemon` (Python sleep loop) and `--json` machine-readable output. See `design/loops/technical.md` §7 for the 11-step tick flow.
`status.py --can-edit` provides a pre-edit gate that any agent harness can call before allowing file modifications. This is the primary enforcement layer. See `contracts/harness-integration.md` for the full integration contract.
The framework provides three enforcement layers:
1.**Harness pre-edit hook** (`--can-edit`) — blocks edits before they happen. Supported by opencode via the `automaton-guard` plugin at `plugins/automaton-guard/`.
2.**Git pre-commit hook** (`scripts/git-hooks/pre-commit`) — blocks commits when no task is in an edit-allowed phase. Works for ALL harnesses.
-`--can-edit --project {p} --loop {name} [--loop-worktree] --file {path}` — Loop worktree scope check: is the file inside this loop's declared `blast_radius.file_scope`? `--loop-worktree` treats the path as worktree-relative; otherwise the absolute path must be inside the project/framework root.
