ci: introduce unified CI Quality Gate with intelligent path filtering

.github/workflows/ci.yml

@@ -12,8 +12,37 @@ env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
+  changes:
+    name: Detect Changed Paths
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      code: ${{ steps.filter.outputs.code }}
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Detect Changed Paths
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        id: filter
+        with:
+          filters: |
+            code:
+              - '**/*.go'
+              - 'go.mod'
+              - 'go.sum'
+              - 'Makefile'
+              - 'scripts/**'
+              - '.github/workflows/ci.yml'
+              - '.github/workflows/release.yml'
+              - '.golangci.yml'
+
   lint:
     name: GolangCI-Lint
+    needs: [changes]
+    if: github.event_name == 'push' || needs.changes.outputs.code == 'true'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Code
@@ -42,6 +71,8 @@ jobs:
 
   test:
     name: Test & Race (${{ matrix.go-version }})
+    needs: [changes]
+    if: github.event_name == 'push' || needs.changes.outputs.code == 'true'
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -80,6 +111,8 @@ jobs:
 
   integration:
     name: PostgreSQL Integration Tests
+    needs: [changes]
+    if: github.event_name == 'push' || needs.changes.outputs.code == 'true'
     runs-on: ubuntu-latest
     services:
       postgres:
@@ -115,6 +148,8 @@ jobs:
 
   security:
     name: Supply Chain & Vulnerability Scanner
+    needs: [changes]
+    if: github.event_name == 'push' || needs.changes.outputs.code == 'true'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Code
@@ -162,3 +197,66 @@ jobs:
 
       - name: Verify Statement Coverage Gate
         run: ./scripts/check_coverage.sh
+
+  ci-gate:
+    name: CI Quality Gate
+    runs-on: ubuntu-latest
+    if: always()
+    needs:
+      - changes
+      - docs-match-tree
+      - lint
+      - test
+      - integration
+      - security
+    steps:
+      - name: Evaluate CI Quality Gate
+        run: |
+          echo "========================================================"
+          echo "🏁 Evaluating CI Quality Gate"
+          echo "   Event: ${{ github.event_name }}"
+          echo "   Code changes detected: ${{ needs.changes.outputs.code }}"
+          echo "========================================================"
+
+          if [ "${{ needs.changes.result }}" != "success" ]; then
+            echo "❌ Path detection failed with: ${{ needs.changes.result }}" >&2
+            exit 1
+          fi
+
+          if [ "${{ needs.docs-match-tree.result }}" != "success" ]; then
+            echo "❌ Documentation & Version Gate failed with: ${{ needs.docs-match-tree.result }}" >&2
+            exit 1
+          fi
+
+          SHOULD_VERIFY_CODE="${{ github.event_name == 'push' || needs.changes.outputs.code == 'true' }}"
+          if [ "$SHOULD_VERIFY_CODE" = "true" ]; then
+            echo "🔍 Verifying code test suites..."
+            FAILED=0
+
+            check_job() {
+              local name="$1"
+              local result="$2"
+              if [ "$result" != "success" ]; then
+                echo "❌ $name failed with result: $result" >&2
+                FAILED=1
+              else
+                echo "✅ $name: success"
+              fi
+            }
+
+            check_job "GolangCI-Lint" "${{ needs.lint.result }}"
+            check_job "Test & Race" "${{ needs.test.result }}"
+            check_job "PostgreSQL Integration" "${{ needs.integration.result }}"
+            check_job "Supply Chain Scanner" "${{ needs.security.result }}"
+
+            if [ "$FAILED" -ne 0 ]; then
+              echo "❌ CI Quality Gate failed due to errors in code test suite." >&2
+              exit 1
+            fi
+          else
+            echo "📄 Docs-only change detected. Heavy test suites (lint, test, race, integration, security) safely skipped."
+          fi
+
+          echo "========================================================"
+          echo "✅ All CI Quality Gates successfully satisfied!"
+          echo "========================================================"