forgecraft-mcp 1.4.0 → 1.7.0

package/templates/universal/hooks.yaml

@@ -1,723 +1,879 @@
-tag: UNIVERSAL
-section: hooks
-hooks:
-  - name: commit-msg
-    trigger: commit-msg
-    description: "Enforce conventional commit format: <type>(<scope>): <description>"
-    filename: commit-msg.sh
-    script: |
-      #!/usr/bin/env bash
-      # commit-msg: enforce conventional commit format
-      # ForgeCraft — generated hook
-
-      COMMIT_MSG_FILE="$1"
-      COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
-
-      # Skip merge commits and fixup commits
-      if echo "$COMMIT_MSG" | grep -qE "^(Merge|Revert|fixup!|squash!)"; then
-        exit 0
-      fi
-
-      # Skip empty messages and comments-only
-      STRIPPED=$(echo "$COMMIT_MSG" | sed '/^#/d' | sed '/^$/d')
-      if [ -z "$STRIPPED" ]; then
-        exit 0
-      fi
-
-      PATTERN="^(feat|fix|refactor|docs|test|chore|perf|ci|build|revert)(\([a-z0-9/_-]+\))?(!)?: .{1,72}"
-
-      if ! echo "$COMMIT_MSG" | grep -qE "$PATTERN"; then
-        echo ""
-        echo "  ✗ Commit message does not follow conventional commit format."
-        echo ""
-        echo "  Required format: <type>(<scope>): <description>"
-        echo "  Types: feat | fix | refactor | docs | test | chore | perf | ci | build | revert"
-        echo "  Examples:"
-        echo "    feat(auth): add JWT refresh token support"
-        echo "    fix(api): handle null response from payment gateway"
-        echo "    docs: update README with setup instructions"
-        echo ""
-        echo "  Your message: $COMMIT_MSG"
-        echo ""
-        exit 1
-      fi
-
-      exit 0
-
-  - name: branch-protection
-    trigger: pre-commit
-    description: "Block direct commits to main/master branches"
-    filename: pre-commit-branch-check.sh
-    script: |
-      #!/bin/bash
-      BRANCH=$(git rev-parse --abbrev-ref HEAD)
-      if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
-        echo "❌ Direct commits to $BRANCH are blocked. Create a feature branch."
-        exit 1
-      fi
-
-  - name: dangerous-commands
-    trigger: pre-exec
-    description: "Block destructive commands (rm -rf /, DROP DATABASE, force push)"
-    filename: pre-exec-safety.sh
-    script: |
-      #!/bin/bash
-      DANGEROUS_PATTERNS=(
-        "rm -rf /"
-        "DROP DATABASE"
-        "DROP TABLE"
-        "TRUNCATE"
-        "force push"
-        "git push.*--force"
-        "kubectl delete namespace"
-      )
-      for pattern in "${DANGEROUS_PATTERNS[@]}"; do
-        if echo "$1" | grep -iqE "$pattern"; then
-          echo "❌ Blocked dangerous command matching: $pattern"
-          exit 1
-        fi
-      done
-
-  - name: auto-format
-    trigger: pre-commit
-    description: "Run language-appropriate formatter on staged files"
-    filename: pre-commit-format.sh
-    script: |
-      #!/bin/bash
-      STAGED=$(git diff --cached --name-only --diff-filter=ACM)
-      # Python
-      echo "$STAGED" | grep '\.py$' | xargs -r black --quiet 2>/dev/null
-      echo "$STAGED" | grep '\.py$' | xargs -r isort --quiet 2>/dev/null
-      # TypeScript/JavaScript
-      echo "$STAGED" | grep '\.\(ts\|tsx\|js\|jsx\)$' | xargs -r npx prettier --write 2>/dev/null
-      # Rust
-      if echo "$STAGED" | grep -q '\.rs$' && [ -f "Cargo.toml" ]; then
-        cargo fmt 2>/dev/null
-      fi
-      # Re-stage formatted files
-      echo "$STAGED" | xargs -r git add
-
-  - name: secrets-scanner
-    trigger: pre-commit
-    description: "Scan for accidentally committed secrets (AWS keys, API keys, passwords)"
-    filename: pre-commit-secrets.sh
-    script: |
-      #!/bin/bash
-      _fc_write_violation() {
-        local hook_name="$1" severity="${2:-error}" message="$3"
-        local repo_root
-        repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || return 0
-        local dir="$repo_root/.forgecraft"
-        mkdir -p "$dir" 2>/dev/null || return 0
-        local ts
-        ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || printf "unknown")"
-        local esc_msg
-        esc_msg="$(printf '%s' "$message" | sed 's/\\/\\\\/g; s/"/\\"/g')"
-        printf '{"hook":"%s","severity":"%s","message":"%s","timestamp":"%s"}\n' \
-          "$hook_name" "$severity" "$esc_msg" "$ts" \
-          >> "$dir/gate-violations.jsonl" 2>/dev/null || true
-      }
-      PATTERNS=(
-        'AKIA[0-9A-Z]{16}'
-        'password\s*=\s*["\x27][^"\x27]+'
-        'BEGIN RSA PRIVATE KEY'
-        'sk-[a-zA-Z0-9]{48}'
-        'ghp_[a-zA-Z0-9]{36}'
-      )
-      STAGED=$(git diff --cached --name-only)
-      for file in $STAGED; do
-        for pattern in "${PATTERNS[@]}"; do
-          if grep -qE "$pattern" "$file" 2>/dev/null; then
-            echo "❌ Potential secret found in $file matching pattern"
-            _fc_write_violation "pre-commit-secrets" "error" "Potential secrets detected in staged files — review output above"
-            exit 1
-          fi
-        done
-      done
-
-  - name: compile-check
-    trigger: pre-commit
-    description: "Detect project type and run appropriate compile/build check"
-    filename: pre-commit-compile.sh
-    script: |
-      #!/bin/bash
-      _fc_write_violation() {
-        local hook_name="$1" severity="${2:-error}" message="$3"
-        local repo_root
-        repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || return 0
-        local dir="$repo_root/.forgecraft"
-        mkdir -p "$dir" 2>/dev/null || return 0
-        local ts
-        ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || printf "unknown")"
-        local esc_msg
-        esc_msg="$(printf '%s' "$message" | sed 's/\\/\\\\/g; s/"/\\"/g')"
-        printf '{"hook":"%s","severity":"%s","message":"%s","timestamp":"%s"}\n' \
-          "$hook_name" "$severity" "$esc_msg" "$ts" \
-          >> "$dir/gate-violations.jsonl" 2>/dev/null || true
-      }
-      echo "🔨 Running build check..."
-      if [ -f "pyproject.toml" ] || [ -f "setup.py" ] || [ -f "requirements.txt" ]; then
-        STAGED_PY=$(git diff --cached --name-only --diff-filter=ACM | grep '\.py$')
-        if [ -n "$STAGED_PY" ]; then
-          for file in $STAGED_PY; do
-            python -m py_compile "$file" 2>&1
-            if [ $? -ne 0 ]; then
-              echo "❌ Syntax error in $file"
-              _fc_write_violation "pre-commit-compile" "error" "TypeScript compilation failed — run tsc --noEmit to see errors"
-              exit 1
-            fi
-          done
-          echo "  ✅ Python syntax OK"
-        fi
-      fi
-      if [ -f "tsconfig.json" ]; then
-        npx tsc --noEmit 2>&1
-        if [ $? -ne 0 ]; then
-          echo "❌ TypeScript compilation failed."
-          _fc_write_violation "pre-commit-compile" "error" "TypeScript compilation failed — run tsc --noEmit to see errors"
-          exit 1
-        fi
-        echo "  ✅ TypeScript compilation OK"
-      fi
-      if [ -f "Cargo.toml" ]; then
-        STAGED_RS=$(git diff --cached --name-only --diff-filter=ACM | grep '\.rs$')
-        if [ -n "$STAGED_RS" ]; then
-          cargo check --quiet 2>&1
-          if [ $? -ne 0 ]; then
-            echo "❌ Rust cargo check failed."
-            _fc_write_violation "pre-commit-compile" "error" "Rust cargo check failed — run cargo check to see errors"
-            exit 1
-          fi
-          echo "  ✅ Rust cargo check OK"
-        fi
-      fi
-      echo "🔨 Build check passed"
-
-  - name: cargo-clippy
-    trigger: pre-commit
-    description: "Run cargo clippy on Rust projects — catches bugs, style issues, and common mistakes beyond cargo check"
-    filename: pre-commit-clippy.sh
-    script: |
-      #!/bin/bash
-      _fc_write_violation() {
-        local hook_name="$1" severity="${2:-error}" message="$3"
-        local repo_root
-        repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || return 0
-        local dir="$repo_root/.forgecraft"
-        mkdir -p "$dir" 2>/dev/null || return 0
-        local ts
-        ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || printf "unknown")"
-        local esc_msg
-        esc_msg="$(printf '%s' "$message" | sed 's/\\/\\\\/g; s/"/\\"/g')"
-        printf '{"hook":"%s","severity":"%s","message":"%s","timestamp":"%s"}\n' \
-          "$hook_name" "$severity" "$esc_msg" "$ts" \
-          >> "$dir/gate-violations.jsonl" 2>/dev/null || true
-      }
-      if [ ! -f "Cargo.toml" ]; then
-        exit 0
-      fi
-      STAGED_RS=$(git diff --cached --name-only --diff-filter=ACM | grep '\.rs$')
-      if [ -z "$STAGED_RS" ]; then
-        exit 0
-      fi
-      echo "🦀 Running cargo clippy..."
-      cargo clippy --all-targets --all-features 2>&1
-      if [ $? -ne 0 ]; then
-        echo "❌ cargo clippy failed — fix lint errors before committing."
-        echo "   Run: cargo clippy --all-targets --all-features"
-        _fc_write_violation "pre-commit-clippy" "error" "Cargo clippy violations found — run cargo clippy to see details"
-        exit 1
-      fi
-      echo "  ✅ cargo clippy passed"
-
-  - name: tdd-phase-gate
-    trigger: pre-commit
-    description: "RED gate: test-only commits must have failing tests; warn on implementation without tests"
-    filename: pre-commit-tdd-check.sh
-    script: |
-      #!/bin/bash
-      STAGED=$(git diff --cached --name-only --diff-filter=ACM)
-      if [ -z "$STAGED" ]; then exit 0; fi
-      SRC_PATTERNS='^(src|lib|app|server|client|pkg|internal|cmd)/'
-      TEST_PATTERNS='^(tests?|spec|__tests__)/'
-      TEST_FILE_PATTERNS='\.(test|spec)\.(ts|tsx|js|jsx|mjs|py|go|rb|java|kt)$'
-      SRC_FILES=()
-      TEST_FILES=()
-      while IFS= read -r file; do
-        if echo "$file" | grep -qE "$SRC_PATTERNS"; then
-          SRC_FILES+=("$file")
-        elif echo "$file" | grep -qE "$TEST_PATTERNS"; then
-          TEST_FILES+=("$file")
-        elif echo "$file" | grep -qE "$TEST_FILE_PATTERNS"; then
-          TEST_FILES+=("$file")
-        fi
-      done <<< "$STAGED"
-      SRC_COUNT=${#SRC_FILES[@]}
-      TEST_COUNT=${#TEST_FILES[@]}
-      # RED gate: test-only commit must have at least one failing test
-      if [ "$TEST_COUNT" -gt 0 ] && [ "$SRC_COUNT" -eq 0 ]; then
-        echo "🔴 TDD gate: test-only commit — running staged tests..."
-        RUN_CMD=""
-        if [ -f "package.json" ]; then
-          if grep -q '"vitest"' package.json 2>/dev/null; then
-            RUN_CMD="npx vitest run"
-          elif grep -q '"jest"' package.json 2>/dev/null; then
-            RUN_CMD="npx jest --passWithNoTests"
-          fi
-        elif [ -f "Cargo.toml" ]; then
-          RUN_CMD="cargo test"
-        elif [ -f "pytest.ini" ] || [ -f "pyproject.toml" ] || [ -f "setup.py" ]; then
-          RUN_CMD="python -m pytest"
-        fi
-        if [ -n "$RUN_CMD" ]; then
-          $RUN_CMD "${TEST_FILES[@]}" > /tmp/tdd-check-output.txt 2>&1
-          if [ $? -eq 0 ]; then
-            echo "❌ TDD RED gate violation: all staged tests PASS"
-            echo "   A test-only commit must contain at least one failing test."
-            echo "   Either tests were written after implementation, or assertions are vacuous."
-            cat /tmp/tdd-check-output.txt | head -30
-            exit 1
-          fi
-          echo "  ✅ RED gate satisfied — staged tests fail as expected"
-        else
-          echo "  ⚠️  Cannot detect test runner — skipping RED gate check"
-        fi
-      fi
-      # Source gate: warn on implementation without tests
-      if [ "$SRC_COUNT" -gt 0 ] && [ "$TEST_COUNT" -eq 0 ]; then
-        echo "⚠️  TDD warning: implementation committed without test changes"
-        echo "   Verify a preceding test(scope): [RED] commit exists in this branch."
-      fi
-      exit 0
-
-  - name: test-coverage
-    trigger: pre-commit
-    description: "Run tests for test-only commits; skip for docs/config-only commits; defer to coverage-gate when src/ staged"
-    filename: pre-commit-test.sh
-    script: |
-      #!/bin/bash
-      COVERAGE_MIN={{coverage_minimum | default: 80}}
-
-      # Collect staged files once.
-      STAGED=$(git diff --cached --name-only --diff-filter=ACM)
-
-      # Determine what kinds of files are staged.
-      SRC_STAGED=0
-      CODE_STAGED=0
-      while IFS= read -r file; do
-        if echo "$file" | grep -qE '^src/'; then
-          SRC_STAGED=1
-          CODE_STAGED=1
-        elif echo "$file" | grep -qE '^tests?/'; then
-          CODE_STAGED=1
-        fi
-      done <<< "$STAGED"
-
-      # If src/ is staged the coverage-gate hook runs the full test + coverage pass.
-      # Skip the bare run here to avoid running the full suite twice.
-      if [ "$SRC_STAGED" -eq 1 ]; then
-        echo "🧪 src/ files staged — tests will run via coverage gate, skipping bare run."
-        exit 0
-      fi
-
-      # If no code files at all are staged (docs-only, config-only, etc.) skip the run.
-      if [ "$CODE_STAGED" -eq 0 ]; then
-        echo "🧪 No code files staged — skipping test run."
-        exit 0
-      fi
-
-      echo "🧪 Running tests..."
-      if [ -f "package.json" ]; then
-        if grep -q '"vitest"' package.json 2>/dev/null; then
-          npx vitest run --reporter=verbose 2>&1
-          if [ $? -ne 0 ]; then
-            echo "❌ Tests failed."
-            exit 1
-          fi
-          echo "  ✅ Tests passed"
-        elif grep -q '"jest"' package.json 2>/dev/null; then
-          npx jest --passWithNoTests --coverage \
-            --coverageThreshold="{\"global\":{\"lines\":$COVERAGE_MIN}}" \
-            --silent 2>&1
-          if [ $? -ne 0 ]; then
-            echo "❌ Jest tests failed or coverage below ${COVERAGE_MIN}%."
-            exit 1
-          fi
-          echo "  ✅ Jest tests passed"
-        fi
-      fi
-      if [ -f "pyproject.toml" ] || [ -f "setup.py" ]; then
-        if command -v pytest &> /dev/null; then
-          pytest --tb=short --quiet --cov=src --cov-fail-under=$COVERAGE_MIN 2>&1
-          if [ $? -ne 0 ]; then
-            echo "❌ Tests failed or coverage below ${COVERAGE_MIN}%."
-            exit 1
-          fi
-          echo "  ✅ Python tests passed"
-        fi
-      fi
-      if [ -f "Cargo.toml" ]; then
-        cargo test --quiet 2>&1
-        if [ $? -ne 0 ]; then
-          echo "❌ Rust tests failed."
-          exit 1
-        fi
-        echo "  ✅ Rust tests passed"
-      fi
-      echo "🧪 All tests passed"
-
-  - name: coverage-gate
-    trigger: pre-commit
-    description: "Enforce minimum coverage thresholds when src/ files are staged"
-    filename: pre-commit-coverage.sh
-    script: |
-      #!/bin/bash
-      _fc_write_violation() {
-        local hook_name="$1" severity="${2:-error}" message="$3"
-        local repo_root
-        repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || return 0
-        local dir="$repo_root/.forgecraft"
-        mkdir -p "$dir" 2>/dev/null || return 0
-        local ts
-        ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || printf "unknown")"
-        local esc_msg
-        esc_msg="$(printf '%s' "$message" | sed 's/\\/\\\\/g; s/"/\\"/g')"
-        printf '{"hook":"%s","severity":"%s","message":"%s","timestamp":"%s"}\n' \
-          "$hook_name" "$severity" "$esc_msg" "$ts" \
-          >> "$dir/gate-violations.jsonl" 2>/dev/null || true
-      }
-      # ──────────────────────────────────────────────────────────────────────
-      # Pre-Commit Hook: Coverage Gate
-      #
-      # Enforces minimum coverage thresholds before a commit lands.
-      # Thresholds are read from vitest.config.ts (via --coverage).
-      # Only runs when files under src/ are staged — skips for
-      # docs-only, config-only, or test-only commits.
-      #
-      # Current thresholds (vitest.config.ts):
-      #   Lines / Statements / Functions: {{coverage_minimum | default: 80}}%
-      #   Branches: 70%
-      #
-      # Trigger: git pre-commit (via scripts/setup-hooks.sh)
-      # Exit: 1 blocks commit, 0 allows
-      # ──────────────────────────────────────────────────────────────────────
-
-      STAGED=$(git diff --cached --name-only --diff-filter=ACM)
-
-      if [ -z "$STAGED" ]; then
-        exit 0
-      fi
-
-      # ── Check if any src/ file is staged ─────────────────────────────────
-      SRC_STAGED=0
-      while IFS= read -r file; do
-        if echo "$file" | grep -qE '^src/'; then
-          SRC_STAGED=1
-          break
-        fi
-      done <<< "$STAGED"
-
-      if [ "$SRC_STAGED" -eq 0 ]; then
-        echo "📊 Coverage gate: no src/ files staged, skipping."
-        exit 0
-      fi
-
-      # ── Run coverage ───────────────────────────────────────────────────────
-      echo "📊 Running coverage gate (src/ files staged)..."
-
-      if [ ! -f "package.json" ] && [ ! -f "pyproject.toml" ] && [ ! -f "setup.py" ]; then
-        if [ -f "Cargo.toml" ]; then
-          # Rust: run tests; use cargo-tarpaulin for coverage if available
-          if command -v cargo-tarpaulin &> /dev/null; then
-            cargo tarpaulin --out Stdout --fail-under {{coverage_minimum | default: 80}} 2>&1
-            if [ $? -ne 0 ]; then
-              echo "❌ Coverage gate failed — below {{coverage_minimum | default: 80}}%."
-              echo "   Run: cargo tarpaulin --out Html"
-              _fc_write_violation "pre-commit-coverage" "error" "Coverage gate failed — run npm test --coverage to see report"
-              exit 1
-            fi
-            echo "  ✅ Rust coverage gate passed"
-          else
-            cargo test --quiet 2>&1
-            if [ $? -ne 0 ]; then
-              echo "❌ Rust tests failed."
-              _fc_write_violation "pre-commit-coverage" "error" "Coverage gate failed — run npm test --coverage to see report"
-              exit 1
-            fi
-            echo "  ✅ Rust tests passed (install cargo-tarpaulin for coverage enforcement)"
-          fi
-        else
-          echo "  ⚠️  No supported build system found — skipping coverage check."
-        fi
-        exit 0
-      fi
-
-      if grep -q '"vitest"' package.json 2>/dev/null; then
-        OUTPUT=$(npx vitest run --coverage --reporter=verbose 2>&1)
-        EXIT_CODE=$?
-
-        if [ $EXIT_CODE -ne 0 ]; then
-          echo "$OUTPUT" | grep -E "ERROR|Coverage|does not meet|%|FAIL|passed|failed" | head -40
-          echo ""
-          echo "❌ Coverage gate failed — thresholds not met."
-          echo "   Run 'npx vitest run --coverage' locally to see the full report."
-          echo "   Add tests until coverage meets the configured minimums."
-          _fc_write_violation "pre-commit-coverage" "error" "Coverage gate failed — run npm test --coverage to see report"
-          exit 1
-        fi
-        echo "  ✅ Coverage gate passed"
-        exit 0
-      fi
-
-      if grep -q '"jest"' package.json 2>/dev/null; then
-        COVERAGE_MIN={{coverage_minimum | default: 80}}
-        npx jest --passWithNoTests --coverage \
-          --coverageThreshold="{\"global\":{\"lines\":$COVERAGE_MIN,\"statements\":$COVERAGE_MIN,\"functions\":$COVERAGE_MIN,\"branches\":70}}" \
-          --silent 2>&1
-        if [ $? -ne 0 ]; then
-          echo "❌ Coverage gate failed — thresholds not met."
-          _fc_write_violation "pre-commit-coverage" "error" "Coverage gate failed — run npm test --coverage to see report"
-          exit 1
-        fi
-        echo "  ✅ Coverage gate passed"
-        exit 0
-      fi
-
-      if [ -f "pyproject.toml" ]|| [ -f "setup.py" ]; then
-        if command -v pytest &> /dev/null; then
-          pytest --tb=no --quiet --cov=src --cov-fail-under={{coverage_minimum | default: 80}} 2>&1
-          if [ $? -ne 0 ]; then
-            echo "❌ Coverage gate failed — below {{coverage_minimum | default: 80}}%."
-            _fc_write_violation "pre-commit-coverage" "error" "Coverage gate failed — run npm test --coverage to see report"
-            exit 1
-          fi
-          echo "  ✅ Coverage gate passed"
-        fi
-      fi
-
-      exit 0
-
-  - name: anti-pattern-detector
-    trigger: pre-commit
-    description: "Scan source files for production code anti-patterns. Respects .forgecraft/exceptions.json for recorded false positives."
-    filename: pre-commit-prod-quality.sh
-    checks:
-      - Hardcoded URLs/hosts (localhost, 127.0.0.1)
-      - Mock/stub data in production code
-      - Direct DB calls in route/controller layer (layer violation)
-      - Bare Error throws (custom hierarchy recommended)
-      - .env vs .env.example drift (warns on missing variables)
-    script: |
-      #!/bin/bash
-      _fc_write_violation() {
-        local hook_name="$1" severity="${2:-error}" message="$3"
-        local repo_root
-        repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || return 0
-        local dir="$repo_root/.forgecraft"
-        mkdir -p "$dir" 2>/dev/null || return 0
-        local ts
-        ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || printf "unknown")"
-        local esc_msg
-        esc_msg="$(printf '%s' "$message" | sed 's/\\/\\\\/g; s/"/\\"/g')"
-        printf '{"hook":"%s","severity":"%s","message":"%s","timestamp":"%s"}\n' \
-          "$hook_name" "$severity" "$esc_msg" "$ts" \
-          >> "$dir/gate-violations.jsonl" 2>/dev/null || true
-      }
-      STAGED=$(git diff --cached --name-only --diff-filter=ACM)
-      SOURCE_FILES=$(echo "$STAGED" | grep -E '\.(py|ts|tsx|js|jsx|rs)$' | grep -vE '(test_|\.test\.|\.spec\.|__tests__|tests/|fixtures/|mock|conftest|_test\.rs)')
-      if [ -z "$SOURCE_FILES" ]; then exit 0; fi
-      VIOLATIONS=0
-      WARNINGS=0
-      # Check if a file is covered by a hook exception in .forgecraft/exceptions.json
-      # Usage: is_excepted "layer-boundary" "src/migrations/001.ts"
-      # Add entries to .forgecraft/exceptions.json to record known false positives.
-      is_excepted() {
-        local hook_name="$1"
-        local file_path="$2"
-        if [ ! -f ".forgecraft/exceptions.json" ]; then return 1; fi
-        node -e "
-          const fs = require('fs');
-          const data = JSON.parse(fs.readFileSync('.forgecraft/exceptions.json', 'utf-8'));
-          const exc = (data.exceptions || []).find(e => {
-            if (e.hook !== '$hook_name') return false;
-            const pat = e.pattern.replace(/\\/g, '/').replace(/\./g, '\\\\.').replace(/\*\*/g, '<<<D>>>').replace(/\*/g, '[^/]*').replace(/<<<D>>>/g, '.*');
-            return new RegExp('^' + pat + '$').test('$file_path'.replace(/\\\\/g, '/'));
-          });
-          if (exc) { console.log('EXCEPTED: ' + exc.reason); process.exit(0); }
-          process.exit(1);
-        " 2>/dev/null
-      }
-      echo "🔍 Scanning for production code anti-patterns..."
-      for file in $SOURCE_FILES; do
-        if echo "$file" | grep -vqE '(config|settings|\.env)'; then
-          if grep -nE '(localhost|127\.0\.0\.1|0\.0\.0\.0)' "$file" | grep -vE '(#|//|""")' > /tmp/violations 2>/dev/null; then
-            if [ -s /tmp/violations ]; then
-              echo "  ❌ $file — hardcoded URL/host"
-              VIOLATIONS=$((VIOLATIONS + 1))
-            fi
-          fi
-        fi
-        if ! is_excepted "anti-pattern/mock-data" "$file"; then
-          if grep -nEi '\b(mock_data|fake_data|dummy_data|stub_response)' "$file" > /tmp/violations 2>/dev/null; then
-            if [ -s /tmp/violations ]; then
-              echo "  ❌ $file — mock/stub data in production code"
-              VIOLATIONS=$((VIOLATIONS + 1))
-            fi
-          fi
-        fi
-        # Layer boundary: no direct DB/ORM imports from route handlers / controllers
-        if echo "$file" | grep -qE '(routes|controllers|handlers|endpoints)'; then
-          if ! is_excepted "layer-boundary" "$file"; then
-            if grep -nE '\b(prisma\.|knex\(|mongoose\.|sequelize\.|db\.query|pool\.query)' "$file" > /tmp/violations 2>/dev/null; then
-              if [ -s /tmp/violations ]; then
-                echo "  ❌ $file — direct DB call in route/controller (layer violation)"
-                VIOLATIONS=$((VIOLATIONS + 1))
-              fi
-            fi
-          fi
-        fi
-        # Bare Error throws in business logic (not test files)
-        if ! is_excepted "error-hierarchy" "$file"; then
-          if grep -nE 'throw new Error\(' "$file" > /tmp/violations 2>/dev/null; then
-            if [ -s /tmp/violations ]; then
-              echo "  ⚠️  $file — bare 'throw new Error()' found — use custom error hierarchy"
-              WARNINGS=$((WARNINGS + 1))
-            fi
-          fi
-        fi
-        LINE_COUNT=$(wc -l < "$file")
-        if [ "$LINE_COUNT" -gt {{max_file_length | default: 300}} ]; then
-          echo "  ⚠️  $file — $LINE_COUNT lines (max {{max_file_length | default: 300}})"
-          WARNINGS=$((WARNINGS + 1))
-        fi
-        # Rust-specific anti-patterns
-        if echo "$file" | grep -q '\.rs$'; then
-          if ! is_excepted "rust/unwrap" "$file"; then
-            if grep -nE '\.unwrap\(\)' "$file" > /tmp/violations 2>/dev/null; then
-              if [ -s /tmp/violations ]; then
-                echo "  ⚠️  $file — .unwrap() in production code — use ? or explicit error handling"
-                WARNINGS=$((WARNINGS + 1))
-              fi
-            fi
-          fi
-          if grep -nE '\btodo!\(|\bunimplemented!\(' "$file" > /tmp/violations 2>/dev/null; then
-            if [ -s /tmp/violations ]; then
-              echo "  ❌ $file — todo!/unimplemented! in production code"
-              VIOLATIONS=$((VIOLATIONS + 1))
-            fi
-          fi
-          if grep -nE '^[[:space:]]*#\[allow\(dead_code\)\]' "$file" > /tmp/violations 2>/dev/null; then
-            if [ -s /tmp/violations ]; then
-              echo "  ⚠️  $file — #[allow(dead_code)] suppression — delete orphaned code instead"
-              WARNINGS=$((WARNINGS + 1))
-            fi
-          fi
-          if grep -nE '^[[:space:]]*unsafe[[:space:]]*\{' "$file" > /tmp/violations 2>/dev/null; then
-            if [ -s /tmp/violations ]; then
-              echo "  ⚠️  $file — unsafe block present — requires explicit justification comment"
-              WARNINGS=$((WARNINGS + 1))
-            fi
-          fi
-        fi
-      rm -f /tmp/violations
-      if [ $VIOLATIONS -gt 0 ]; then
-        echo "❌ $VIOLATIONS violation(s) found — commit blocked."
-        _fc_write_violation "pre-commit-anti-patterns" "error" "Anti-patterns detected in staged files — see output above"
-        exit 1
-      fi
-      if [ $WARNINGS -gt 0 ]; then
-        echo "⚠️  $WARNINGS warning(s) found — review recommended."
-      fi
-      echo "🔍 Production quality scan passed"
-
-  - name: function-length
-    trigger: pre-commit
-    description: "Warn when staged functions exceed the configured maximum line count"
-    filename: pre-commit-function-length.sh
-    script: |
-      #!/bin/bash
-      MAX_LENGTH={{max_function_length | default: 50}}
-      STAGED=$(git diff --cached --name-only --diff-filter=ACM)
-      SOURCE_FILES=$(echo "$STAGED" | grep -E '\.(ts|tsx|js|jsx|rs)$' | grep -vE '(\.test\.|\.spec\.|__tests__|tests/|_test\.rs)')
-      if [ -z "$SOURCE_FILES" ]; then exit 0; fi
-      WARNINGS=0
-      for file in $SOURCE_FILES; do
-        # Heuristic: find function/method declarations and count lines to next declaration
-        if echo "$file" | grep -q '\.rs$'; then
-          awk -v max="$MAX_LENGTH" -v fname="$file" '
-            /^[[:space:]]*(pub )?(async )?fn [a-zA-Z_]/ {
-              if (start > 0 && NR - start > max) {
-                printf "  ⚠️  %s:%d — fn starting here is %d lines (max %d)\n", fname, start, NR - start, max
-              }
-              start = NR
-            }
-            END {
-              if (start > 0 && NR - start > max) {
-                printf "  ⚠️  %s:%d — fn starting here is %d lines (max %d)\n", fname, start, NR - start, max
-              }
-            }
-          ' "$file"
-        else
-          awk -v max="$MAX_LENGTH" -v fname="$file" '
-            /^[[:space:]]*(export )?(async )?(function |const [a-zA-Z]+ = (async )?\(|[a-zA-Z]+\(.*\) \{|[a-zA-Z]+\(.*\): )/ {
-              if (start > 0 && NR - start > max) {
-                printf "  ⚠️  %s:%d — function starting here is %d lines (max %d)\n", fname, start, NR - start, max
-                warnings++
-              }
-              start = NR
-            }
-            END {
-              if (start > 0 && NR - start > max) {
-                printf "  ⚠️  %s:%d — function starting here is %d lines (max %d)\n", fname, start, NR - start, max
-                warnings++
-              }
-            }
-          ' "$file"
-        fi
-        WARNINGS=$((WARNINGS + $?))
-      done
-      # Warning only — does not block commit since bash heuristics aren't perfect
-      exit 0
-
-  - name: import-cycle-detector
-    trigger: pre-commit
-    description: "Detect circular import dependencies in TypeScript and Python projects"
-    filename: pre-commit-import-cycles.sh
-    script: |
-      #!/bin/bash
-      echo "🔄 Checking for circular imports..."
-      if [ -f "tsconfig.json" ]; then
-        if command -v npx &> /dev/null; then
-          RESULT=$(npx --yes madge --circular --extensions ts src/ 2>&1)
-          if echo "$RESULT" | grep -q "Found.*circular"; then
-            echo "❌ Circular imports detected in TypeScript:"
-            echo "$RESULT"
-            exit 1
-          fi
-          echo "  ✅ No circular imports (TypeScript)"
-        fi
-      fi
-      if [ -f "pyproject.toml" ] || [ -f "setup.py" ]; then
-        if command -v lint-imports &> /dev/null; then
-          lint-imports 2>&1
-          if [ $? -ne 0 ]; then
-            echo "❌ Circular imports detected in Python"
-            exit 1
-          fi
-          echo "  ✅ No circular imports (Python)"
-        fi
-      fi
-      echo "🔄 Import cycle check passed"
-
-  - name: code-review
-    trigger: pre-commit
-    description: "AI assistant reviews diff against project standards"
-    filename: pre-commit-review.sh
-    script: |
-      #!/bin/bash
-      DIFF=$(git diff --cached)
-      if [ -z "$DIFF" ]; then exit 0; fi
-      echo "📝 Staged changes ready for review"
-      # Full auto-review requires claude CLI integration
-      # This hook validates the diff is non-empty and staged
-      exit 0
+tag: UNIVERSAL
+section: hooks
+hooks:
+  - name: commit-msg
+    trigger: commit-msg
+    description: "Enforce conventional commit format: <type>(<scope>): <description>"
+    filename: commit-msg.sh
+    script: |
+      #!/usr/bin/env bash
+      # commit-msg: enforce conventional commit format
+      # ForgeCraft — generated hook
+
+      COMMIT_MSG_FILE="$1"
+      COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
+
+      # Skip merge commits and fixup commits
+      if echo "$COMMIT_MSG" | grep -qE "^(Merge|Revert|fixup!|squash!)"; then
+        exit 0
+      fi
+
+      # Skip empty messages and comments-only
+      STRIPPED=$(echo "$COMMIT_MSG" | sed '/^#/d' | sed '/^$/d')
+      if [ -z "$STRIPPED" ]; then
+        exit 0
+      fi
+
+      PATTERN="^(feat|fix|refactor|docs|test|chore|perf|ci|build|revert)(\([a-z0-9/_-]+\))?(!)?: .{1,72}"
+
+      if ! echo "$COMMIT_MSG" | grep -qE "$PATTERN"; then
+        echo ""
+        echo "  ✗ Commit message does not follow conventional commit format."
+        echo ""
+        echo "  Required format: <type>(<scope>): <description>"
+        echo "  Types: feat | fix | refactor | docs | test | chore | perf | ci | build | revert"
+        echo "  Examples:"
+        echo "    feat(auth): add JWT refresh token support"
+        echo "    fix(api): handle null response from payment gateway"
+        echo "    docs: update README with setup instructions"
+        echo ""
+        echo "  Your message: $COMMIT_MSG"
+        echo ""
+        exit 1
+      fi
+
+      # ── TDD [RED]/[GREEN] phase enforcement ────────────────────────────────
+      SUBJECT=$(echo "$COMMIT_MSG" | head -1)
+      BODY=$(echo "$COMMIT_MSG" | tail -n +3)
+      TYPE=$(echo "$SUBJECT" | sed -E 's/^([a-z]+).*/\1/')
+      SCOPE=$(echo "$SUBJECT" | sed -nE 's/^[a-z]+\(([^)]+)\).*/\1/p')
+
+      # If subject contains [GREEN] and type is feat|fix, verify preceding [RED] commit
+      if echo "$SUBJECT" | grep -q '\[GREEN\]'; then
+        if echo "$TYPE" | grep -qE '^(feat|fix)$'; then
+          # Allow explicit tdd-skip annotation in body
+          if echo "$BODY" | grep -q '\[tdd-skip:'; then
+            echo "  ⚠️  TDD skip recorded: $(echo "$BODY" | grep '\[tdd-skip:' | head -1)"
+          else
+            # Look for a test(scope): [RED] commit in recent history (7 days)
+            SEARCH_SCOPE="${SCOPE:-}"
+            if [ -n "$SEARCH_SCOPE" ]; then
+              RED_FOUND=$(git log --since="7 days ago" --pretty="%s" 2>/dev/null | grep -E "^test\(${SEARCH_SCOPE}\):.*\[RED\]" | head -1)
+            else
+              RED_FOUND=$(git log --since="7 days ago" --pretty="%s" 2>/dev/null | grep -E "^test[:(].*\[RED\]" | head -1)
+            fi
+            if [ -z "$RED_FOUND" ]; then
+              echo ""
+              echo "  ✗ TDD [GREEN] gate: no preceding test(${SCOPE:-*}): [RED] commit found in the last 7 days."
+              echo ""
+              echo "  A [GREEN] commit must follow a [RED] test commit for the same scope."
+              echo "  Expected: test(${SCOPE:-scope}): [RED] <description>"
+              echo ""
+              echo "  To bypass (document the reason): add [tdd-skip: reason] in the commit body."
+              echo "  Example body line: [tdd-skip: brownfield module without test harness]"
+              echo ""
+              exit 1
+            fi
+            echo "  ✅ TDD gate: found preceding RED commit — $RED_FOUND"
+          fi
+        fi
+      fi
+
+      exit 0
+
+  - name: branch-protection
+    trigger: pre-commit
+    description: "Block direct commits to main/master branches"
+    filename: pre-commit-branch-check.sh
+    script: |
+      #!/bin/bash
+      BRANCH=$(git rev-parse --abbrev-ref HEAD)
+      if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+        echo "❌ Direct commits to $BRANCH are blocked. Create a feature branch."
+        exit 1
+      fi
+
+  - name: dangerous-commands
+    trigger: pre-exec
+    description: "Block destructive commands (rm -rf /, DROP DATABASE, force push)"
+    filename: pre-exec-safety.sh
+    script: |
+      #!/bin/bash
+      DANGEROUS_PATTERNS=(
+        "rm -rf /"
+        "DROP DATABASE"
+        "DROP TABLE"
+        "TRUNCATE"
+        "force push"
+        "git push.*--force"
+        "kubectl delete namespace"
+      )
+      for pattern in "${DANGEROUS_PATTERNS[@]}"; do
+        if echo "$1" | grep -iqE "$pattern"; then
+          echo "❌ Blocked dangerous command matching: $pattern"
+          exit 1
+        fi
+      done
+
+  - name: auto-format
+    trigger: pre-commit
+    description: "Run language-appropriate formatter on staged files"
+    filename: pre-commit-format.sh
+    script: |
+      #!/bin/bash
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM)
+      # Python
+      echo "$STAGED" | grep '\.py$' | xargs -r black --quiet 2>/dev/null
+      echo "$STAGED" | grep '\.py$' | xargs -r isort --quiet 2>/dev/null
+      # TypeScript/JavaScript
+      echo "$STAGED" | grep '\.\(ts\|tsx\|js\|jsx\)$' | xargs -r npx prettier --write 2>/dev/null
+      # Rust
+      if echo "$STAGED" | grep -q '\.rs$' && [ -f "Cargo.toml" ]; then
+        cargo fmt 2>/dev/null
+      fi
+      # Re-stage formatted files
+      echo "$STAGED" | xargs -r git add
+
+  - name: secrets-scanner
+    trigger: pre-commit
+    description: "Scan for accidentally committed secrets (AWS keys, API keys, passwords)"
+    filename: pre-commit-secrets.sh
+    script: |
+      #!/bin/bash
+      _fc_write_violation() {
+        local hook_name="$1" severity="${2:-error}" message="$3"
+        local repo_root
+        repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || return 0
+        local dir="$repo_root/.forgecraft"
+        mkdir -p "$dir" 2>/dev/null || return 0
+        local ts
+        ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || printf "unknown")"
+        local esc_msg
+        esc_msg="$(printf '%s' "$message" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+        printf '{"hook":"%s","severity":"%s","message":"%s","timestamp":"%s"}\n' \
+          "$hook_name" "$severity" "$esc_msg" "$ts" \
+          >> "$dir/gate-violations.jsonl" 2>/dev/null || true
+      }
+      PATTERNS=(
+        'AKIA[0-9A-Z]{16}'
+        'password\s*=\s*["\x27][^"\x27]+'
+        'BEGIN RSA PRIVATE KEY'
+        'sk-[a-zA-Z0-9]{48}'
+        'ghp_[a-zA-Z0-9]{36}'
+      )
+      STAGED=$(git diff --cached --name-only)
+      for file in $STAGED; do
+        for pattern in "${PATTERNS[@]}"; do
+          if grep -qE "$pattern" "$file" 2>/dev/null; then
+            echo "❌ Potential secret found in $file matching pattern"
+            _fc_write_violation "pre-commit-secrets" "error" "Potential secrets detected in staged files — review output above"
+            exit 1
+          fi
+        done
+      done
+
+  - name: compile-check
+    trigger: pre-commit
+    description: "Detect project type and run appropriate compile/build check"
+    filename: pre-commit-compile.sh
+    script: |
+      #!/bin/bash
+      _fc_write_violation() {
+        local hook_name="$1" severity="${2:-error}" message="$3"
+        local repo_root
+        repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || return 0
+        local dir="$repo_root/.forgecraft"
+        mkdir -p "$dir" 2>/dev/null || return 0
+        local ts
+        ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || printf "unknown")"
+        local esc_msg
+        esc_msg="$(printf '%s' "$message" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+        printf '{"hook":"%s","severity":"%s","message":"%s","timestamp":"%s"}\n' \
+          "$hook_name" "$severity" "$esc_msg" "$ts" \
+          >> "$dir/gate-violations.jsonl" 2>/dev/null || true
+      }
+      echo "🔨 Running build check..."
+      if [ -f "pyproject.toml" ] || [ -f "setup.py" ] || [ -f "requirements.txt" ]; then
+        STAGED_PY=$(git diff --cached --name-only --diff-filter=ACM | grep '\.py$')
+        if [ -n "$STAGED_PY" ]; then
+          for file in $STAGED_PY; do
+            python -m py_compile "$file" 2>&1
+            if [ $? -ne 0 ]; then
+              echo "❌ Syntax error in $file"
+              _fc_write_violation "pre-commit-compile" "error" "TypeScript compilation failed — run tsc --noEmit to see errors"
+              exit 1
+            fi
+          done
+          echo "  ✅ Python syntax OK"
+        fi
+      fi
+      if [ -f "tsconfig.json" ]; then
+        npx tsc --noEmit 2>&1
+        if [ $? -ne 0 ]; then
+          echo "❌ TypeScript compilation failed."
+          _fc_write_violation "pre-commit-compile" "error" "TypeScript compilation failed — run tsc --noEmit to see errors"
+          exit 1
+        fi
+        echo "  ✅ TypeScript compilation OK"
+      fi
+      if [ -f "Cargo.toml" ]; then
+        STAGED_RS=$(git diff --cached --name-only --diff-filter=ACM | grep '\.rs$')
+        if [ -n "$STAGED_RS" ]; then
+          cargo check --quiet 2>&1
+          if [ $? -ne 0 ]; then
+            echo "❌ Rust cargo check failed."
+            _fc_write_violation "pre-commit-compile" "error" "Rust cargo check failed — run cargo check to see errors"
+            exit 1
+          fi
+          echo "  ✅ Rust cargo check OK"
+        fi
+      fi
+      echo "🔨 Build check passed"
+
+  - name: cargo-clippy
+    trigger: pre-commit
+    stack: [RUST]
+    description: "Run cargo clippy on Rust projects — catches bugs, style issues, and common mistakes beyond cargo check"
+    filename: pre-commit-clippy.sh
+    script: |
+      #!/bin/bash
+      _fc_write_violation() {
+        local hook_name="$1" severity="${2:-error}" message="$3"
+        local repo_root
+        repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || return 0
+        local dir="$repo_root/.forgecraft"
+        mkdir -p "$dir" 2>/dev/null || return 0
+        local ts
+        ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || printf "unknown")"
+        local esc_msg
+        esc_msg="$(printf '%s' "$message" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+        printf '{"hook":"%s","severity":"%s","message":"%s","timestamp":"%s"}\n' \
+          "$hook_name" "$severity" "$esc_msg" "$ts" \
+          >> "$dir/gate-violations.jsonl" 2>/dev/null || true
+      }
+      if [ ! -f "Cargo.toml" ]; then
+        exit 0
+      fi
+      STAGED_RS=$(git diff --cached --name-only --diff-filter=ACM | grep '\.rs$')
+      if [ -z "$STAGED_RS" ]; then
+        exit 0
+      fi
+      echo "🦀 Running cargo clippy..."
+      cargo clippy --all-targets --all-features 2>&1
+      if [ $? -ne 0 ]; then
+        echo "❌ cargo clippy failed — fix lint errors before committing."
+        echo "   Run: cargo clippy --all-targets --all-features"
+        _fc_write_violation "pre-commit-clippy" "error" "Cargo clippy violations found — run cargo clippy to see details"
+        exit 1
+      fi
+      echo "  ✅ cargo clippy passed"
+
+  - name: tdd-phase-gate
+    trigger: pre-commit
+    description: "RED gate: test-only commits must have failing tests; warn on implementation without tests"
+    filename: pre-commit-tdd-check.sh
+    script: |
+      #!/bin/bash
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM)
+      if [ -z "$STAGED" ]; then exit 0; fi
+      SRC_PATTERNS='^(src|lib|app|server|client|pkg|internal|cmd)/'
+      TEST_PATTERNS='^(tests?|spec|__tests__)/'
+      TEST_FILE_PATTERNS='\.(test|spec)\.(ts|tsx|js|jsx|mjs|py|go|rb|java|kt)$'
+      SRC_FILES=()
+      TEST_FILES=()
+      while IFS= read -r file; do
+        if echo "$file" | grep -qE "$SRC_PATTERNS"; then
+          SRC_FILES+=("$file")
+        elif echo "$file" | grep -qE "$TEST_PATTERNS"; then
+          TEST_FILES+=("$file")
+        elif echo "$file" | grep -qE "$TEST_FILE_PATTERNS"; then
+          TEST_FILES+=("$file")
+        fi
+      done <<< "$STAGED"
+      SRC_COUNT=${#SRC_FILES[@]}
+      TEST_COUNT=${#TEST_FILES[@]}
+      # RED gate: test-only commit must have at least one failing test
+      if [ "$TEST_COUNT" -gt 0 ] && [ "$SRC_COUNT" -eq 0 ]; then
+        echo "🔴 TDD gate: test-only commit — running staged tests..."
+        RUN_CMD=""
+        if [ -f "package.json" ]; then
+          if grep -q '"vitest"' package.json 2>/dev/null; then
+            RUN_CMD="npx vitest run"
+          elif grep -q '"jest"' package.json 2>/dev/null; then
+            RUN_CMD="npx jest --passWithNoTests"
+          fi
+        elif [ -f "Cargo.toml" ]; then
+          RUN_CMD="cargo test"
+        elif [ -f "pytest.ini" ] || [ -f "pyproject.toml" ] || [ -f "setup.py" ]; then
+          RUN_CMD="python -m pytest"
+        fi
+        if [ -n "$RUN_CMD" ]; then
+          $RUN_CMD "${TEST_FILES[@]}" > /tmp/tdd-check-output.txt 2>&1
+          if [ $? -eq 0 ]; then
+            echo "❌ TDD RED gate violation: all staged tests PASS"
+            echo "   A test-only commit must contain at least one failing test."
+            echo "   Either tests were written after implementation, or assertions are vacuous."
+            cat /tmp/tdd-check-output.txt | head -30
+            exit 1
+          fi
+          echo "  ✅ RED gate satisfied — staged tests fail as expected"
+        else
+          echo "  ⚠️  Cannot detect test runner — skipping RED gate check"
+        fi
+      fi
+      # Source gate: warn on implementation without tests
+      if [ "$SRC_COUNT" -gt 0 ] && [ "$TEST_COUNT" -eq 0 ]; then
+        echo "⚠️  TDD warning: implementation committed without test changes"
+        echo "   Verify a preceding test(scope): [RED] commit exists in this branch."
+      fi
+      exit 0
+
+  - name: test-coverage
+    trigger: pre-commit
+    description: "Run affected tests only (--changed) for pre-commit; skip for docs/config-only commits"
+    filename: pre-commit-test.sh
+    script: |
+      #!/bin/bash
+      # pre-commit: run only affected tests using --changed flag.
+      # Full suite runs pre-push. TDD_RED=1 bypasses for [RED] commits.
+
+      # TDD RED bypass: skip test run when committing a failing test (RED phase)
+      if [ "${TDD_RED:-0}" = "1" ]; then
+        echo "🔴 TDD_RED=1: bypassing test run for RED commit."
+        exit 0
+      fi
+
+      # Collect staged files once.
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM)
+
+      # Determine what kinds of files are staged.
+      CODE_STAGED=0
+      while IFS= read -r file; do
+        if echo "$file" | grep -qE '^(src|tests?|lib|app)/'; then
+          CODE_STAGED=1
+          break
+        elif echo "$file" | grep -qE '\.(ts|tsx|js|jsx|py|rs)$'; then
+          CODE_STAGED=1
+          break
+        fi
+      done <<< "$STAGED"
+
+      # If no code files at all are staged (docs-only, config-only, etc.) skip the run.
+      if [ "$CODE_STAGED" -eq 0 ]; then
+        echo "🧪 No code files staged — skipping test run."
+        exit 0
+      fi
+
+      echo "🧪 Running affected tests (--changed)..."
+      if [ -f "package.json" ]; then
+        if grep -q '"vitest"' package.json 2>/dev/null; then
+          npx vitest run --changed --passWithNoTests 2>&1
+          if [ $? -ne 0 ]; then
+            echo "❌ Affected tests failed."
+            echo "   To bypass for a RED commit: TDD_RED=1 git commit ..."
+            exit 1
+          fi
+          echo "  ✅ Affected tests passed"
+        elif grep -q '"jest"' package.json 2>/dev/null; then
+          npx jest --passWithNoTests --onlyChanged --silent 2>&1
+          if [ $? -ne 0 ]; then
+            echo "❌ Jest affected tests failed."
+            exit 1
+          fi
+          echo "  ✅ Jest affected tests passed"
+        fi
+      fi
+      if [ -f "pyproject.toml" ] || [ -f "setup.py" ]; then
+        if command -v pytest &> /dev/null; then
+          # pytest doesn't have --changed; run only staged test files as best-effort
+          STAGED_TESTS=$(echo "$STAGED" | grep -E '(test_.*\.py|.*_test\.py)$')
+          if [ -n "$STAGED_TESTS" ]; then
+            pytest --tb=short --quiet $STAGED_TESTS 2>&1
+            if [ $? -ne 0 ]; then
+              echo "❌ Python tests failed."
+              exit 1
+            fi
+            echo "  ✅ Python staged tests passed"
+          else
+            echo "🧪 No Python test files staged — skipping pytest."
+          fi
+        fi
+      fi
+      if [ -f "Cargo.toml" ]; then
+        cargo test --quiet 2>&1
+        if [ $? -ne 0 ]; then
+          echo "❌ Rust tests failed."
+          exit 1
+        fi
+        echo "  ✅ Rust tests passed"
+      fi
+      echo "🧪 Affected tests passed"
+
+  - name: coverage-gate
+    trigger: pre-commit
+    description: "Enforce minimum coverage thresholds when src/ files are staged"
+    filename: pre-commit-coverage.sh
+    script: |
+      #!/bin/bash
+      _fc_write_violation() {
+        local hook_name="$1" severity="${2:-error}" message="$3"
+        local repo_root
+        repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || return 0
+        local dir="$repo_root/.forgecraft"
+        mkdir -p "$dir" 2>/dev/null || return 0
+        local ts
+        ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || printf "unknown")"
+        local esc_msg
+        esc_msg="$(printf '%s' "$message" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+        printf '{"hook":"%s","severity":"%s","message":"%s","timestamp":"%s"}\n' \
+          "$hook_name" "$severity" "$esc_msg" "$ts" \
+          >> "$dir/gate-violations.jsonl" 2>/dev/null || true
+      }
+      # ──────────────────────────────────────────────────────────────────────
+      # Pre-Commit Hook: Coverage Gate
+      #
+      # Enforces minimum coverage thresholds before a commit lands.
+      # Thresholds are read from vitest.config.ts (via --coverage).
+      # Only runs when files under src/ are staged — skips for
+      # docs-only, config-only, or test-only commits.
+      #
+      # Current thresholds (vitest.config.ts):
+      #   Lines / Statements / Functions: {{coverage_minimum | default: 80}}%
+      #   Branches: 70%
+      #
+      # Trigger: git pre-commit (via scripts/setup-hooks.sh)
+      # Exit: 1 blocks commit, 0 allows
+      # ──────────────────────────────────────────────────────────────────────
+
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM)
+
+      if [ -z "$STAGED" ]; then
+        exit 0
+      fi
+
+      # ── Check if any src/ file is staged ─────────────────────────────────
+      SRC_STAGED=0
+      while IFS= read -r file; do
+        if echo "$file" | grep -qE '^src/'; then
+          SRC_STAGED=1
+          break
+        fi
+      done <<< "$STAGED"
+
+      if [ "$SRC_STAGED" -eq 0 ]; then
+        echo "📊 Coverage gate: no src/ files staged, skipping."
+        exit 0
+      fi
+
+      # ── Run coverage ───────────────────────────────────────────────────────
+      echo "📊 Running coverage gate (src/ files staged)..."
+
+      if [ ! -f "package.json" ] && [ ! -f "pyproject.toml" ] && [ ! -f "setup.py" ]; then
+        if [ -f "Cargo.toml" ]; then
+          # Rust: run tests; use cargo-tarpaulin for coverage if available
+          if command -v cargo-tarpaulin &> /dev/null; then
+            cargo tarpaulin --out Stdout --fail-under {{coverage_minimum | default: 80}} 2>&1
+            if [ $? -ne 0 ]; then
+              echo "❌ Coverage gate failed — below {{coverage_minimum | default: 80}}%."
+              echo "   Run: cargo tarpaulin --out Html"
+              _fc_write_violation "pre-commit-coverage" "error" "Coverage gate failed — run npm test --coverage to see report"
+              exit 1
+            fi
+            echo "  ✅ Rust coverage gate passed"
+          else
+            cargo test --quiet 2>&1
+            if [ $? -ne 0 ]; then
+              echo "❌ Rust tests failed."
+              _fc_write_violation "pre-commit-coverage" "error" "Coverage gate failed — run npm test --coverage to see report"
+              exit 1
+            fi
+            echo "  ✅ Rust tests passed (install cargo-tarpaulin for coverage enforcement)"
+          fi
+        else
+          echo "  ⚠️  No supported build system found — skipping coverage check."
+        fi
+        exit 0
+      fi
+
+      if grep -q '"vitest"' package.json 2>/dev/null; then
+        OUTPUT=$(npx vitest run --coverage --reporter=verbose 2>&1)
+        EXIT_CODE=$?
+
+        if [ $EXIT_CODE -ne 0 ]; then
+          echo "$OUTPUT" | grep -E "ERROR|Coverage|does not meet|%|FAIL|passed|failed" | head -40
+          echo ""
+          echo "❌ Coverage gate failed — thresholds not met."
+          echo "   Run 'npx vitest run --coverage' locally to see the full report."
+          echo "   Add tests until coverage meets the configured minimums."
+          _fc_write_violation "pre-commit-coverage" "error" "Coverage gate failed — run npm test --coverage to see report"
+          exit 1
+        fi
+        echo "  ✅ Coverage gate passed"
+        exit 0
+      fi
+
+      if grep -q '"jest"' package.json 2>/dev/null; then
+        COVERAGE_MIN={{coverage_minimum | default: 80}}
+        npx jest --passWithNoTests --coverage \
+          --coverageThreshold="{\"global\":{\"lines\":$COVERAGE_MIN,\"statements\":$COVERAGE_MIN,\"functions\":$COVERAGE_MIN,\"branches\":70}}" \
+          --silent 2>&1
+        if [ $? -ne 0 ]; then
+          echo "❌ Coverage gate failed — thresholds not met."
+          _fc_write_violation "pre-commit-coverage" "error" "Coverage gate failed — run npm test --coverage to see report"
+          exit 1
+        fi
+        echo "  ✅ Coverage gate passed"
+        exit 0
+      fi
+
+      if [ -f "pyproject.toml" ]|| [ -f "setup.py" ]; then
+        if command -v pytest &> /dev/null; then
+          pytest --tb=no --quiet --cov=src --cov-fail-under={{coverage_minimum | default: 80}} 2>&1
+          if [ $? -ne 0 ]; then
+            echo "❌ Coverage gate failed — below {{coverage_minimum | default: 80}}%."
+            _fc_write_violation "pre-commit-coverage" "error" "Coverage gate failed — run npm test --coverage to see report"
+            exit 1
+          fi
+          echo "  ✅ Coverage gate passed"
+        fi
+      fi
+
+      exit 0
+
+  - name: anti-pattern-detector
+    trigger: pre-commit
+    description: "Scan source files for production code anti-patterns. Respects .forgecraft/exceptions.json for recorded false positives."
+    filename: pre-commit-prod-quality.sh
+    checks:
+      - Hardcoded URLs/hosts (localhost, 127.0.0.1)
+      - Mock/stub data in production code
+      - Direct DB calls in route/controller layer (layer violation)
+      - Bare Error throws (custom hierarchy recommended)
+      - .env vs .env.example drift (warns on missing variables)
+    script: |
+      #!/bin/bash
+      _fc_write_violation() {
+        local hook_name="$1" severity="${2:-error}" message="$3"
+        local repo_root
+        repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || return 0
+        local dir="$repo_root/.forgecraft"
+        mkdir -p "$dir" 2>/dev/null || return 0
+        local ts
+        ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || printf "unknown")"
+        local esc_msg
+        esc_msg="$(printf '%s' "$message" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+        printf '{"hook":"%s","severity":"%s","message":"%s","timestamp":"%s"}\n' \
+          "$hook_name" "$severity" "$esc_msg" "$ts" \
+          >> "$dir/gate-violations.jsonl" 2>/dev/null || true
+      }
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM)
+      SOURCE_FILES=$(echo "$STAGED" | grep -E '\.(py|ts|tsx|js|jsx|rs)$' | grep -vE '(test_|\.test\.|\.spec\.|__tests__|tests/|fixtures/|mock|conftest|_test\.rs)')
+      if [ -z "$SOURCE_FILES" ]; then exit 0; fi
+      VIOLATIONS=0
+      WARNINGS=0
+      # Check if a file is covered by a hook exception in .forgecraft/exceptions.json
+      # Usage: is_excepted "layer-boundary" "src/migrations/001.ts"
+      # Add entries to .forgecraft/exceptions.json to record known false positives.
+      is_excepted() {
+        local hook_name="$1"
+        local file_path="$2"
+        if [ ! -f ".forgecraft/exceptions.json" ]; then return 1; fi
+        node -e "
+          const fs = require('fs');
+          const data = JSON.parse(fs.readFileSync('.forgecraft/exceptions.json', 'utf-8'));
+          const exc = (data.exceptions || []).find(e => {
+            if (e.hook !== '$hook_name') return false;
+            const pat = e.pattern.replace(/\\/g, '/').replace(/\./g, '\\\\.').replace(/\*\*/g, '<<<D>>>').replace(/\*/g, '[^/]*').replace(/<<<D>>>/g, '.*');
+            return new RegExp('^' + pat + '$').test('$file_path'.replace(/\\\\/g, '/'));
+          });
+          if (exc) { console.log('EXCEPTED: ' + exc.reason); process.exit(0); }
+          process.exit(1);
+        " 2>/dev/null
+      }
+      echo "🔍 Scanning for production code anti-patterns..."
+      for file in $SOURCE_FILES; do
+        if echo "$file" | grep -vqE '(config|settings|\.env)'; then
+          if grep -nE '(localhost|127\.0\.0\.1|0\.0\.0\.0)' "$file" | grep -vE '(#|//|""")' > /tmp/violations 2>/dev/null; then
+            if [ -s /tmp/violations ]; then
+              echo "  ❌ $file — hardcoded URL/host"
+              VIOLATIONS=$((VIOLATIONS + 1))
+            fi
+          fi
+        fi
+        if ! is_excepted "anti-pattern/mock-data" "$file"; then
+          if grep -nEi '\b(mock_data|fake_data|dummy_data|stub_response)' "$file" > /tmp/violations 2>/dev/null; then
+            if [ -s /tmp/violations ]; then
+              echo "  ❌ $file — mock/stub data in production code"
+              VIOLATIONS=$((VIOLATIONS + 1))
+            fi
+          fi
+        fi
+        # Layer boundary: no direct DB/ORM imports from route handlers / controllers
+        if echo "$file" | grep -qE '(routes|controllers|handlers|endpoints)'; then
+          if ! is_excepted "layer-boundary" "$file"; then
+            if grep -nE '\b(prisma\.|knex\(|mongoose\.|sequelize\.|db\.query|pool\.query)' "$file" > /tmp/violations 2>/dev/null; then
+              if [ -s /tmp/violations ]; then
+                echo "  ❌ $file — direct DB call in route/controller (layer violation)"
+                VIOLATIONS=$((VIOLATIONS + 1))
+              fi
+            fi
+          fi
+        fi
+        # Bare Error throws in business logic (not test files)
+        if ! is_excepted "error-hierarchy" "$file"; then
+          if grep -nE 'throw new Error\(' "$file" > /tmp/violations 2>/dev/null; then
+            if [ -s /tmp/violations ]; then
+              echo "  ⚠️  $file — bare 'throw new Error()' found — use custom error hierarchy"
+              WARNINGS=$((WARNINGS + 1))
+            fi
+          fi
+        fi
+        LINE_COUNT=$(wc -l < "$file")
+        if [ "$LINE_COUNT" -gt {{max_file_length | default: 300}} ]; then
+          echo "  ⚠️  $file — $LINE_COUNT lines (max {{max_file_length | default: 300}})"
+          WARNINGS=$((WARNINGS + 1))
+        fi
+        # Rust-specific anti-patterns
+        if echo "$file" | grep -q '\.rs$'; then
+          if ! is_excepted "rust/unwrap" "$file"; then
+            if grep -nE '\.unwrap\(\)' "$file" > /tmp/violations 2>/dev/null; then
+              if [ -s /tmp/violations ]; then
+                echo "  ⚠️  $file — .unwrap() in production code — use ? or explicit error handling"
+                WARNINGS=$((WARNINGS + 1))
+              fi
+            fi
+          fi
+          if grep -nE '\btodo!\(|\bunimplemented!\(' "$file" > /tmp/violations 2>/dev/null; then
+            if [ -s /tmp/violations ]; then
+              echo "  ❌ $file — todo!/unimplemented! in production code"
+              VIOLATIONS=$((VIOLATIONS + 1))
+            fi
+          fi
+          if grep -nE '^[[:space:]]*#\[allow\(dead_code\)\]' "$file" > /tmp/violations 2>/dev/null; then
+            if [ -s /tmp/violations ]; then
+              echo "  ⚠️  $file — #[allow(dead_code)] suppression — delete orphaned code instead"
+              WARNINGS=$((WARNINGS + 1))
+            fi
+          fi
+          if grep -nE '^[[:space:]]*unsafe[[:space:]]*\{' "$file" > /tmp/violations 2>/dev/null; then
+            if [ -s /tmp/violations ]; then
+              echo "  ⚠️  $file — unsafe block present — requires explicit justification comment"
+              WARNINGS=$((WARNINGS + 1))
+            fi
+          fi
+        fi
+      rm -f /tmp/violations
+      if [ $VIOLATIONS -gt 0 ]; then
+        echo "❌ $VIOLATIONS violation(s) found — commit blocked."
+        _fc_write_violation "pre-commit-anti-patterns" "error" "Anti-patterns detected in staged files — see output above"
+        exit 1
+      fi
+      if [ $WARNINGS -gt 0 ]; then
+        echo "⚠️  $WARNINGS warning(s) found — review recommended."
+      fi
+      echo "🔍 Production quality scan passed"
+
+  - name: function-length
+    trigger: pre-commit
+    description: "Warn when staged functions exceed the configured maximum line count"
+    filename: pre-commit-function-length.sh
+    script: |
+      #!/bin/bash
+      MAX_LENGTH={{max_function_length | default: 50}}
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM)
+      SOURCE_FILES=$(echo "$STAGED" | grep -E '\.(ts|tsx|js|jsx|rs)$' | grep -vE '(\.test\.|\.spec\.|__tests__|tests/|_test\.rs)')
+      if [ -z "$SOURCE_FILES" ]; then exit 0; fi
+      WARNINGS=0
+      for file in $SOURCE_FILES; do
+        # Heuristic: find function/method declarations and count lines to next declaration
+        if echo "$file" | grep -q '\.rs$'; then
+          awk -v max="$MAX_LENGTH" -v fname="$file" '
+            /^[[:space:]]*(pub )?(async )?fn [a-zA-Z_]/ {
+              if (start > 0 && NR - start > max) {
+                printf "  ⚠️  %s:%d — fn starting here is %d lines (max %d)\n", fname, start, NR - start, max
+              }
+              start = NR
+            }
+            END {
+              if (start > 0 && NR - start > max) {
+                printf "  ⚠️  %s:%d — fn starting here is %d lines (max %d)\n", fname, start, NR - start, max
+              }
+            }
+          ' "$file"
+        else
+          awk -v max="$MAX_LENGTH" -v fname="$file" '
+            /^[[:space:]]*(export )?(async )?(function |const [a-zA-Z]+ = (async )?\(|[a-zA-Z]+\(.*\) \{|[a-zA-Z]+\(.*\): )/ {
+              if (start > 0 && NR - start > max) {
+                printf "  ⚠️  %s:%d — function starting here is %d lines (max %d)\n", fname, start, NR - start, max
+                warnings++
+              }
+              start = NR
+            }
+            END {
+              if (start > 0 && NR - start > max) {
+                printf "  ⚠️  %s:%d — function starting here is %d lines (max %d)\n", fname, start, NR - start, max
+                warnings++
+              }
+            }
+          ' "$file"
+        fi
+        WARNINGS=$((WARNINGS + $?))
+      done
+      # Warning only — does not block commit since bash heuristics aren't perfect
+      exit 0
+
+  - name: import-cycle-detector
+    trigger: pre-commit
+    description: "Detect circular import dependencies in TypeScript and Python projects"
+    filename: pre-commit-import-cycles.sh
+    script: |
+      #!/bin/bash
+      echo "🔄 Checking for circular imports..."
+      if [ -f "tsconfig.json" ]; then
+        if command -v npx &> /dev/null; then
+          RESULT=$(npx --yes madge --circular --extensions ts src/ 2>&1)
+          if echo "$RESULT" | grep -q "Found.*circular"; then
+            echo "❌ Circular imports detected in TypeScript:"
+            echo "$RESULT"
+            exit 1
+          fi
+          echo "  ✅ No circular imports (TypeScript)"
+        fi
+      fi
+      if [ -f "pyproject.toml" ] || [ -f "setup.py" ]; then
+        if command -v lint-imports &> /dev/null; then
+          lint-imports 2>&1
+          if [ $? -ne 0 ]; then
+            echo "❌ Circular imports detected in Python"
+            exit 1
+          fi
+          echo "  ✅ No circular imports (Python)"
+        fi
+      fi
+      echo "🔄 Import cycle check passed"
+
+  - name: code-review
+    trigger: pre-commit
+    description: "AI assistant reviews diff against project standards"
+    filename: pre-commit-review.sh
+    script: |
+      #!/bin/bash
+      DIFF=$(git diff --cached)
+      if [ -z "$DIFF" ]; then exit 0; fi
+      echo "📝 Staged changes ready for review"
+      # Full auto-review requires claude CLI integration
+      # This hook validates the diff is non-empty and staged
+      exit 0
+
+  - name: pre-tool-use
+    trigger: pre-tool-use
+    description: "Block Tier 3 (irreversible) operations during Claude Code sessions"
+    filename: pre-tool-use.sh
+    script: |
+      #!/usr/bin/env bash
+      # pre-tool-use: block Tier 3 destructive operations.
+      # Invoked by Claude Code PreToolUse hook before Bash tool executes.
+      set -u
+      input=$(cat)
+      if command -v jq >/dev/null 2>&1; then
+        tool_name=$(echo "$input" | jq -r '.tool_name // empty')
+        cmd=$(echo "$input" | jq -r '.tool_input.command // empty')
+      else
+        tool_name=$(echo "$input" | grep -o '"tool_name":"[^"]*"' | cut -d'"' -f4)
+        cmd=$(echo "$input" | grep -o '"command":"[^"]*"' | cut -d'"' -f4)
+      fi
+      [[ "$tool_name" != "Bash" ]] && exit 0
+      [[ "${FORGECRAFT_ALLOW_DESTRUCTIVE:-0}" == "1" ]] && exit 0
+      block() {
+        echo "🚫 BLOCKED by pre-tool-use hook: $1" >&2
+        echo "   Command: $cmd" >&2
+        echo "   See docs/operation-classification.md" >&2
+        echo "   To override (use with care): FORGECRAFT_ALLOW_DESTRUCTIVE=1 <command>" >&2
+        exit 2
+      }
+      [[ "$cmd" =~ DROP[[:space:]]+TABLE ]] && block "DROP TABLE — Tier 3 irreversible"
+      [[ "$cmd" =~ TRUNCATE[[:space:]] ]] && block "TRUNCATE — Tier 3 irreversible"
+      if [[ "$cmd" =~ git[[:space:]]+push ]] && [[ "$cmd" =~ (-f|--force) ]] && [[ "$cmd" =~ (main|master) ]]; then
+        block "force push to main — Tier 3 irreversible"
+      fi
+      if [[ "$cmd" =~ rm[[:space:]]+-rf ]] && [[ "$cmd" =~ (src|docs|migrations|\.git)[/[:space:]] ]]; then
+        block "rm -rf on protected path — Tier 3"
+      fi
+      if [[ "$cmd" =~ git[[:space:]]+push[[:space:]]+origin[[:space:]]+(main|master) ]]; then
+        echo "⚠️  Direct push to main detected. Use a PR instead." >&2
+      fi
+      exit 0
+
+  - name: post-edit
+    trigger: post-edit
+    description: "After Write/Edit: check Bounded property (file size, console.log, any)"
+    filename: post-edit.sh
+    script: |
+      #!/usr/bin/env bash
+      # post-edit: enforce Bounded property after every file write/edit.
+      set -u
+      input=$(cat)
+      if command -v jq >/dev/null 2>&1; then
+        file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.path // empty')
+      else
+        file_path=$(echo "$input" | grep -o '"file_path":"[^"]*"' | cut -d'"' -f4 | head -1)
+      fi
+      [[ -z "$file_path" ]] && exit 0
+      [[ ! -f "$file_path" ]] && exit 0
+      echo "$file_path" | grep -qE '(node_modules|pnpm-lock|package-lock|\.d\.ts$|\.min\.|/generated/)' && exit 0
+      line_count=$(wc -l < "$file_path")
+      if [[ "$line_count" -gt 300 ]]; then
+        echo "⚠️  BOUNDED: $file_path has $line_count lines (max 300). Extract to sub-modules before commit." >&2
+      fi
+      if [[ "$file_path" =~ \.(ts|tsx|js|jsx)$ ]] && [[ ! "$file_path" =~ \.(test|spec)\. ]] && [[ ! "$file_path" =~ /scripts/ ]]; then
+        grep -q 'console\.\(log\|debug\)' "$file_path" && echo "⚠️  console.log in $file_path — use structured logger" >&2
+        grep -nE '^[^/]*:\s*any\b|\bas\s+any\b' "$file_path" >/dev/null 2>&1 && echo "⚠️  'any' type in $file_path — prefer 'unknown' + narrowing" >&2
+      fi
+      exit 0
+
+  - name: prompt-guard
+    trigger: user-prompt-submit
+    description: "Intercept prompts with destructive or structural signals; inject sentinel reminder"
+    filename: prompt-guard.sh
+    script: |
+      #!/usr/bin/env bash
+      # prompt-guard: runs on every user prompt (UserPromptSubmit).
+      # Two jobs:
+      #   1. Detect Tier 2/3 operation signals -> remind about operation-classification.md.
+      #   2. Detect structural task signals -> remind to read the sentinel first.
+      set -u
+      input=$(cat)
+      if command -v jq >/dev/null 2>&1; then
+        user_prompt=$(echo "$input" | jq -r '.prompt // empty')
+      else
+        user_prompt=$(echo "$input" | grep -o '"prompt":"[^"]*"' | cut -d'"' -f4 | head -1)
+      fi
+      lower=$(echo "$user_prompt" | tr '[:upper:]' '[:lower:]')
+      sensitive_signals=("drop table" "truncate" "delete from" "force push" "full resync"
+        "backfill" "reset db" "disable rls" "service role" "bypass auth"
+        "rm -rf" "drop database" "wipe data")
+      for signal in "${sensitive_signals[@]}"; do
+        if [[ "$lower" == *"$signal"* ]]; then
+          printf "🧭 prompt-guard: destructive signal detected (\"%s\").\n" "$signal"
+          printf "   Before executing:\n"
+          printf "   1. Check docs/operation-classification.md -- classify the operation (Tier 0-3).\n"
+          printf "   2. If Tier 2+: confirm with the user before proceeding.\n"
+          printf "   3. If Tier 3: require FORGECRAFT_ALLOW_DESTRUCTIVE=1 override + ADR.\n"
+          break
+        fi
+      done
+      structural_signals=("create a new" "add a new" "refactor" "migrate" "new feature"
+        "new endpoint" "new module" "change architecture" "add table" "add column"
+        "new component" "new service" "new repository")
+      for signal in "${structural_signals[@]}"; do
+        if [[ "$lower" == *"$signal"* ]]; then
+          printf "🧭 prompt-guard: structural task detected (\"%s\").\n" "$signal"
+          printf "   Before coding:\n"
+          printf "   1. Read CLAUDE.md (sentinel) -- architecture rules and prohibited ops.\n"
+          printf "   2. Read the relevant section of docs/PRD.md or use-cases.md.\n"
+          printf "   3. If decision is non-trivial -> propose an ADR before implementing.\n"
+          printf "   4. If the change spans > 3 files -> propose a brief plan first.\n"
+          break
+        fi
+      done
+      exit 0