Add pre-commit hook installation to onboarding and upgrade processes

- prompts/onboarding.md: Step 2c installs git pre-commit hook for new projects
- scripts/upgrade.sh: Installs pre-commit hook during upgrade (with symlink detection)
- scripts/install.sh: Mentions hook installation in post-install next steps

prompts/onboarding.md

@@ -66,6 +66,15 @@ Verify that the project is set up for v2.0 state enforcement:
 3. If the project has existing tasks, run `python ~/.automaton/scripts/status.py --audit --project {project}` to check for violations or manually created tasks that need `.state` files.
 4. If the project has existing tasks without `.state` files, run `python ~/.automaton/scripts/status.py --upgrade --project {project}` to bootstrap `.state` files from artifact heuristics.
 
+### Step 2c: Pre-Commit Hook Installation
+
+Install the automaton pre-commit hook to block commits when no task is in an edit-allowed phase:
+1. Check if `{project}/.git/hooks/` exists (the project uses git).
+2. If it does, create a symlink: `ln -sf ~/.automaton/scripts/git-hooks/pre-commit {project}/.git/hooks/pre-commit`
+3. If `{project}/.git/hooks/pre-commit` already exists and is not our symlink, warn the user and ask whether to replace it.
+4. Verify the hook: `python ~/.automaton/scripts/status.py --can-edit --project {project}` should return exit code 1 (DENIED) since no tasks exist yet.
+5. Note in the onboarding report whether the hook was installed.
+
 ## Output
 
 Create or update the following inside {project}/.automaton/:

scripts/install.sh

@@ -59,4 +59,10 @@ fi
 
 echo ""
 echo "Installation complete."
-echo "Next step: cd into a project and run the onboarding prompt."
+echo ""
+echo "Next steps:"
+echo "  1. cd into a project and run the onboarding prompt"
+echo "  2. In each project that uses git, install the pre-commit hook:"
+echo "     ln -sf ~/.automaton/scripts/git-hooks/pre-commit .git/hooks/pre-commit"
+echo ""
+echo "This hook blocks commits when no task is in an edit-allowed phase."

scripts/upgrade.sh

@@ -54,4 +54,32 @@ fi
 echo ""
 echo "=== Upgrade Complete ==="
 echo "Run 'python ~/.automaton/scripts/status.py --list --project $PROJECT_DIR' to verify task states."
-echo "Run 'python ~/.automaton/scripts/status.py --audit --project $PROJECT_DIR' to check for violations."
+echo "Run 'python ~/.automaton/scripts/status.py --audit --project $PROJECT_DIR' to check for violations."
+echo ""
+
+# Install pre-commit hook if project uses git
+GIT_DIR="$PROJECT_DIR/.git"
+if [ -d "$GIT_DIR/hooks" ]; then
+    HOOK_TARGET="$GIT_DIR/hooks/pre-commit"
+    HOOK_SOURCE="$FRAMEWORK_DIR/scripts/git-hooks/pre-commit"
+    if [ -f "$HOOK_TARGET" ]; then
+        if [ -L "$HOOK_TARGET" ]; then
+            EXISTING_TARGET="$(readlink "$HOOK_TARGET")"
+            if [ "$EXISTING_TARGET" = "$HOOK_SOURCE" ]; then
+                echo "Pre-commit hook already linked to automaton."
+            else
+                echo "WARNING: pre-commit hook already exists (symlink to: $EXISTING_TARGET)"
+                echo "  To use automaton's hook, run: ln -sf $HOOK_SOURCE $HOOK_TARGET"
+            fi
+        else
+            echo "WARNING: pre-commit hook already exists at $HOOK_TARGET"
+            echo "  To replace it with automaton's hook, run: ln -sf $HOOK_SOURCE $HOOK_TARGET"
+        fi
+    else
+        ln -sf "$HOOK_SOURCE" "$HOOK_TARGET"
+        echo "Installed pre-commit hook at $HOOK_TARGET"
+    fi
+else
+    echo "NOTE: No .git/hooks/ directory found. Install the hook manually if this project uses git:"
+    echo "  ln -sf $FRAMEWORK_DIR/scripts/git-hooks/pre-commit \$PROJECT_DIR/.git/hooks/pre-commit"
+fi

tasks/hook-install-process/.state

@@ -0,0 +1 @@
+implement

tasks/hook-install-process/.state.approvals

@@ -0,0 +1 @@
+research:approved|2026-06-15T18:20:49.509508+00:00|user

tasks/hook-install-process/SPEC.md

@@ -0,0 +1,16 @@
+# Hook Installation in Onboarding and Upgrade
+
+## Goal
+Add pre-commit hook installation to both the new-project onboarding process and the existing-project upgrade process, so enforcement is set up automatically.
+
+## Requirements
+- Onboarding prompt includes a step to install the git pre-commit hook
+- upgrade.sh installs the hook during upgrade (with symlink detection)
+- install.sh mentions hook installation in post-install next steps
+
+## Acceptance Criteria
+- [x] prompts/onboarding.md includes Step 2c for hook installation
+- [x] scripts/upgrade.sh installs hook and detects existing hooks
+- [x] scripts/install.sh mentions hook installation
+- [x] Shell scripts pass syntax check
+- [x] All 200 tests pass