build(hooks): replace hardcoded pre-commit hook with lefthook

Replace the 90-line bash script in .githooks/pre-commit and its
setup-git-hooks.ts installer with a lefthook.yml configuration.

Key change: the entire pre-commit hook is skipped when CI=true, which
means the pi-coding-agent-action's create_pull_request tool commits
cleanly without triggering typecheck + tests. Previously, a hook
failure caused the tool to retry from scratch each time, generating
a new branch on every attempt.

The hook logic is otherwise identical to what it replaced:
- Block stale bun.lockb (Vitest transition guard)
- Block manually committed migration files (ALLOW_MIGRATIONS=1 to bypass)
- Validate changed GitHub Actions workflow YAML
- Biome format staged files in-place and re-stage
- Biome lint
- TypeScript typecheck
- Frontend build (when frontend files changed)
- Backend tests (when backend src files changed)

Local dev: hooks skip in CI, run normally everywhere else.
Hook bypass: LEFTHOOK=0 git commit (replaces --no-verify)

prepare script updated to: bunx lefthook install --reset-hooks-path
(clears any global core.hooksPath before installing)

Author: mcowger

.githooks/pre-commit

@@ -9,7 +9,7 @@
 ## Critical Requirements
 
 - **NEVER** commit or push without explicit request, unless running in CI (`CI=true`). In local/interactive sessions, every individual commit and push requires explicit user permission — even if permission was granted earlier in the same session. Do not assume continued consent. In GitHub Actions (CI), commits and pushes are expected as part of the workflow and do not require per-instance approval.
-- **NEVER** use --no-verify without user permission.
+- **NEVER** use --no-verify or LEFTHOOK=0 without user permission.
 - **AVOID** search library type definitions for documentation. Use search and context skills where available first.
 - **NEVER** produce implementation or summary documents unless specifically requested.
 - **NEVER** edit existing migration files or manually create SQL migrations. See [Migrations](#migrations) below.

AGENTS.md

@@ -8,7 +8,7 @@ cd plexus
 bun install
 ```
 
-Running `bun install` automatically configures git hooks (via the `prepare` script). No extra setup is needed.
+Running `bun install` automatically installs git hooks via [Lefthook](https://github.com/evilmartians/lefthook) (the `prepare` script runs `lefthook install`). No extra setup is needed.
 
 ## Database Schema Changes
 
@@ -40,6 +40,14 @@ git reset HEAD -- packages/backend/drizzle/migrations/ packages/backend/drizzle/
 
 Then commit again with only your schema `.ts` files.
 
+### Skipping hooks
+
+The hooks are skipped automatically when `CI=true` (GitHub Actions). To skip locally in exceptional circumstances:
+
+```bash
+LEFTHOOK=0 git commit -m "..."
+```
+
 ## Drizzle Config Files
 
 The project uses separate Drizzle ORM config files for each database dialect:

CONTRIBUTING.md

@@ -0,0 +1,88 @@
+pre-commit:
+  # Skip the entire hook in CI — GitHub Actions runs each check independently
+  # in dedicated workflow steps, making the hook redundant and harmful
+  # (failed hook = create_pull_request retries with a new branch each time).
+  skip:
+    - CI: "true"
+
+  commands:
+    # --- Block stale bun.lockb (Vitest transition cutoff 2025-04-18) ----------
+    lockfile-check:
+      skip:
+        - CI: "true"
+      run: |
+        CUTOFF="2025-04-18"
+        MTIME=$(stat -f "%Sm" -t "%Y-%m-%d" bun.lockb 2>/dev/null \
+             || stat -c "%y" bun.lockb 2>/dev/null | cut -d' ' -f1 \
+             || echo "1970-01-01")
+        if [ "$MTIME" \< "$CUTOFF" ]; then
+          echo ""
+          echo "[pre-commit] ERROR: bun.lockb is from $MTIME, before $CUTOFF."
+          echo "The project switched to Vitest. Run:  bun install"
+          echo ""
+          exit 1
+        fi
+
+    # --- Block manually committed migration files ----------------------------
+    no-migrations:
+      skip:
+        - CI: "true"
+      run: |
+        if [ "${ALLOW_MIGRATIONS:-}" = "1" ]; then exit 0; fi
+        migration_files=$(git diff --cached --name-only -- \
+          'packages/backend/drizzle/migrations/' \
+          'packages/backend/drizzle/migrations_pg/' || true)
+        if [ -n "$migration_files" ]; then
+          echo ""
+          echo "[pre-commit] ERROR: Migration files should not be committed manually."
+          echo "Migrations are auto-generated on main by CI after schema changes merge."
+          echo ""
+          echo "Blocked files:"
+          echo "$migration_files" | sed 's/^/  /'
+          echo ""
+          echo "To remove them:  git reset HEAD -- packages/backend/drizzle/migrations/ packages/backend/drizzle/migrations_pg/"
+          echo "To bypass (maintainers only):  ALLOW_MIGRATIONS=1 git commit ..."
+          echo ""
+          exit 1
+        fi
+
+    # --- Validate changed GitHub Actions workflow YAML -----------------------
+    workflow-yaml:
+      glob: ".github/workflows/*.{yml,yaml}"
+      run: |
+        for f in {staged_files}; do
+          bun -e "
+            const fs = require('fs');
+            const yaml = require('./packages/backend/node_modules/yaml');
+            try {
+              yaml.parse(fs.readFileSync('$f', 'utf8'));
+              console.log('  ✓ $f');
+            } catch (e) {
+              console.error('  ✗ $f:', e.message);
+              process.exit(1);
+            }
+          " || exit 1
+        done
+
+    # --- Biome: format staged source files in-place and re-stage -------------
+    biome-format:
+      glob: "*.{ts,tsx,js,jsx,json}"
+      run: bunx biome format --write {staged_files} && git add {staged_files}
+
+    # --- Biome: lint all sources ---------------------------------------------
+    biome-lint:
+      run: bunx biome lint .
+
+    # --- TypeScript type-check across all packages ---------------------------
+    typecheck:
+      run: bun run typecheck
+
+    # --- Frontend build (catches broken imports/exports) ---------------------
+    frontend-build:
+      glob: "packages/frontend/src/**"
+      run: bun run build:frontend
+
+    # --- Backend tests (only when backend source changes) --------------------
+    backend-tests:
+      glob: "packages/backend/src/**"
+      run: cd packages/backend && bun run test

bun.lock

@@ -6,6 +6,7 @@
     "@redocly/cli": "^2.30.1",
     "agent-browser": "^0.26.0",
     "bun-types": "latest",
+    "lefthook": "^2.1.6",
     "octokit": "^5.0.5",
     "pi-agent-browser-native": "latest",
     "vitest": "^4.1.5"
@@ -27,8 +28,7 @@
     "release": "bun run scripts/release.ts",
     "populate-dev": "bun run scripts/populate-dev.ts",
     "clear-dev": "bun run scripts/clear-dev.ts",
-    "prepare": "bun run scripts/setup-git-hooks.ts --no-fail --quiet",
-    "setup:hooks": "bun run scripts/setup-git-hooks.ts",
+    "prepare": "bunx lefthook install --reset-hooks-path",
     "format": "bunx biome format --write .",
     "format:check": "bunx biome format .",
     "lint": "bunx biome lint --write .",