Fix pre-existing issues and update README for v2.0

- Fix _infer_state_from_artifacts: SPEC-only maps to research (was bug_find)
- Fix cmd_validate_folder: corrupted .state files now error instead of silent fallback
- Fix upgrade.sh: remove || true, add python3 check, use git rev-parse --git-dir
- Update README.md with --project flag, --can-edit modes, --upgrade, enforcement layers
- Add 6 new tests for inference and validation fixes
- Complete hook-install-process and readme-upgrade-docs tasks

README.md

@@ -61,6 +61,13 @@ If you prefer to set it up manually, create a `.automaton/` directory in your pr
 - `.agent.md`: Project-specific configuration (Mode, rules, etc.).
 - `.rules.md`: Project-specific constraints and past failure modes.
 
+Then install the git pre-commit hook:
+```bash
+ln -sf ~/.automaton/scripts/git-hooks/pre-commit .git/hooks/pre-commit
+```
+
+This hook blocks commits when no task is in `implement` or `doc_review` phase, preventing accidental code changes without a tracked task.
+
 ---
 
 ## The Autopilot Workflow
@@ -171,9 +178,11 @@ When a task is decomposed, the Orchestrator creates sub-tasks under `tasks/{pare
 - `.rules.md`: Living document of project constraints and past failure modes.
 - `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/status.py`: Enforcement script — task status, phase transitions, approval gates, folder validation, audits, pre-edit hook (`--can-edit`), 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.
+- `scripts/git-hooks/pre-commit`: Blocks commits when no task is in an edit-allowed phase.
+- `contracts/harness-integration.md`: Integration contract for agent harnesses (opencode, aider, etc.).
+- `plugins/automaton-guard/`: opencode plugin that intercepts `edit`/`write` calls and checks `--can-edit` before allowing them.
 
 ## State Enforcement (v2.0)
 
@@ -191,31 +200,61 @@ Automaton v2.0 enforces the state machine computationally, not just via prompts:
 
 ```bash
 # Create a new task
-python ~/.automaton/scripts/status.py --create-task add-user-auth
+python ~/.automaton/scripts/status.py --create-task add-user-auth --project /path/to/project
 
 # Check task status
-python ~/.automaton/scripts/status.py --task add-user-auth
+python ~/.automaton/scripts/status.py --task add-user-auth --project /path/to/project
 
 # List all tasks
-python ~/.automaton/scripts/status.py --list
+python ~/.automaton/scripts/status.py --list --project /path/to/project
 
 # 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
+python ~/.automaton/scripts/status.py --transition research --task add-user-auth --project /path/to/project
+python ~/.automaton/scripts/status.py --transition research:awaiting_approval --task add-user-auth --project /path/to/project
 
 # Approve a phase (after user sign-off)
-python ~/.automaton/scripts/status.py --approve --task add-user-auth
+python ~/.automaton/scripts/status.py --approve --task add-user-auth --project /path/to/project
 
 # Validate task folder
-python ~/.automaton/scripts/status.py --validate-folder --task add-user-auth
+python ~/.automaton/scripts/status.py --validate-folder --task add-user-auth --project /path/to/project
 
 # Audit all tasks
-python ~/.automaton/scripts/status.py --audit
+python ~/.automaton/scripts/status.py --audit --project /path/to/project
 
-# Check if code edits are allowed
-python ~/.automaton/scripts/status.py --can-edit --task add-user-auth
+# Upgrade pre-v2.0 tasks (bootstrap .state files)
+python ~/.automaton/scripts/status.py --upgrade --project /path/to/project
+
+# Check if code edits are allowed (harness integration)
+python ~/.automaton/scripts/status.py --can-edit --project /path/to/project
+python ~/.automaton/scripts/status.py --can-edit --project /path/to/project --file src/main.py
+python ~/.automaton/scripts/status.py --can-edit --project /path/to/project --task add-user-auth --json
 ```
 
+**Important**: Always pass `--project` to ensure correct scoping when multiple projects exist. Without it, `status.py` resolves the project from the current directory and errors if not in a project.
+
+### Untracked Tasks
+
+Tasks without `.state` files are UNTRACKED — all commands (`--transition`, `--can-edit`, `--task`, `--approve`) refuse to operate on them. This prevents agents from working on tasks created before v2.0 state enforcement.
+
+To fix untracked tasks:
+```bash
+# Upgrade a single task
+python ~/.automaton/scripts/status.py --upgrade --task my-old-task --project /path/to/project
+
+# Upgrade all tasks at once
+python ~/.automaton/scripts/status.py --upgrade --project /path/to/project
+```
+
+### Enforcement
+
+The framework enforces the state machine computationally. No phase can be skipped, no approval can be bypassed, and no code edits can happen without a task in an edit-allowed phase. This is enforced through three layers:
+
+1. **Harness pre-edit hook** (`--can-edit`) — blocks edits before they happen. Supported by opencode via the `automaton-guard` plugin.
+2. **Git pre-commit hook** — blocks commits when no task is in `implement` or `doc_review` phase. Works for ALL harnesses.
+3. **Prompt-based rules** (ALLOWED/FORBIDDEN sections) — advisory only, relies on agent discipline.
+
+See `contracts/harness-integration.md` for integration details.
+
 ### Multi-Agent (Optional)
 
 Add an `Agent Configuration` section to `.agent.md` to enable multi-agent mode:
@@ -256,13 +295,49 @@ The framework uses a **layered approach** to file management, with a clear prece
 
 ### Upgrading
 
+#### Updating the framework
+
 The framework reads all base files from `~/.automaton/` at runtime. To update the framework:
 
 ```bash
 cd ~/.automaton && git pull
 ```
 
-This automatically applies changes to all projects — no per-project upgrade needed.
+This automatically applies changes to all projects — no per-project file update needed.
+
+#### Upgrading an existing project to v2.0
+
+If a project was created before v2.0 state enforcement (`.state` files), it needs an upgrade to bootstrap `.state` files and install the pre-commit hook:
+
+```bash
+# From the project root:
+bash ~/.automaton/scripts/upgrade.sh /path/to/project
+```
+
+This will:
+1. Bootstrap `.state` files for all existing tasks (inferring phase from artifacts)
+2. Add a version marker to `~/.automaton/config.md`
+3. Install the git pre-commit hook (blocks commits without a task in implement/doc_review)
+
+You can also upgrade tasks individually:
+```bash
+python ~/.automaton/scripts/status.py --upgrade --task my-task --project /path/to/project
+```
+
+#### Installing the pre-commit hook manually
+
+If you skipped the upgrade script or are setting up a new project:
+
+```bash
+# From the project root:
+ln -sf ~/.automaton/scripts/git-hooks/pre-commit .git/hooks/pre-commit
+```
+
+To verify the hook is working:
+```bash
+python ~/.automaton/scripts/status.py --can-edit --project /path/to/project
+# Should return exit code 1 (DENIED) if no tasks are in implement/doc_review
+```
 
 If a project has stale framework file copies (from the old model), tell the agent:
 > "Upgrade automaton for this project."