chore: migrate pre-commit hooks to lefthook for improved performance and consistency

2026-03-07 02:20:29 +00:00
parent 37471141e8
commit c665f62700
23 changed files with 414 additions and 270 deletions
--- a/.dockerignore
+++ b/.dockerignore
@@ -9,13 +9,12 @@
 .git/
 .gitignore
 .github/
-.pre-commit-config.yaml
 codecov.yml
 .goreleaser.yaml
 .sourcery.yml

 # -----------------------------------------------------------------------------
-# Python (pre-commit, tooling)
+# Python (tooling)
 # -----------------------------------------------------------------------------
 __pycache__/
 *.py[cod]
--- a/.github/agents/Backend_Dev.agent.md
+++ b/.github/agents/Backend_Dev.agent.md
@@ -45,7 +45,7 @@ Your priority is writing code that is clean, tested, and secure by default.
    - **Step 3 (The Logic)**:
        - Implement the handler in `internal/api/handlers`.
    - **Step 4 (Lint and Format)**:
-        - Run `pre-commit run --all-files` to ensure code quality.
+        - Run `lefthook run pre-commit` to ensure code quality.
    - **Step 5 (The Green Light)**:
        - Run `go test ./...`.
        - **CRITICAL**: If it fails, fix the *Code*, NOT the *Test* (unless the test was wrong about the contract).
@@ -57,8 +57,7 @@ Your priority is writing code that is clean, tested, and secure by default.
        - **Conditional GORM Gate**: If task changes include model/database-related
            files (`backend/internal/models/**`, GORM query logic, migrations), run
            GORM scanner in check mode and treat CRITICAL/HIGH findings as blocking:
-                - Run: `pre-commit run --hook-stage manual gorm-security-scan --all-files`
-                    OR `./scripts/scan-gorm-security.sh --check`
+                - Run: `lefthook run pre-commit` (which includes manual gorm-security-scan) OR `./scripts/scan-gorm-security.sh --check`
                - Policy: Process-blocking gate even while automation is manual stage
    - **Local Patch Coverage Preflight (MANDATORY)**: Run VS Code task `Test: Local Patch Report` or `bash scripts/local-patch-report.sh` before backend coverage runs.
        - Ensure artifacts exist: `test-results/local-patch-report.md` and `test-results/local-patch-report.json`.
@@ -69,9 +68,9 @@ Your priority is writing code that is clean, tested, and secure by default.
        - **Manual Script**: Execute `/projects/Charon/scripts/go-test-coverage.sh` from the root directory
        - **Minimum**: 85% coverage (configured via `CHARON_MIN_COVERAGE` or `CPM_MIN_COVERAGE`)
        - **Critical**: If coverage drops below threshold, write additional tests immediately. Do not skip this step.
-        - **Why**: Coverage tests are in manual stage of pre-commit for performance. You MUST run them via VS Code tasks or scripts before completing your task.
+        - **Why**: Coverage tests are in manual stage of lefthook for performance. You MUST run them via VS Code tasks or scripts before completing your task.
    - Ensure coverage goals are met as well as all tests pass. Just because Tests pass does not mean you are done. Goal Coverage Needs to be met even if the tests to get us there are outside the scope of your task. At this point, your task is to maintain coverage goal and all tests pass because we cannot commit changes if they fail.
-    - Run `pre-commit run --all-files` as final check (this runs fast hooks only; coverage was verified above).
+    - Run `lefthook run pre-commit` as final check (this runs fast hooks only; coverage was verified above).
 </workflow>

 <constraints>
--- a/.github/agents/Frontend_Dev.agent.md
+++ b/.github/agents/Frontend_Dev.agent.md
@@ -48,7 +48,7 @@ You are a SENIOR REACT/TYPESCRIPT ENGINEER with deep expertise in:
   - Run tests with `npm test` in `frontend/` directory

 4. **Quality Checks**:
-   - Run `pre-commit run --all-files` to ensure linting and formatting
+   - Run `lefthook run pre-commit` to ensure linting and formatting
   - Ensure accessibility with proper ARIA attributes
 </workflow>

--- a/.github/agents/Management.agent.md
+++ b/.github/agents/Management.agent.md
@@ -73,7 +73,7 @@ You are "lazy" in the smartest way possible. You never do what a subordinate can
    - **Supervisor**: Call `Supervisor` to review the implementation against the plan. Provide feedback and ensure alignment with best practices.

 6. **Phase 6: Audit**:
-    - **QA**: Call `QA_Security` to meticulously test current implementation as well as regression test. Run all linting, security tasks, and manual pre-commit checks. Write a report to `docs/reports/qa_report.md`. Start back at Phase 1 if issues are found.
+    - **QA**: Call `QA_Security` to meticulously test current implementation as well as regression test. Run all linting, security tasks, and manual lefthook checks. Write a report to `docs/reports/qa_report.md`. Start back at Phase 1 if issues are found.

 7. **Phase 7: Closure**:
    - **Docs**: Call `Docs_Writer`.
--- a/.github/instructions/copilot-instructions.md
+++ b/.github/instructions/copilot-instructions.md
@@ -67,7 +67,7 @@ Before proposing ANY code change or fix, you must build a mental map of the feat

 - **Run**: `cd backend && go run ./cmd/api`.
 - **Test**: `go test ./...`.
- **Static Analysis (BLOCKING)**: Fast linters run automatically on every commit via pre-commit hooks.
+- **Static Analysis (BLOCKING)**: Fast linters run automatically on every commit via lefthook pre-commit-phase hooks.
  - **Staticcheck errors MUST be fixed** - commits are BLOCKED until resolved
  - Manual run: `make lint-fast` or VS Code task "Lint: Staticcheck (Fast)"
  - Staticcheck-only: `make lint-staticcheck-only`
@@ -79,7 +79,7 @@ Before proposing ANY code change or fix, you must build a mental map of the feat
 - **Security**: Sanitize all file paths using `filepath.Clean`. Use `fmt.Errorf("context: %w", err)` for error wrapping.
 - **Graceful Shutdown**: Long-running work must respect `server.Run(ctx)`.

-### Troubleshooting Pre-Commit Staticcheck Failures
+### Troubleshooting Lefthook Staticcheck Failures

 **Common Issues:**

@@ -175,7 +175,7 @@ Before marking an implementation task as complete, perform the following in orde
    - **Exclusions**: Skip this gate for docs-only (`**/*.md`) or frontend-only (`frontend/**`) changes
    - **Run One Of**:
        - VS Code task: `Lint: GORM Security Scan`
-        - Pre-commit: `pre-commit run --hook-stage manual gorm-security-scan --all-files`
+        - Lefthook: `lefthook run pre-commit` (includes gorm-security-scan)
        - Direct: `./scripts/scan-gorm-security.sh --check`
        - **Gate Enforcement**: DoD is process-blocking until scanner reports zero
            CRITICAL/HIGH findings, even while automation remains in manual stage
@@ -189,15 +189,15 @@ Before marking an implementation task as complete, perform the following in orde
    - **Expected Behavior**: Report may warn (non-blocking rollout), but artifact generation is mandatory.

 3. **Security Scans** (MANDATORY - Zero Tolerance):
-    - **CodeQL Go Scan**: Run VS Code task "Security: CodeQL Go Scan (CI-Aligned)" OR `pre-commit run codeql-go-scan --all-files`
+    - **CodeQL Go Scan**: Run VS Code task "Security: CodeQL Go Scan (CI-Aligned)" OR `lefthook run pre-commit`
        - Must use `security-and-quality` suite (CI-aligned)
        - **Zero high/critical (error-level) findings allowed**
        - Medium/low findings should be documented and triaged
-    - **CodeQL JS Scan**: Run VS Code task "Security: CodeQL JS Scan (CI-Aligned)" OR `pre-commit run codeql-js-scan --all-files`
+    - **CodeQL JS Scan**: Run VS Code task "Security: CodeQL JS Scan (CI-Aligned)" OR `lefthook run pre-commit`
        - Must use `security-and-quality` suite (CI-aligned)
        - **Zero high/critical (error-level) findings allowed**
        - Medium/low findings should be documented and triaged
-    - **Validate Findings**: Run `pre-commit run codeql-check-findings --all-files` to check for HIGH/CRITICAL issues
+    - **Validate Findings**: Run `lefthook run pre-commit` to check for HIGH/CRITICAL issues
    - **Trivy Container Scan**: Run VS Code task "Security: Trivy Scan" for container/dependency vulnerabilities
    - **Results Viewing**:
        - Primary: VS Code SARIF Viewer extension (`MS-SarifVSCode.sarif-viewer`)
@@ -210,7 +210,7 @@ Before marking an implementation task as complete, perform the following in orde
        - Database creation: `--threads=0 --overwrite`
        - Analysis: `--sarif-add-baseline-file-info`

-4. **Pre-Commit Triage**: Run `pre-commit run --all-files`.
+4. **Lefthook Triage**: Run `lefthook run pre-commit`.
    - If errors occur, **fix them immediately**.
    - If logic errors occur, analyze and propose a fix.
    - Do not output code that violates pre-commit standards.
--- a/.github/instructions/go.instructions.md
+++ b/.github/instructions/go.instructions.md
@@ -353,7 +353,7 @@ Follow idiomatic Go practices and community standards when writing Go code. Thes
 ### Development Practices

 - Run tests before committing
- Use pre-commit hooks for formatting and linting
+- Use lefthook pre-commit-phase hooks for formatting and linting
 - Keep commits focused and atomic
 - Write meaningful commit messages
 - Review diffs before committing
--- a/.github/instructions/structure.instructions.md
+++ b/.github/instructions/structure.instructions.md
@@ -9,7 +9,7 @@ description: 'Repository structure guidelines to maintain organized file placeme

 The repository root should contain ONLY:

- Essential config files (`.gitignore`, `.pre-commit-config.yaml`, `Makefile`, etc.)
+- Essential config files (`.gitignore`, `Makefile`, etc.)
 - Standard project files (`README.md`, `CONTRIBUTING.md`, `LICENSE`, `CHANGELOG.md`)
 - Go workspace files (`go.work`, `go.work.sum`)
 - VS Code workspace (`Chiron.code-workspace`)
--- a/.github/skills/README.md
+++ b/.github/skills/README.md
@@ -63,7 +63,7 @@ Agent Skills are self-documenting, AI-discoverable task definitions that combine

 | Skill Name | Category | Description | Status |
 |------------|----------|-------------|--------|
-| [qa-precommit-all](./qa-precommit-all.SKILL.md) | qa | Run all pre-commit hooks on entire codebase | ✅ Active |
+| [qa-lefthook-all](./qa-lefthook-all.SKILL.md) | qa | Run all lefthook pre-commit‑phase hooks on entire codebase | ✅ Active |

 ### Utility Skills

--- a/.github/skills/qa-lefthook-all.SKILL.md
+++ b/.github/skills/qa-lefthook-all.SKILL.md
@@ -0,0 +1,349 @@
+---
+# agentskills.io specification v1.0
+name: "qa-lefthook-all"
+version: "1.0.0"
+description: "Run all lefthook pre-commit-phase hooks for comprehensive code quality validation"
+author: "Charon Project"
+license: "MIT"
+tags:
+  - "qa"
+  - "quality"
+  - "pre-commit"
+  - "linting"
+  - "validation"
+compatibility:
+  os:
+    - "linux"
+    - "darwin"
+  shells:
+    - "bash"
+requirements:
+  - name: "python3"
+    version: ">=3.8"
+    optional: false
+  - name: "lefthook"
+    version: ">=0.14"
+    optional: false
+environment_variables:
+    - name: "SKIP"
+    description: "Comma-separated list of hook IDs to skip"
+    default: ""
+    required: false
+parameters:
+  - name: "files"
+    type: "string"
+    description: "Specific files to check (default: all staged files)"
+    default: "--all-files"
+    required: false
+outputs:
+  - name: "validation_report"
+    type: "stdout"
+    description: "Results of all pre-commit hook executions"
+  - name: "exit_code"
+    type: "number"
+    description: "0 if all hooks pass, non-zero if any fail"
+metadata:
+  category: "qa"
+  subcategory: "quality"
+  execution_time: "medium"
+  risk_level: "low"
+  ci_cd_safe: true
+  requires_network: false
+  idempotent: true
+---
+
+# QA Pre-commit All
+
+## Overview
+
+Executes all configured lefthook pre-commit-phase hooks to validate code quality, formatting, security, and best practices across the entire codebase. This skill runs checks for Python, Go, JavaScript/TypeScript, Markdown, YAML, and more.
+
+This skill is designed for CI/CD pipelines and local quality validation before committing code.
+
+## Prerequisites
+
+- Python 3.8 or higher installed and in PATH
+- Python virtual environment activated (`.venv`)
+- Pre-commit installed in virtual environment: `pip install pre-commit`
+- Pre-commit hooks installed: `pre-commit install`
+- All language-specific tools installed (Go, Node.js, etc.)
+
+## Usage
+
+### Basic Usage
+
+Run all pre-commit-phase hooks on all files:
+
+```bash
+cd /path/to/charon
+lefthook run pre-commit
+```
+
+### Staged Files Only
+
+Run lefthook on staged files only (faster):
+
+```bash
+lefthook run pre-commit --staged
+```
+
+### Specific Hook
+
+Run only a specific hook by ID:
+
+```bash
+lefthook run pre-commit --hooks=trailing-whitespace
+```
+
+### Skip Specific Hooks
+
+Skip certain hooks during execution:
+
+```bash
+SKIP=prettier,eslint .github/skills/scripts/skill-runner.sh qa-precommit-all
+```
+
+## Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| files     | string | No     | --all-files | File selection mode (--all-files or staged) |
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| SKIP | No | "" | Comma-separated hook IDs to skip |
+| PRE_COMMIT_HOME | No | ~/.cache/pre-commit | Pre-commit cache directory |
+
+## Outputs
+
+- **Success Exit Code**: 0 (all hooks passed)
+- **Error Exit Codes**: Non-zero (one or more hooks failed)
+- **Output**: Detailed results from each hook
+
+## Pre-commit Hooks Included
+
+The following hooks are configured in `.pre-commit-config.yaml`:
+
+### General Hooks
+- **trailing-whitespace**: Remove trailing whitespace
+- **end-of-file-fixer**: Ensure files end with newline
+- **check-yaml**: Validate YAML syntax
+- **check-json**: Validate JSON syntax
+- **check-merge-conflict**: Detect merge conflict markers
+- **check-added-large-files**: Prevent committing large files
+
+### Python Hooks
+- **black**: Code formatting
+- **isort**: Import sorting
+- **flake8**: Linting
+- **mypy**: Type checking
+
+### Go Hooks
+- **gofmt**: Code formatting
+- **go-vet**: Static analysis
+- **golangci-lint**: Comprehensive linting
+
+### JavaScript/TypeScript Hooks
+- **prettier**: Code formatting
+- **eslint**: Linting and code quality
+
+### Markdown Hooks
+- **markdownlint**: Markdown linting and formatting
+
+### Security Hooks
+- **detect-private-key**: Prevent committing private keys
+- **detect-aws-credentials**: Prevent committing AWS credentials
+
+## Examples
+
+### Example 1: Full Quality Check
+
+```bash
+# Run all hooks on all files
+source .venv/bin/activate
+.github/skills/scripts/skill-runner.sh qa-precommit-all
+```
+
+Output:
+```
+Trim Trailing Whitespace.....................................Passed
+Fix End of Files.............................................Passed
+Check Yaml...................................................Passed
+Check JSON...................................................Passed
+Check for merge conflicts....................................Passed
+Check for added large files..................................Passed
+black........................................................Passed
+isort........................................................Passed
+prettier.....................................................Passed
+eslint.......................................................Passed
+markdownlint.................................................Passed
+```
+
+### Example 2: Quick Staged Files Check
+
+```bash
+# Run only on staged files (faster for pre-commit)
+.github/skills/scripts/skill-runner.sh qa-precommit-all staged
+```
+
+### Example 3: Skip Slow Hooks
+
+```bash
+# Skip time-consuming hooks for quick validation
+SKIP=golangci-lint,mypy .github/skills/scripts/skill-runner.sh qa-precommit-all
+```
+
+### Example 4: CI/CD Pipeline Integration
+
+```yaml
+# GitHub Actions example
+- name: Set up Python
+  uses: actions/setup-python@v4
+  with:
+    python-version: '3.11'
+
+- name: Install pre-commit
+  run: pip install pre-commit
+
+- name: Run QA Pre-commit Checks
+  run: .github/skills/scripts/skill-runner.sh qa-precommit-all
+```
+
+### Example 5: Auto-fix Mode
+
+```bash
+# Some hooks can auto-fix issues
+# Run twice: first to fix, second to validate
+.github/skills/scripts/skill-runner.sh qa-precommit-all || \
+.github/skills/scripts/skill-runner.sh qa-precommit-all
+```
+
+## Error Handling
+
+### Common Issues
+
+**Virtual environment not activated**:
+```bash
+Error: pre-commit not found
+Solution: source .venv/bin/activate
+```
+
+**Pre-commit not installed**:
+```bash
+Error: pre-commit command not available
+Solution: pip install pre-commit
+```
+
+**Hooks not installed**:
+```bash
+Error: Run 'pre-commit install'
+Solution: pre-commit install
+```
+
+**Hook execution failed**:
+```bash
+Hook X failed
+Solution: Review error output and fix reported issues
+```
+
+**Language tool missing**:
+```bash
+Error: golangci-lint not found
+Solution: Install required language tools
+```
+
+## Exit Codes
+
+- **0**: All hooks passed
+- **1**: One or more hooks failed
+- **Other**: Hook execution error
+
+## Hook Fixing Strategies
+
+### Auto-fixable Issues
+These hooks automatically fix issues:
+- `trailing-whitespace`
+- `end-of-file-fixer`
+- `black`
+- `isort`
+- `prettier`
+- `gofmt`
+
+**Workflow**: Run pre-commit, review changes, commit fixed files
+
+### Manual Fixes Required
+These hooks only report issues:
+- `check-yaml`
+- `check-json`
+- `flake8`
+- `eslint`
+- `markdownlint`
+- `go-vet`
+- `golangci-lint`
+
+**Workflow**: Review errors, manually fix code, re-run pre-commit
+
+## Related Skills
+
+- [test-backend-coverage](./test-backend-coverage.SKILL.md) - Backend test coverage
+- [test-frontend-coverage](./test-frontend-coverage.SKILL.md) - Frontend test coverage
+- [security-scan-trivy](./security-scan-trivy.SKILL.md) - Security scanning
+
+## Notes
+
+- Pre-commit hooks cache their environments for faster execution
+- First run may be slow while environments are set up
+- Subsequent runs are much faster (seconds vs minutes)
+- Hooks run in parallel where possible
+- Failed hooks stop execution (fail-fast behavior)
+- Use `SKIP` to bypass specific hooks temporarily
+- Recommended to run before every commit
+- Can be integrated into Git pre-commit hook for automatic checks
+- Cache location: `~/.cache/pre-commit` (configurable)
+
+## Performance Tips
+
+- **Initial Setup**: First run takes longer (installing hook environments)
+- **Incremental**: Run on staged files only for faster feedback
+- **Parallel**: Pre-commit runs compatible hooks in parallel
+- **Cache**: Hook environments are cached and reused
+- **Skip**: Use `SKIP` to bypass slow hooks during development
+
+## Integration with Git
+
+To automatically run on every commit:
+
+```bash
+# Install Git pre-commit hook
+pre-commit install
+
+# Now pre-commit runs automatically on git commit
+git commit -m "Your commit message"
+```
+
+To bypass pre-commit hook temporarily:
+
+```bash
+git commit --no-verify -m "Emergency commit"
+```
+
+## Configuration
+
+Pre-commit configuration is in `.pre-commit-config.yaml`. To update hooks:
+
+```bash
+# Update to latest versions
+pre-commit autoupdate
+
+# Clean cache and re-install
+pre-commit clean
+pre-commit install --install-hooks
+```
+
+---
+
+**Last Updated**: 2025-12-20
+**Maintained by**: Charon Project
+**Source**: `pre-commit run --all-files`
--- a/.github/skills/qa-precommit-all.SKILL.md
+++ b/.github/skills/qa-precommit-all.SKILL.md
@@ -1,8 +1,8 @@
 ---
 # agentskills.io specification v1.0
-name: "qa-precommit-all"
+name: "qa-lefthook-all"
 version: "1.0.0"
-description: "Run all pre-commit hooks for comprehensive code quality validation"
+description: "Run all lefthook pre-commit-phase hooks for comprehensive code quality validation"
 author: "Charon Project"
 license: "MIT"
 tags:
@@ -21,15 +21,11 @@ requirements:
  - name: "python3"
    version: ">=3.8"
    optional: false
-  - name: "pre-commit"
-    version: ">=2.0"
+  - name: "lefthook"
+    version: ">=0.14"
    optional: false
 environment_variables:
-  - name: "PRE_COMMIT_HOME"
-    description: "Pre-commit cache directory"
-    default: "~/.cache/pre-commit"
-    required: false
-  - name: "SKIP"
+    - name: "SKIP"
    description: "Comma-separated list of hook IDs to skip"
    default: ""
    required: false
@@ -60,7 +56,7 @@ metadata:

 ## Overview

-Executes all configured pre-commit hooks to validate code quality, formatting, security, and best practices across the entire codebase. This skill runs checks for Python, Go, JavaScript/TypeScript, Markdown, YAML, and more.
+Executes all configured lefthook pre-commit-phase hooks to validate code quality, formatting, security, and best practices across the entire codebase. This skill runs checks for Python, Go, JavaScript/TypeScript, Markdown, YAML, and more.

 This skill is designed for CI/CD pipelines and local quality validation before committing code.

@@ -76,19 +72,19 @@ This skill is designed for CI/CD pipelines and local quality validation before c

 ### Basic Usage

-Run all hooks on all files:
+Run all pre-commit-phase hooks on all files:

 ```bash
 cd /path/to/charon
-.github/skills/scripts/skill-runner.sh qa-precommit-all
+lefthook run pre-commit
 ```

 ### Staged Files Only

-Run hooks on staged files only (faster):
+Run lefthook on staged files only (faster):

 ```bash
-.github/skills/scripts/skill-runner.sh qa-precommit-all staged
+lefthook run pre-commit --staged
 ```

 ### Specific Hook
@@ -96,7 +92,7 @@ Run hooks on staged files only (faster):
 Run only a specific hook by ID:

 ```bash
-SKIP="" .github/skills/scripts/skill-runner.sh qa-precommit-all trailing-whitespace
+lefthook run pre-commit --hooks=trailing-whitespace
 ```

 ### Skip Specific Hooks
--- a/.github/skills/security-scan-codeql.SKILL.md
+++ b/.github/skills/security-scan-codeql.SKILL.md
@@ -251,7 +251,7 @@ Solution: Verify source-root points to correct directory

 - [security-scan-trivy](./security-scan-trivy.SKILL.md) - Container/dependency vulnerabilities
 - [security-scan-go-vuln](./security-scan-go-vuln.SKILL.md) - Go-specific CVE checking
- [qa-precommit-all](./qa-precommit-all.SKILL.md) - Pre-commit quality checks
+- [qa-lefthook-all](./qa-lefthook-all.SKILL.md) - Lefthook pre-commit-phase quality checks

 ## CI Alignment

--- a/.github/skills/security-scan-gorm.SKILL.md
+++ b/.github/skills/security-scan-gorm.SKILL.md
@@ -545,7 +545,7 @@ Solution: Add suppression comment: // gorm-scanner:ignore [reason]

 - [security-scan-trivy](./security-scan-trivy.SKILL.md) - Container vulnerability scanning
 - [security-scan-codeql](./security-scan-codeql.SKILL.md) - Static analysis for Go/JS
- [qa-precommit-all](./qa-precommit-all.SKILL.md) - Pre-commit quality checks
+- [qa-lefthook-all](./qa-lefthook-all.SKILL.md) - Lefthook pre-commit-phase quality checks

 ## Best Practices

--- a/.github/skills/security-scan-trivy.SKILL.md
+++ b/.github/skills/security-scan-trivy.SKILL.md
@@ -227,7 +227,7 @@ Solution: Review and remediate reported vulnerabilities
 ## Related Skills

 - [security-scan-go-vuln](./security-scan-go-vuln.SKILL.md) - Go-specific vulnerability checking
- [qa-precommit-all](./qa-precommit-all.SKILL.md) - Pre-commit quality checks
+- [qa-lefthook-all](./qa-lefthook-all.SKILL.md) - Lefthook pre-commit-phase quality checks

 ## Notes

--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,211 +0,0 @@
-# NOTE: golangci-lint-fast now includes test files (_test.go) to catch security
-# issues earlier. The fast config uses gosec with critical-only checks (G101,
-# G110, G305, G401, G501, G502, G503) for acceptable performance.
-# Last updated: 2026-02-02
-
-repos:
-  - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v6.0.0
-    hooks:
-      - id: end-of-file-fixer
-        exclude: '^(frontend/(coverage|dist|node_modules|\.vite)/|.*\.tsbuildinfo$)'
-      - id: trailing-whitespace
-        exclude: '^(frontend/(coverage|dist|node_modules|\.vite)/|.*\.tsbuildinfo$)'
-      - id: check-yaml
-      - id: check-added-large-files
-        args: ['--maxkb=2500']
-  - repo: https://github.com/shellcheck-py/shellcheck-py
-    rev: v0.10.0.1
-    hooks:
-      - id: shellcheck
-        name: shellcheck
-        exclude: '^(frontend/(coverage|dist|node_modules|\.vite)/|test-results|codeql-agent-results)/'
-        args: ['--severity=error']
-  - repo: https://github.com/rhysd/actionlint
-    rev: v1.7.10
-    hooks:
-      - id: actionlint
-        name: actionlint (GitHub Actions)
-        files: '^\.github/workflows/.*\.ya?ml$'
-  - repo: local
-    hooks:
-      - id: dockerfile-check
-        name: dockerfile validation
-        entry: tools/dockerfile_check.sh
-        language: script
-        files: "Dockerfile.*"
-        pass_filenames: true
-      - id: go-test-coverage
-        name: Go Test Coverage (Manual)
-        entry: scripts/go-test-coverage.sh
-        language: script
-        files: '\.go$'
-        pass_filenames: false
-        verbose: true
-        stages: [manual]  # Only runs when explicitly called
-      - id: go-vet
-        name: Go Vet
-        entry: bash -c 'cd backend && go vet ./...'
-        language: system
-        files: '\.go$'
-        pass_filenames: false
-      - id: golangci-lint-fast
-        name: golangci-lint (Fast Linters - BLOCKING)
-        entry: scripts/pre-commit-hooks/golangci-lint-fast.sh
-        language: script
-        files: '\.go$'
-        # Test files are now included to catch security issues (gosec critical checks)
-        pass_filenames: false
-        description: "Runs fast, essential linters (staticcheck, govet, errcheck, ineffassign, unused, gosec critical) - BLOCKS commits on failure"
-      - id: check-version-match
-        name: Check .version matches latest Git tag
-        entry: bash -c 'scripts/check-version-match-tag.sh'
-        language: system
-        files: '\.version$'
-        pass_filenames: false
-      - id: check-lfs-large-files
-        name: Prevent large files that are not tracked by LFS
-        entry: bash scripts/pre-commit-hooks/check-lfs-for-large-files.sh
-        language: system
-        pass_filenames: false
-        verbose: true
-        always_run: true
-      - id: block-codeql-db-commits
-        name: Prevent committing CodeQL DB artifacts
-        entry: bash scripts/pre-commit-hooks/block-codeql-db-commits.sh
-        language: system
-        pass_filenames: false
-        verbose: true
-        always_run: true
-      - id: block-data-backups-commit
-        name: Prevent committing data/backups files
-        entry: bash scripts/pre-commit-hooks/block-data-backups-commit.sh
-        language: system
-        pass_filenames: false
-        verbose: true
-        always_run: true
-
-      # === MANUAL/CI-ONLY HOOKS ===
-      # These are slow and should only run on-demand or in CI
-      # Run manually with: pre-commit run golangci-lint-full --all-files
-      - id: go-test-race
-        name: Go Test Race (Manual)
-        entry: bash -c 'cd backend && go test -race ./...'
-        language: system
-        files: '\.go$'
-        pass_filenames: false
-        stages: [manual]  # Only runs when explicitly called
-
-      - id: golangci-lint-full
-        name: golangci-lint (Full - Manual)
-        entry: scripts/pre-commit-hooks/golangci-lint-full.sh
-        language: script
-        files: '\.go$'
-        pass_filenames: false
-        stages: [manual]  # Only runs when explicitly called
-
-      - id: hadolint
-        name: Hadolint Dockerfile Check (Manual)
-        entry: bash -c 'docker run --rm -i hadolint/hadolint < Dockerfile'
-        language: system
-        files: 'Dockerfile'
-        pass_filenames: false
-        stages: [manual]  # Only runs when explicitly called
-      - id: frontend-type-check
-        name: Frontend TypeScript Check
-        entry: bash -c 'cd frontend && npx tsc --noEmit'
-        language: system
-        files: '^frontend/.*\.(ts|tsx)$'
-        pass_filenames: false
-      - id: frontend-lint
-        name: Frontend Lint (Fix)
-        entry: bash -c 'cd frontend && npm run lint -- --fix'
-        language: system
-        files: '^frontend/.*\.(ts|tsx|js|jsx)$'
-        pass_filenames: false
-
-      - id: frontend-test-coverage
-        name: Frontend Test Coverage (Manual)
-        entry: scripts/frontend-test-coverage.sh
-        language: script
-        files: '^frontend/.*\\.(ts|tsx|js|jsx)$'
-        pass_filenames: false
-        verbose: true
-        stages: [manual]
-
-      - id: security-scan
-        name: Security Vulnerability Scan (Manual)
-        entry: scripts/security-scan.sh
-        language: script
-        files: '(\.go$|go\.mod$|go\.sum$)'
-        pass_filenames: false
-        verbose: true
-        stages: [manual]  # Only runs when explicitly called
-
-      - id: codeql-go-scan
-        name: CodeQL Go Security Scan (Manual - Slow)
-        entry: scripts/pre-commit-hooks/codeql-go-scan.sh
-        language: script
-        files: '\.go$'
-        pass_filenames: false
-        verbose: true
-        stages: [manual]  # Performance: 30-60s, only run on-demand
-
-      - id: codeql-js-scan
-        name: CodeQL JavaScript/TypeScript Security Scan (Manual - Slow)
-        entry: scripts/pre-commit-hooks/codeql-js-scan.sh
-        language: script
-        files: '^frontend/.*\.(ts|tsx|js|jsx)$'
-        pass_filenames: false
-        verbose: true
-        stages: [manual]  # Performance: 30-60s, only run on-demand
-
-      - id: codeql-check-findings
-        name: Block HIGH/CRITICAL CodeQL Findings
-        entry: scripts/pre-commit-hooks/codeql-check-findings.sh
-        language: script
-        pass_filenames: false
-        verbose: true
-        stages: [manual]  # Only runs after CodeQL scans
-
-      - id: codeql-parity-check
-        name: CodeQL Suite/Trigger Parity Guard (Manual)
-        entry: scripts/ci/check-codeql-parity.sh
-        language: script
-        pass_filenames: false
-        verbose: true
-        stages: [manual]
-
-      - id: gorm-security-scan
-        name: GORM Security Scanner (Manual)
-        entry: scripts/pre-commit-hooks/gorm-security-check.sh
-        language: script
-        files: '\.go$'
-        pass_filenames: false
-        stages: [manual]  # Manual stage initially (soft launch)
-        verbose: true
-        description: "Detects GORM ID leaks and common GORM security mistakes"
-
-      - id: semgrep-scan
-        name: Semgrep Security Scan (Blocking - pre-push)
-        entry: scripts/pre-commit-hooks/semgrep-scan.sh
-        language: script
-        pass_filenames: false
-        verbose: true
-        stages: [pre-push]
-
-      - id: gitleaks-tuned-scan
-        name: Gitleaks Security Scan (Tuned, Manual)
-        entry: scripts/pre-commit-hooks/gitleaks-tuned-scan.sh
-        language: script
-        pass_filenames: false
-        verbose: true
-        stages: [manual]  # Manual stage initially (reversible rollout)
-
-  - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: v0.47.0
-    hooks:
-      - id: markdownlint
-        args: ["--fix"]
-        exclude: '^(node_modules|\.venv|test-results|codeql-db|codeql-agent-results)/'
-        stages: [manual]
--- a/.vscode/tasks.json
+++ b/.vscode/tasks.json
@@ -371,9 +371,9 @@
            }
        },
        {
-            "label": "Lint: Pre-commit (All Files)",
+            "label": "Lint: Lefthook Pre-commit (All Files)",
            "type": "shell",
-            "command": ".github/skills/scripts/skill-runner.sh qa-precommit-all",
+            "command": "lefthook run pre-commit",
            "group": "test",
            "problemMatcher": []
        },
@@ -466,9 +466,9 @@
            "problemMatcher": []
        },
        {
-            "label": "Security: Semgrep Scan (Manual Hook)",
+            "label": "Security: Semgrep Scan (Lefthook Pre-push)",
            "type": "shell",
-            "command": "pre-commit run --hook-stage manual semgrep-scan --all-files",
+            "command": "lefthook run pre-push",
            "group": "test",
            "problemMatcher": []
        },
@@ -480,9 +480,9 @@
            "problemMatcher": []
        },
        {
-            "label": "Security: Gitleaks Scan (Tuned Manual Hook)",
+            "label": "Security: Gitleaks Scan (Lefthook Pre-push)",
            "type": "shell",
-            "command": "pre-commit run --hook-stage manual gitleaks-tuned-scan --all-files",
+            "command": "lefthook run pre-push",
            "group": "test",
            "problemMatcher": []
        },
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -33,7 +33,19 @@ This project follows a Code of Conduct that all contributors are expected to adh

 ### Development Tools

-Install golangci-lint for pre-commit hooks (required for Go development):
+Install golangci-lint for lefthook pre-commit-phase hooks (required for Go development):
+
+Also install lefthook itself so the git hooks work:
+
+```bash
+# Option 1: Homebrew (macOS/Linux)
+brew install lefthook
+
+# Option 2: Go install
+go install github.com/evilmartians/lefthook@latest
+```
+
+

 ```bash
 # Option 1: Homebrew (macOS/Linux)
@@ -59,7 +71,7 @@ golangci-lint --version
 # Should output: golangci-lint has version 1.xx.x ...
 ```

-**Note:** Pre-commit hooks will **BLOCK commits** if golangci-lint finds issues. This is intentional - fix the issues before committing.
+**Note:** Lefthook pre-commit-phase hooks will **BLOCK commits** if golangci-lint finds issues. This is intentional - fix the issues before committing.

 ### CI/CD Go Version Management

@@ -84,7 +96,7 @@ When the project's Go version is updated (usually by Renovate):

 3. **Rebuild your development tools**
   ```bash
-   # This fixes pre-commit hook errors and IDE issues
+   # This fixes lefthook hook errors and IDE issues
   ./scripts/rebuild-go-tools.sh
   ```

@@ -104,7 +116,7 @@ Rebuilding tools with `./scripts/rebuild-go-tools.sh` fixes this by compiling th

 **What if I forget?**

-Don't worry! The pre-commit hook will detect the version mismatch and automatically rebuild tools for you. You'll see:
+Don't worry! The lefthook pre-commit hook will detect the version mismatch and automatically rebuild tools for you. You'll see:

 ```
 ⚠️  golangci-lint Go version mismatch:
--- a/docs/features.md
+++ b/docs/features.md
@@ -114,7 +114,7 @@ Automated static analysis that detects GORM security issues and common mistakes
 - **3 Operating Modes** — Report, check, and enforce modes for different workflows
 - **Fast Performance** — Scans entire codebase in 2.1 seconds
 - **Zero False Positives** — Smart GORM model detection prevents incorrect warnings
- **Pre-commit Integration** — Catches issues before they're committed
+- **Lefthook Integration** — Catches issues before they're committed
 - **VS Code Task** — Run security scans from the Command Palette

 **Detects:**
@@ -128,8 +128,8 @@ Automated static analysis that detects GORM security issues and common mistakes

 ```bash
 # Run via VS Code: Command Palette → "Lint: GORM Security Scan"
-# Or via pre-commit:
-pre-commit run --hook-stage manual gorm-security-scan --all-files
+# Or via lefthook:
+lefthook run pre-commit
 ```

 → [Learn More](implementation/gorm_security_scanner_complete.md)
--- a/docs/implementation/PHASE_3_COMPLETE.md
+++ b/docs/implementation/PHASE_3_COMPLETE.md
@@ -53,7 +53,7 @@ Phase 3 successfully implements all security scanning and QA validation skills.

 ### 3. qa-precommit-all ✅

-**Location**: `.github/skills/qa-precommit-all.SKILL.md`
+**Location**: `.github/skills/qa-lefthook-all.SKILL.md`
 **Execution Script**: `.github/skills/qa-precommit-all-scripts/run.sh`
 **Purpose**: Run all pre-commit hooks for comprehensive code quality validation

@@ -107,7 +107,7 @@ All skills validated with **0 errors**:
 ```bash
 ✓ security-scan-trivy.SKILL.md is valid
 ✓ security-scan-go-vuln.SKILL.md is valid
-✓ qa-precommit-all.SKILL.md is valid
+✓ qa-lefthook-all.SKILL.md is valid
 ```

 **Validation Checks Passed**:
--- a/docs/implementation/PHASE_4_COMPLETE.md
+++ b/docs/implementation/PHASE_4_COMPLETE.md
@@ -113,7 +113,7 @@ Validating 19 skill(s)...
 ✓ integration-test-crowdsec-decisions.SKILL.md
 ✓ integration-test-crowdsec-startup.SKILL.md
 ✓ integration-test-crowdsec.SKILL.md
-✓ qa-precommit-all.SKILL.md
+✓ qa-lefthook-all.SKILL.md
 ✓ security-scan-go-vuln.SKILL.md
 ✓ security-scan-trivy.SKILL.md
 ✓ test-backend-coverage.SKILL.md
--- a/docs/implementation/PHASE_5_COMPLETE.md
+++ b/docs/implementation/PHASE_5_COMPLETE.md
@@ -110,7 +110,7 @@ Phase 5 of the Agent Skills migration has been successfully completed. All docum

 - `test-backend-unit` and `test-frontend-unit` (created from inline tasks, no legacy script)
 - `security-scan-go-vuln` (created from inline command, no legacy script)
- `qa-precommit-all` (wraps pre-commit run, no legacy script)
+- `qa-lefthook-all` (wraps lefthook pre-commit run, no legacy script)
 - `docker-start-dev`, `docker-stop-dev`, `docker-prune` (wraps docker commands, no legacy scripts)

 **Result**: ✅ Complete - All legacy scripts now show deprecation warnings
--- a/scripts/pre-commit-hooks/codeql-check-findings.sh
+++ b/scripts/pre-commit-hooks/codeql-check-findings.sh
@@ -15,7 +15,7 @@ check_sarif() {

    if [ ! -f "$sarif_file" ]; then
        echo -e "${RED}❌ No SARIF file found: $sarif_file${NC}"
-        echo "Run CodeQL scan first: pre-commit run --hook-stage manual codeql-$lang-scan --all-files"
+        echo "Run CodeQL scan first: lefthook run pre-commit (which includes codeql-$lang-scan) or run `lefthook run codeql`"
        FAILED=1
        return 1
    fi
@@ -96,7 +96,7 @@ check_sarif() {
        fi
    else
                        echo -e "${RED}❌ jq is required for semantic CodeQL severity evaluation (${lang})${NC}"
-                        echo "Install jq and re-run: pre-commit run --hook-stage manual codeql-check-findings --all-files"
+                        echo "Install jq and re-run: lefthook run pre-commit"
                        FAILED=1
    fi
 }
@@ -106,7 +106,7 @@ echo ""

                if ! command -v jq &> /dev/null; then
                    echo -e "${RED}❌ jq is required for CodeQL finding checks${NC}"
-                    echo "Install jq and re-run: pre-commit run --hook-stage manual codeql-check-findings --all-files"
+                    echo "Install jq and re-run: lefthook run pre-commit"
                    exit 1
                fi

--- a/scripts/pre-commit-hooks/codeql-go-scan.sh
+++ b/scripts/pre-commit-hooks/codeql-go-scan.sh
@@ -68,4 +68,4 @@ echo -e "${GREEN}✅ Extraction parity OK${NC} (compiled baseline=$BASELINE_COUN
 echo -e "${GREEN}✅ CodeQL Go scan complete${NC}"
 echo "Results saved to: codeql-results-go.sarif"
 echo ""
-echo "Run 'pre-commit run codeql-check-findings' to validate findings"
+echo "Run 'lefthook run pre-commit' (or `lefthook run pre-commit` which includes codeql-check-findings) to validate findings"
--- a/scripts/pre-commit-hooks/codeql-js-scan.sh
+++ b/scripts/pre-commit-hooks/codeql-js-scan.sh
@@ -38,4 +38,4 @@ codeql database analyze codeql-db-js \
 echo -e "${GREEN}✅ CodeQL JavaScript/TypeScript scan complete${NC}"
 echo "Results saved to: codeql-results-js.sarif"
 echo ""
-echo "Run 'pre-commit run codeql-check-findings' to validate findings"
+echo "Run 'lefthook run pre-commit' (or `lefthook run pre-commit` which includes codeql-check-findings) to validate findings"