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)

README.md

@@ -166,16 +166,80 @@ When a task is decomposed, the Orchestrator creates sub-tasks under `tasks/{pare
 - The parent task is NOT complete until ALL sub-tasks pass
 
 ## Key Components
-- `.agent.md`: Project-specific agent behavior (Autopilot mode, routing rules).
-- `config.md`: Global framework settings (VRAM, model, system requirements).
+- `.agent.md`: Project-specific agent behavior (Autopilot mode, routing rules, optional Agent Configuration for multi-agent).
+- `config.md`: Global framework settings (VRAM, model, system requirements, version).
 - `.rules.md`: Living document of project constraints and past failure modes.
-- `prompts/`: Specialized system prompts for each phase (Research, Design, Test Design, Implement, Bug Finder, Adversarial Bug Finder, Doc Review, Referee, Decompose, etc.).
-- `workflow.md`: The state machine governing the Autopilot lifecycle.
-- `test_design.md`: Produces a TEST_PLAN.md — an explicit test specification before implementation.
-- `decompose.md`: Breaks a task into VRAM-sized sub-tasks.
+- `prompts/`: Specialized system prompts for each phase with ALLOWED/FORBIDDEN sections and approval gates.
+- `workflow.md`: The state machine governing the task lifecycle, with `.state` file as canonical phase indicator.
+- `scripts/status.py`: Enforcement script — task status, phase transitions, approval gates, folder validation, audits, multi-agent claiming.
 - `scripts/vram_detect.py`: Auto-detects GPU VRAM, RAM, model context window, and framework overhead.
 - `contracts/vram_config.md`: Contract for VRAM-aware task decomposition.
 
+## State Enforcement (v2.0)
+
+Automaton v2.0 enforces the state machine computationally, not just via prompts:
+
+- **`.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, Design, Decomposition, and Test Design phases require explicit user approval before proceeding
+- **`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
+- **FORBIDDEN actions in prompts**: Each phase prompt explicitly lists what agents cannot do
+
+### Quick Reference
+
+```bash
+# Create a new task
+python ~/.automaton/scripts/status.py --create-task add-user-auth
+
+# Check task status
+python ~/.automaton/scripts/status.py --task add-user-auth
+
+# List all tasks
+python ~/.automaton/scripts/status.py --list
+
+# Transition to next phase
+python ~/.automaton/scripts/status.py --transition research --task add-user-auth
+python ~/.automaton/scripts/status.py --transition research:awaiting_approval --task add-user-auth
+
+# Approve a phase (after user sign-off)
+python ~/.automaton/scripts/status.py --approve --task add-user-auth
+
+# Validate task folder
+python ~/.automaton/scripts/status.py --validate-folder --task add-user-auth
+
+# Audit all tasks
+python ~/.automaton/scripts/status.py --audit
+
+# Check if code edits are allowed
+python ~/.automaton/scripts/status.py --can-edit --task add-user-auth
+```
+
+### Multi-Agent (Optional)
+
+Add an `Agent Configuration` section to `.agent.md` to enable multi-agent mode:
+
+```markdown
+## Agent Configuration
+Mode: multi-agent
+Agents:
+  - id: researcher
+    phases: [research, decomposition, design, test_design]
+  - id: implementer
+    phases: [implement]
+  - id: bug-hunter
+    phases: [bug_find, adversarial_bug_find]
+  - id: referee
+    phases: [referee]
+  - id: orchestrator
+    phases: [new, complete, human_intervention]
+    role: coordinator
+Lock timeout: 30m
+```
+
+In multi-agent mode, agents claim tasks and discover work via `status.py --claim` and `--next-available`. In single-agent mode (the default), these commands are no-ops.
+
 ## Layered File System
 
 The framework uses a **layered approach** to file management, with a clear precedence:
@@ -212,6 +276,9 @@ The dashboard provides a web-based Kanban board, statistics, and timeline views
 ```bash
 # Start from any project root or ~/.automaton/
 python -m automaton.dashboard
+
+# Or use the convenience wrapper
+bash ~/.automaton/scripts/dashboard.sh
 ```
 
 See `automaton/dashboard/README.md` for full documentation on views, keyboard shortcuts, configuration, and scope detection.