v2.0: state enforcement, project scoping, harness integration

State Enforcement (v2.0):
- .state file as single source of truth for task phase
- Approval gates for research, decomposition, design, test_design
- status.py --transition refuses illegal phase transitions
- status.py --validate-folder detects out-of-order artifacts
- status.py --audit checks all tasks for violations
- status.py --create-task is the only valid way to create tasks
- Pre-v2.0 tasks without .state are UNTRACKED -- all commands refuse them
- New --upgrade command bootstraps .state files for existing tasks

Project Scoping:
- --project flag added to all status.py commands across 16+ files
- _find_project_dir errors instead of silently falling back to ~/.automaton/
- --scope-check marks framework files OUT_OF_SCOPE when working on a project
- Dashboard handlers use stored project_root instead of re-detecting from CWD
- Prompts reference ~/.automaton/scripts/vram_detect.py (not {project}/.automaton/)

Harness Integration:
- status.py --can-edit now supports project-level checks (no --task required)
- --can-edit --file checks file scope without --task
- --json output for machine-readable harness integration
- opencode plugin (plugins/automaton-guard/plugin.ts) intercepts edit/write
- Git pre-commit hook (scripts/git-hooks/pre-commit) blocks commits without task
- Formal integration contract (contracts/harness-integration.md)

Other:
- upgrade.sh delegates to status.py --upgrade instead of manual heuristics
- Phase prompts reference --project {project} for multi-project scoping
- 200 tests passing (14 new)

AGENTS.md

@@ -4,7 +4,7 @@ This file contains the information coding agents need to work effectively on the
 
 ## Project Overview
 
-Automaton is a **prompt-driven, contract-based workflow framework** for LLM agents. It is intentionally not an agent harness: the framework provides prompts, conventions, scripts, and a dashboard, but enforcement is soft and relies on agent discipline.
+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.
 
 ## Repository Layout
 
@@ -20,15 +20,22 @@ Automaton is a **prompt-driven, contract-based workflow framework** for LLM agen
 ├── scripts/               # Bash/Python helper scripts
 │   ├── install.sh
 │   ├── update.sh
+│   ├── upgrade.sh          # Upgrades projects to v2.0 (bootstraps .state files)
 │   ├── migrate-project.sh
+│   ├── status.py            # Phase enforcement, transitions, audits, claiming, can-edit
 │   ├── vram_detect.py
+│   ├── git-hooks/           # Git hooks for enforcement
+│   │   └── pre-commit       # Blocks commits when no task in edit phase
 │   └── dashboard.sh
 ├── prompts/               # Phase-specific LLM prompts
 │   ├── orchestrate.md
 │   ├── research.md
 │   ├── implement.md
 │   └── ...
-├── contracts/             # Contract checklists
+├── contracts/             # Contract checklists and integration docs
+│   └── harness-integration.md  # Harness integration contract
+├── plugins/               # Agent harness plugins
+│   └── automaton-guard/    # opencode pre-edit guard plugin
 ├── templates/             # Task templates
 │   └── tasks/
 │       ├── bad-impl/
@@ -71,6 +78,38 @@ python -m automaton.dashboard
 - **Tests** are required for any new Python code or significant script logic.
 - **No orchestrator runtime** — keep the framework prompt-driven. Do not add an agent harness.
 - **No Rust rewrite** — Python/Bash are the implementation languages.
+- **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 --validate-folder`**: Detects out-of-order artifacts (phase skipping)
+- **`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.
+
+## Harness Integration
+
+`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.
+3. **Prompt-based rules** (ALLOWED/FORBIDDEN sections) — advisory only, relies on agent discipline.
+
+Modes:
+- `--can-edit --project {p}` — Is editing allowed on this project? (checks for tasks in implement/doc_review)
+- `--can-edit --project {p} --file {path}` — Same, plus file scope check
+- `--can-edit --project {p} --task {t}` — Is this specific task in an edit-allowed phase?
+- `--can-edit --project {p} --task {t} --file {path}` — Same, plus file scope check
+- Add `--json` for machine-readable output
 
 ## Adding or Updating Prompts