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)

.onboarding.md

@@ -38,44 +38,65 @@ Instead of memorizing trigger phrases for each phase, you can just say **"orches
 **Output**: `SPEC.md`
 **Trigger**: *"Research {task-description}"* (or just *"orchestrate"* in manual mode)
 **Interaction**: Agent will grill you for requirements, edge cases, and constraints. Present draft for review. Get your sign-off before finalizing.
+**State transition**: `new` → `research` → `research:awaiting_approval` (awaiting your sign-off) → `research:approved` (after you say "APPROVED")
 
 ### Phase 1b: Design (Optional)
 **Template**: `prompts/design.md`
 **Output**: `DESIGN.md`
 **Trigger**: *"Design the {task-name} task"* (or just *"orchestrate"* in manual mode)
 **Interaction**: Agent will grill you for design decisions, trade-offs, and constraints. Present draft for review. Get your sign-off before finalizing.
+**State transition**: `design` → `design:awaiting_approval` → `design:approved`
 
 ### Phase 1c: Test Design (Optional)
 **Template**: `prompts/test_design.md`
 **Output**: `TEST_PLAN.md`
 **Trigger**: *"Design tests for the {task-name} task"* (or just *"orchestrate"* in manual mode)
 **Interaction**: Agent will grill you for test coverage, edge cases, and test strategy. Present draft for review. Get your sign-off before finalizing.
+**State transition**: `test_design` → `test_design:awaiting_approval` → `test_design:approved`
 
 ### Phase 2: Implementation
 **Template**: `prompts/implement.md`
 **Output**: Code changes + test results
 **Trigger**: *"Implement the {task-name} task"* (or just *"orchestrate"* in manual mode)
-**Note**: The implementer follows the TEST_PLAN.md (if present) and implements code with tests using TDD.
+**Note**: The implementer follows the TEST_PLAN.md (if present) and implements code with tests using TDD. No approval gate — transitions directly to bug_find.
 
 ### Phase 3: Bug Finding
 **Template**: `prompts/bug_finder.md`
 **Output**: `BUG_REPORT.md`
 **Trigger**: *"Find bugs in the {task-name} task"* (or just *"orchestrate"* in manual mode)
+**State transition**: `bug_find` (no approval gate)
 
 ### Phase 4: Adversarial Verification
 **Template**: `prompts/adversarial_bug_find.md`
 **Output**: `ADVERSARIAL_BUG_REPORT.md`
 **Trigger**: *"Perform adversarial bug find for {task-name}"* (or just *"orchestrate"* in manual mode)
+**State transition**: `adversarial_bug_find` (no approval gate)
 
 ### Phase 5: Documentation Review
 **Template**: `prompts/doc_review.md`
 **Output**: `DOC_REVIEW.md`
 **Trigger**: *"Review docs for the {task-name} task"* (or just *"orchestrate"* in manual mode)
+**State transition**: `doc_review` (no approval gate)
 
 ### Phase 6: Referee
 **Template**: `prompts/referee.md`
 **Output**: `VERDICT.md`
 **Trigger**: *"Review the {task-name} task"* (or just *"orchestrate"* in manual mode)
+**State transition**: `referee` → `complete` or `human_intervention`
+
+## State Enforcement (v2.0)
+
+All phase transitions are enforced by `status.py`:
+- Tasks are created with `python ~/.automaton/scripts/status.py --create-task {name} --project {project}`
+- Phases are transitioned with `python ~/.automaton/scripts/status.py --transition {phase} --task {name} --project {project}`
+- Approvals are granted with `python ~/.automaton/scripts/status.py --approve --task {name} --project {project}`
+- Folders are validated with `python ~/.automaton/scripts/status.py --validate-folder --task {name} --project {project}`
+- All tasks are audited with `python ~/.automaton/scripts/status.py --audit --project {project}`
+- Pre-v2.0 tasks are upgraded with `python ~/.automaton/scripts/status.py --upgrade --project {project}`
+
+The `.state` file in each task folder is the single source of truth for the task's current phase. Never create task directories manually — always use `status.py --create-task`. Tasks without `.state` files are UNTRACKED and all commands refuse to operate on them. Run `status.py --upgrade` to bootstrap `.state` files for existing tasks.
+
+**Important**: Always pass `--project {project}` to ensure correct scoping. Without it, `status.py` resolves the project from the current working directory, which can target the wrong project when multiple projects exist on the same machine.
 
 ## Prompt Rendering Convention