@boyingliu01/xp-gate 0.10.17 → 0.11.0

package/hooks/pre-commit

@@ -11,16 +11,17 @@
 # 1. Global: ~/.config/xp-gate/adapters (for core.hooksPath global setup)
 # 2. Project-local: <repo>/githooks/ (for per-project init)
 # 3. Script dir: hooks directory containing this script (fallback)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ADAPTER_DIR=""
 GLOBAL_ADAPTER_DIR="$HOME/.config/xp-gate/adapters"
 PROJECT_GITHOOKS="$(git rev-parse --show-toplevel 2>/dev/null)/githooks"
+GATES_DIR="$SCRIPT_DIR/gates"
 
 if [ -f "$GLOBAL_ADAPTER_DIR/adapter-common.sh" ]; then
   ADAPTER_DIR="$GLOBAL_ADAPTER_DIR"
 elif [ -f "$PROJECT_GITHOOKS/adapter-common.sh" ]; then
   ADAPTER_DIR="$PROJECT_GITHOOKS"
 else
-  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
   ADAPTER_DIR="$SCRIPT_DIR"
 fi
 source "$ADAPTER_DIR/adapter-common.sh" 2>/dev/null || {
@@ -29,6 +30,49 @@ source "$ADAPTER_DIR/adapter-common.sh" 2>/dev/null || {
   exit 1
 }
 
+# Resolve adapter file path — handles both layouts:
+#   Global:      ~/.config/xp-gate/adapters/typescript.sh      (flat)
+#   Project:     <repo>/githooks/adapters/typescript.sh          (nested)
+#   Script dir:  <hook-dir>/adapters/typescript.sh               (nested)
+# ADAPTER_DIR points to the base directory that contains either
+# adapter-common.sh directly (global) or adapter-common.sh in a flat layout.
+# Gate scripts live alongside adapter-common.sh.
+resolve_adapter_path() {
+  local lang="$1"
+  # Try flat layout first (global: typescript.sh next to adapter-common.sh)
+  if [ -f "$ADAPTER_DIR/${lang}.sh" ]; then
+    echo "$ADAPTER_DIR/${lang}.sh"
+    return 0
+  fi
+  # Try nested layout (project: adapters/typescript.sh)
+  if [ -f "$ADAPTER_DIR/adapters/${lang}.sh" ]; then
+    echo "$ADAPTER_DIR/adapters/${lang}.sh"
+    return 0
+  fi
+  # Try project githooks as fallback
+  if [ -f "$PROJECT_GITHOOKS/adapters/${lang}.sh" ]; then
+    echo "$PROJECT_GITHOOKS/adapters/${lang}.sh"
+    return 0
+  fi
+  # Try script dir as last resort
+  if [ -f "$SCRIPT_DIR/adapters/${lang}.sh" ]; then
+    echo "$SCRIPT_DIR/adapters/${lang}.sh"
+    return 0
+  fi
+  return 1
+}
+
+# Gate scripts directory — falls back to project githooks if ADAPTER_DIR doesn't have them
+if [ -f "$ADAPTER_DIR/gate-3.sh" ]; then
+  GATE_DIR="$ADAPTER_DIR"
+elif [ -f "$PROJECT_GITHOOKS/gate-3.sh" ]; then
+  GATE_DIR="$PROJECT_GITHOOKS"
+elif [ -f "$SCRIPT_DIR/gate-3.sh" ]; then
+  GATE_DIR="$SCRIPT_DIR"
+else
+  GATE_DIR="$ADAPTER_DIR"
+fi
+
 # Trap: ensure quality report generated on ANY exit (pass or fail).
 # Using a guard prevents recursion when 'exit' is called from inside the trap.
 # IMPORTANT: Captures exit status FIRST so generate_quality_report cannot override it.
@@ -132,7 +176,7 @@ echo ""
 # ============================================================================
 
 CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
-PROTECTED_BRANCHES="main master develop trunk mainline"
+PROTECTED_BRANCHES="master develop trunk mainline"
 ROOT_DIR=$(git rev-parse --show-toplevel 2>/dev/null || echo ".")
 
 # Optional: project-level .protected-branches config file
@@ -155,7 +199,7 @@ if [ "$is_protected" = "true" ]; then
   # Env var bypass: SKIP_VERSION_CHECK=1 skips Gate 0 entirely
   # Useful for: SKIP_VERSION_CHECK=1 git commit -m "chore: ..."
   if [ "${SKIP_VERSION_CHECK:-}" = "1" ]; then
-    echo "✅ PASSED - Gate 0: Version Consistency Check (SKIP_VERSION_CHECK=1 env var)"
+    echo "⏭️  SKIPPED - Gate 0: Version consistency (SKIP_VERSION_CHECK=1 env var)"
   else
   # Check if staged changes include VERSION or CHANGELOG.md
   STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
@@ -540,13 +584,13 @@ GATE_1_START=$(gate_start_ms)
 
 if [ "$PROJECT_LANG" = "documentation-only" ]; then
   # Documentation-only project - skip static analysis
-  echo "✅ PASSED - Skipped (no source code to analyze)."
-   
+  echo "⏭️  SKIPPED - Code quality (documentation project)."
+  
   elif [ "$PROJECT_LANG" = "typescript" ]; then
   # TypeScript: static analysis (tsc) + linting (eslint)
   if ! command -v npx &> /dev/null; then
-    echo "ℹ️  SKIP - npx not available (non-blocking for TypeScript)"
-    echo "✅ PASSED - Code Quality Gate (SKIP)"
+    echo "ℹ️  npx not available — skipping TypeScript checks"
+    echo "⏭️  SKIPPED - Code quality (npx not available)"
   else
     # Verify tsc is real TypeScript compiler (npx may fetch deprecated tsc@2.0.4 placeholder)
     TSC_OUTPUT=$(npx tsc --version 2>&1)
@@ -625,14 +669,36 @@ if [ "$PROJECT_LANG" = "documentation-only" ]; then
       fi
     else
       echo "ℹ️  No ESLint configuration found - Skipping"
+      if [ -f "package.json" ] && command -v node &> /dev/null; then
+        HAS_ESLINT=$(node -e "try{const p=JSON.parse(require('fs').readFileSync('package.json','utf8'));const d=p.devDependencies||{};const deps=p.dependencies||{};console.log((d.eslint||deps.eslint)?'yes':'no')}catch{console.log('no')}") && true
+        if [ "$HAS_ESLINT" = "yes" ]; then
+          echo "⚠️  WARNING: eslint is installed in package.json but no eslint config found"
+          echo "   Either create .eslintrc.* / eslint.config.* or remove eslint from dependencies"
+          echo "   See: https://eslint.org/docs/latest/use/configure/configuration-files"
+        fi
+      fi
+    fi
+
+    # ── Biome config detection ──
+    if ! [ -f "biome.json" ] && ! [ -f "biome.jsonc" ]; then
+      if [ -f "package.json" ] && command -v node &> /dev/null; then
+        HAS_BIOME=$(node -e "try{const p=JSON.parse(require('fs').readFileSync('package.json','utf8'));const d=p.devDependencies||{};const deps=p.dependencies||{};console.log((d['@biomejs/biome']||deps['@biomejs/biome'])?'yes':'no')}catch{console.log('no')}") && true
+        if [ "$HAS_BIOME" = "yes" ]; then
+          echo ""
+          echo "⚠️  WARNING: @biomejs/biome is installed in package.json but no biome.json found"
+          echo "   Create a biome.json configuration file to enable Biome linting."
+          echo "   NOTE: useLiteralKeys conflicts with TypeScript TS4111 — see docs/biome-configuration.md"
+          echo "   For quick setup: add '\"linter\":{\"rules\":{\"complexity\":{\"useLiteralKeys\":\"off\"}}}' to biome.json"
+        fi
+      fi
     fi
   fi
 
 elif [ "$PROJECT_LANG" = "python" ]; then
   # Python: Ruff (includes syntax + linting) + mypy (optional typing)
   if ! command -v ruff &> /dev/null; then
-    echo "ℹ️  SKIP - ruff not available (non-blocking for Python)"
-    echo "✅ PASSED - Code Quality Gate (SKIP)"
+    echo "ℹ️  ruff not available — skipping Python linting"
+    echo "⏭️  SKIPPED - Code quality (ruff not available, run: pip install ruff)"
   else
     # Run Ruff (includes syntax check, linting)
     echo "Running Ruff linting (syntax + lint)..."
@@ -711,8 +777,8 @@ elif [ "$PROJECT_LANG" = "python" ]; then
 elif [ "$PROJECT_LANG" = "go" ]; then
   # Go: go vet + golangci-lint
   if ! command -v golangci-lint &> /dev/null; then
-    echo "ℹ️  SKIP - golangci-lint not available (non-blocking for Go)"
-    echo "✅ PASSED - Code Quality Gate (SKIP)"
+    echo "ℹ️  golangci-lint not available — skipping Go linting"
+    echo "⏭️  SKIPPED - Code quality (golangci-lint not available)"
   else
     echo "Running golangci-lint (comprehensive static analysis)..."
     golangci-lint run 2>&1 | head -30
@@ -799,7 +865,8 @@ elif [ "$PROJECT_LANG" = "shell" ] || echo "$CHANGED_FILES" | grep -qE '\.sh$';
 
 else
   # Route to appropriate adapter for other languages
-  if source "$ADAPTER_DIR/adapters/${PROJECT_LANG}.sh" 2>/dev/null; then
+  ADAPTER_FILE=$(resolve_adapter_path "$PROJECT_LANG")
+  if [ -n "$ADAPTER_FILE" ] && source "$ADAPTER_FILE" 2>/dev/null; then
     echo "Running static analysis for $PROJECT_LANG..."
     run_static_analysis | head -30 2>/dev/null
     ANALYSIS_EXIT=$?
@@ -817,13 +884,13 @@ else
     if [ "$ANALYSIS_EXIT" -eq 0 ] && [ "$LINT_EXIT" -eq 0 ]; then
       echo "✅ PASSED - Language-specific code quality checks."
     else
-      # If tools are not available or failed, skip non-blockingly
-      echo "✅ PASSED - Code Quality Gate (SKIP for unavailable tools)"
+      # Tools unavailable or failed — skip non-blockingly
+      echo "⏭️  SKIPPED - Code quality (tools unavailable or failed)"
     fi
   else
     # If no adapter exists for this language, skip
-    echo "ℹ️  No specific adapter for $PROJECT_LANG - using generic checks if any"
-    echo "✅ PASSED - Code Quality Gate (no specific checks available)."
+    echo "ℹ️  No specific adapter for $PROJECT_LANG — using generic checks if any"
+    echo "⏭️  SKIPPED - Code quality (no specific checks for $PROJECT_LANG)"
   fi
 fi
 GATE_1_STATUS="PASS"
@@ -839,8 +906,8 @@ record_gate_audit "gate-1" "code-quality" "$GATE_1_STATUS" "0" "$GATE_1_START"
 GATE_2_START=$(gate_start_ms)
 
 if [ "$PROJECT_LANG" = "documentation-only" ]; then
-  echo "✅ PASSED - Skipped (no source code to analyze)."
-  
+echo "⏭️  SKIPPED - Duplicate code (documentation project)."
+
 elif [ "$PROJECT_LANG" = "typescript" ]; then
   if ! require_tool "jscpd" "Gate 2" "npm install -D jscpd"; then
     exit 1
@@ -886,11 +953,11 @@ elif [ "$PROJECT_LANG" = "go" ]; then
 
 elif [ "$PROJECT_LANG" = "powershell" ]; then
   echo "ℹ️  No PowerShell-native duplicate detector (jscpd does not support .ps1)"
-  echo "✅ PASSED - Skipped (no standardized tool for PowerShell duplicate detection)"
+  echo "⏭️  SKIPPED - Duplicate code (no tool for PowerShell)"
 
 elif [ "$PROJECT_LANG" = "shell" ]; then
   echo "ℹ️  Duplicate detection not typically used for shell scripts"
-  echo "✅ PASSED - Skipped (shell scripts, no standardized dup tool)"
+  echo "⏭️  SKIPPED - Duplicate code (no tool for shell scripts)"
 
 else
   SOURCE_FILES=$(echo "$CHANGED_FILES" | grep -E '\.(ts|tsx|js|jsx|py|go|java|scala|kt|cpp|c|h|rs|php|dart|swift)$')
@@ -909,132 +976,16 @@ GATE_2_STATUS="PASS"
 record_gate_audit "gate-2" "duplicate-code" "$GATE_2_STATUS" "0" "$GATE_2_START"
 
 # ============================================================================
-# GATE 3: Cyclomatic Complexity Check (Old Gate 7)
-# Uses lizard - keeps existing logic for consistency
+# GATE 3: Cyclomatic Complexity Check
+# Extracted to gate-3.sh for maintainability
 # ============================================================================
- 2>&1 echo ""
- 2>&1 echo "→ Gate 3: Cyclomatic complexity..."
-GATE_3_START=$(gate_start_ms)
-
-if [ "$PROJECT_LANG" = "documentation-only" ]; then
-  echo "✅ PASSED - Skipped (documentation project)."
-
-elif [ "$PROJECT_LANG" = "powershell" ]; then
-  echo "ℹ️  No PowerShell principles checker available"
-  echo "✅ PASSED - Skipped (no PowerShell Clean Code / SOLID tool)"
-  
-else
-  CCN_THRESHOLD=5
-  
-  # Check lizard availability
-  LIZARD_CMD=""
-  if command -v lizard > /dev/null 2>&1; then
-    LIZARD_CMD=lizard
-  elif [ -f ~/.local/bin/lizard ]; then
-    LIZARD_CMD=~/.local/bin/lizard
-  fi
-  
-  if [ -n "$LIZARD_CMD" ]; then
-    LIZARD_PATH=$(eval echo "$LIZARD_CMD")
-    
-    # Get changed source files for complexity check
-    CC_FILES=$(echo "$CHANGED_FILES" | grep -E '\.(ts|tsx|js|jsx|py|go|java|swift|cpp|c|hpp|h|m|mm|kt)$' || true)
-    
-    if [ -n "$CC_FILES" ]; then
-      echo "Checking complexity for source files..."
-      
-      # Run lizard with CCN threshold
-      CC_OUTPUT=$($LIZARD_PATH -C $CCN_THRESHOLD $CC_FILES 2>&1 || true)
-      
-      # Parse warning count from the summary table: "Warning cnt   8"
-      # Use anchored grep to avoid matching lizard table headers (e.g. "Rt" column)
-      CC_WARNINGS=$(echo "$CC_OUTPUT" | grep "^Warning cnt" | awk '{print $NF}' | tr -d '[:space:]' | sed 's/[^0-9]//g' || true)
-      CC_WARNINGS=${CC_WARNINGS:-0}
-      
-      if [ "$CC_WARNINGS" -gt 0 ]; then
-        echo "$CC_OUTPUT"
-        echo ""
-        echo "❌ BLOCKED - $CC_WARNINGS functions with CCN > $CCN_THRESHOLD found."
-        echo "Refactor high-complexity functions to keep below $CCN_THRESHOLD complexity."
-        exit 1
-      else
-        echo "✅ PASSED - All functions within complexity threshold ($CCN_THRESHOLD)."
-      fi
-    else
-      echo "✅ PASSED - No source files to check for complexity."
-    fi
-  else
-    echo "⚠️  WARN - lizard not installed, complexity check not performed"
-    echo "   Install with: pip install --user lizard"
-    echo "   Gate 3: Complexity check (WARN, tool not available)"
-    GATE_3_STATUS="WARN"
-  fi
-fi
-GATE_3_STATUS="PASS"
-record_gate_audit "gate-3" "complexity" "$GATE_3_STATUS" "${CC_WARNINGS:-0}" "$GATE_3_START"
+source "$GATE_DIR/gate-3.sh"
 
 # ============================================================================
-# GATE 4: Principles Checker (Old Gate 6 - Clean Code + SOLID)
-# Reuses existing principles checker logic
+# GATE 4: Principles Checker (Clean Code + SOLID)
+# Extracted to gate-4.sh for maintainability
 # ============================================================================
- 2>&1 echo ""
- 2>&1 echo "→ Gate 4: Principles checker (Clean Code + SOLID)..."
-GATE_4_START=$(gate_start_ms)
-
-if [ "$PROJECT_LANG" = "documentation-only" ]; then
-  echo "✅ PASSED - Skipped (documentation project)."
-  
-else
-  # Get source files to check against principles
-  PRINCIPLES_FILES=$(echo "$CHANGED_FILES" | grep -E '\.(ts|tsx|js|jsx|py|go|java|kt|dart|swift|cpp|c|hpp|h|m|mm)$' || true)
-  
-  if [ -n "$PRINCIPLES_FILES" ]; then
-    # Check if principles checker exists in project
-    if [ -f "src/principles/index.ts" ]; then
-      echo "Checking Clean Code + SOLID principles..."
-      
-      if command -v npx > /dev/null 2>&1; then
-        # Run principles checker and store results
-        if npx tsx src/principles/index.ts --files $PRINCIPLES_FILES --format json > /tmp/principles-output.json 2>/dev/null; then
-          # Check severity levels
-          ERROR_COUNT=$(grep -c '"severity":"error"' /tmp/principles-output.json 2>/dev/null || true)
-          ERROR_COUNT=${ERROR_COUNT:-0}
-          WARNING_COUNT=$(grep -c '"severity":"warning"' /tmp/principles-output.json 2>/dev/null || true)
-          WARNING_COUNT=${WARNING_COUNT:-0}
-          
-          if [ "$ERROR_COUNT" -gt 0 ]; then
-            echo ""
-            echo "❌ BLOCKED - $ERROR_COUNT principle ERROR(S) found"
-            echo "Critical violations must be fixed before commit:"
-            echo "  - error-handling violations"
-            echo "  - SOLID principle violations"
-            echo "  - architectural violations"
-            npx tsx src/principles/index.ts --files $PRINCIPLES_FILES --format console
-            exit 1
-          fi
-          
-          echo "✅ PASSED - Principles checker (no errors found)."
-          if [ "$WARNING_COUNT" -gt 0 ]; then
-            echo "ℹ️  $WARNING_COUNT warnings found (will be handled by Boy Scout Rule)."
-          fi
-        else
-          echo "⚠️  Warning: Principles checker execution failed"
-          echo "✅ PASSED - Principles check (SKIP, execution issue)"
-        fi
-      else
-        echo "ℹ️  npx not available - skipping principles check"
-        echo "✅ PASSED - Principles check (SKIP, no Node.js)"
-      fi
-    else
-      echo "ℹ️  Principles checker not found in project - skipping"
-      echo "✅ PASSED - Principles check (SKIP, not available in project)"
-    fi
-  else
-    echo "✅ PASSED - No source files changed (principles check skipped)."
-  fi
-fi
-GATE_4_STATUS="PASS"
-record_gate_audit "gate-4" "principles" "$GATE_4_STATUS" "${WARNING_COUNT:-0}" "$GATE_4_START"
+source "$GATE_DIR/gate-4.sh"
 
 # ============================================================================
 # GATE 5: Tests & Coverage Combined (Combines Old Gates 3 - Tests and 4 - Coverage)
@@ -1049,15 +1000,133 @@ if [ "$PROJECT_LANG" = "documentation-only" ]; then
 
 else
   # ========================================================================
-  # Gate 5a: Test-Source File Pairing Check (WARNING only)
+  # Gate 5a: Test-Source File Pairing Check
+  # New .ts/.tsx files: BLOCK (no corresponding test → commit rejected)
+  # Modified files (any lang): WARNING (backward compatible)
+  # New non-TS files: WARNING (unchanged)
+  # Escape valve: SKIP_GATE_5A_BLOCK=1 (non-main/master only, audit logged)
+  # Grace period: .tdd-adoption.yaml gracePeriod: N (first N commits = WARNING only)
   # Checks coexistence, not temporal order. True "test-first" enforced by
   # Agent skills (Layer 1 + Layer 4).
   # ========================================================================
-  NEW_SOURCE_FILES=$(git diff --cached --name-only --diff-filter=A | grep -E '\.(ts|tsx|py|go|java|kt|kts|cpp|cc|cxx|c|swift|dart|rb|rs)$' | grep -v '__tests__' | grep -v '\.test\.' | grep -v '\.spec\.' | grep -v '__snapshots__' || true)
 
-  if [ -n "$NEW_SOURCE_FILES" ]; then
+  # --- Pre-checks: grace period + escape valve ---
+  TDD_GRACE=0
+  if [ -f ".tdd-adoption.yaml" ]; then
+    TDD_ENABLED=$(grep -E '^\s*enabled:' .tdd-adoption.yaml | awk '{print $2}' || echo "true")
+    if [ "$TDD_ENABLED" != "false" ]; then
+      TDD_GRACE=$(grep -E '^\s*gracePeriod:' .tdd-adoption.yaml | awk '{print $2}' || echo "0")
+    fi
+  fi
+
+  TDD_BLOCK_DOWNGRADE=false
+  if [ "$TDD_GRACE" -gt 0 ] 2>/dev/null; then
+    TDD_BLOCK_DOWNGRADE=true
+  fi
+
+  SKIP_5A_BLOCK=false
+  if [ "${SKIP_GATE_5A_BLOCK:-0}" = "1" ]; then
+    CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+    if [ "$CURRENT_BRANCH" != "main" ] && [ "$CURRENT_BRANCH" != "master" ]; then
+      REASON="${SKIP_GATE_5A_BLOCK_REASON:-not specified}"
+      mkdir -p .xp-gate/reports
+      # Escape special characters in REASON for valid JSON
+      ESCAPED_REASON=$(printf '%s' "$REASON" | sed 's/\\/\\\\/g; s/"/\\"/g')
+      ESCAPED_USER=$(printf '%s' "$(git config user.name)" | sed 's/\\/\\\\/g; s/"/\\"/g')
+      echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"branch\":\"$CURRENT_BRANCH\",\"user\":\"$ESCAPED_USER\",\"reason\":\"$ESCAPED_REASON\",\"gate\":\"5a-block\"}" >> .xp-gate/reports/escape-valve-log.json
+      echo "⚠️  ESCAPE VALVE: SKIP_GATE_5A_BLOCK=1 on branch $CURRENT_BRANCH (reason: $REASON)"
+      echo "   ⚠️  Post-mortem issue required within 24h"
+      SKIP_5A_BLOCK=true
+    else
+      echo "❌ ESCAPE VALVE BLOCKED: SKIP_GATE_5A_BLOCK not allowed on main/master branch"
+      exit 1
+    fi
+  fi
+
+  # --- BLOCK path: New .ts/.tsx files without corresponding tests ---
+  NEW_TS_FILES=$(git diff --cached --name-only --diff-filter=A | grep -E '\.(ts|tsx)$' | grep -v '\.d\.ts$' | grep -v '__tests__' | grep -v '\.test\.' | grep -v '\.spec\.' | grep -v '__snapshots__' | grep -v 'node_modules/' | grep -v '\.next/' | grep -v '\.nuxt/' | grep -v 'dist/' | grep -v 'build/' | grep -v '.turbo/' | grep -v '.cache/' | grep -Ev '(^|/)vitest\.config\.' | grep -Ev '(^|/)vite\.config\.' | grep -Ev '(^|/)jest\.config\.' | grep -Ev '(^|/)tsconfig\.' | grep -Ev '(^|/)eslint\.' | grep -Ev '(^|/)prettier\.' | grep -Ev '(^|/)tailwind\.' || true)
+
+  if [ -n "$NEW_TS_FILES" ]; then
+    BLOCKED_TS_FILES=0
+    for src_file in $NEW_TS_FILES; do
+      base="${src_file%.*}"
+      ext="${src_file##*.}"
+      filename="${base##*/}"
+      dir="$(dirname "$src_file")"
+
+      # Skip excluded files: index/barrel, types, interfaces, constants, declarations
+      case "$filename" in
+        index|types|interfaces|constants|__init__) continue ;;
+      esac
+      case "$ext" in
+        d.ts|pyi) continue ;;
+      esac
+      # Skip files with @no-test-required (reason >= 10 chars) or legacy @no-test annotation
+      # Order matters: @no-test-required must be checked first — @no-test is a substring match
+      if grep -q '@no-test-required' "$src_file" 2>/dev/null; then
+        if grep -qE '@no-test-required\s*:\s*.{10,}' "$src_file" 2>/dev/null; then
+          continue
+        fi
+        # @no-test-required with short reason (< 10 chars) — fall through to BLOCK
+      elif grep -q '@no-test' "$src_file" 2>/dev/null; then
+        continue
+      fi
+
+      # Check common test file patterns for TypeScript
+      TEST_FOUND=false
+      patterns=(
+        "${base}.test.${ext}"
+        "${base}.spec.${ext}"
+        "${dir}/__tests__/${filename}.test.${ext}"
+        "${dir}/__tests__/${filename}.spec.${ext}"
+        "tests/${filename}.test.${ext}"
+        "tests/${filename}.spec.${ext}"
+      )
+
+      for pattern in "${patterns[@]}"; do
+        if [[ "$pattern" == *'*'* ]]; then
+          found=$(find . -path "*/${pattern}" -type f 2>/dev/null | head -1)
+          if [ -n "$found" ]; then TEST_FOUND=true; break; fi
+        elif [ -f "$pattern" ]; then
+          TEST_FOUND=true
+          break
+        fi
+      done
+
+      if [ "$TEST_FOUND" = false ]; then
+        if [ "$SKIP_5A_BLOCK" = true ] || [ "$TDD_BLOCK_DOWNGRADE" = true ]; then
+          echo "⚠️  TEST PAIRING WARNING (downgraded): New TypeScript file without test: $src_file"
+          echo "   Expected: ${patterns[0]}, ${patterns[1]:-...}"
+          echo "   Or: Add '// @no-test-required: <reason>' if this file doesn't need tests"
+        else
+          echo "❌ BLOCKED: $src_file — New TypeScript source file without corresponding test"
+          echo "   Expected: ${patterns[0]}, ${patterns[1]:-...}"
+          echo "   Add '// @no-test-required: <reason>' if this file doesn't need tests"
+          BLOCKED_TS_FILES=$((BLOCKED_TS_FILES + 1))
+        fi
+      fi
+    done
+
+    if [ "$BLOCKED_TS_FILES" -gt 0 ]; then
+      echo ""
+      echo "❌ $BLOCKED_TS_FILES new TypeScript file(s) without corresponding tests — commit BLOCKED"
+      echo "   Add test files or '// @no-test-required: <reason>' annotation."
+      echo "   Escape valve: SKIP_GATE_5A_BLOCK=1 (non-main/master only)"
+      exit 1
+    fi
+  fi
+
+  # --- WARNING path: Modified files (any lang) + New non-TS files ---
+  WARNING_SOURCE_FILES=$(
+    {
+      git diff --cached --name-only --diff-filter=M | grep -E '\.(ts|tsx|py|go|java|kt|kts|cpp|cc|cxx|c|swift|dart|rb|rs)$' | grep -v '__tests__' | grep -v '\.test\.' | grep -v '\.spec\.' | grep -v '__snapshots__'
+      git diff --cached --name-only --diff-filter=A | grep -E '\.(py|go|java|kt|kts|cpp|cc|cxx|c|swift|dart|rb|rs)$' | grep -v '__tests__' | grep -v '\.test\.' | grep -v '\.spec\.' | grep -v '__snapshots__'
+    } | sort -u || true
+  )
+
+  if [ -n "$WARNING_SOURCE_FILES" ]; then
     PAIRING_WARNINGS=0
-    for src_file in $NEW_SOURCE_FILES; do
+    for src_file in $WARNING_SOURCE_FILES; do
       base="${src_file%.*}"
       ext="${src_file##*.}"
       filename="${base##*/}"
@@ -1070,8 +1139,14 @@ else
       case "$ext" in
         d.ts|pyi) continue ;;
       esac
-      # Skip files with // @no-test annotation
-      if grep -q '@no-test' "$src_file" 2>/dev/null; then
+      # Skip files with @no-test-required (reason >= 10 chars) or legacy @no-test annotation
+      # Order matters: @no-test-required must be checked first — @no-test is a substring match
+      if grep -q '@no-test-required' "$src_file" 2>/dev/null; then
+        if grep -qE '@no-test-required\s*:\s*.{10,}' "$src_file" 2>/dev/null; then
+          continue
+        fi
+        # @no-test-required with short reason (< 10 chars) — fall through to BLOCK
+      elif grep -q '@no-test' "$src_file" 2>/dev/null; then
         continue
       fi
 
@@ -1149,18 +1224,18 @@ else
       done
 
       if [ "$TEST_FOUND" = false ]; then
-        echo "⚠️  TEST PAIRING WARNING: New source file without corresponding test: $src_file"
+        echo "⚠️  TEST PAIRING WARNING: Source file without corresponding test: $src_file"
         echo "   Expected patterns for .${ext}: ${patterns[0]}, ${patterns[1]:-...}"
-        echo "   Or: Add '// @no-test' annotation if this file doesn't need tests"
+        echo "   Or: Add '// @no-test-required: <reason>' annotation if this file doesn't need tests"
         PAIRING_WARNINGS=$((PAIRING_WARNINGS + 1))
       fi
     done
 
     if [ "$PAIRING_WARNINGS" -gt 0 ]; then
       echo ""
-      echo "⚠️  $PAIRING_WARNINGS new source file(s) without corresponding tests"
+      echo "⚠️  $PAIRING_WARNINGS source file(s) without corresponding tests"
       echo "   This is a WARNING — commit proceeds. TDD order enforced by Agent skills."
-      echo "   To suppress for specific files, add '// @no-test' at the top."
+      echo "   To suppress for specific files, add '// @no-test-required: <reason>' at the top."
     fi
   fi
 
@@ -1180,7 +1255,11 @@ else
                   'mockResolvedValue' 'mockRejectedValue' 'mockReturnValue' 'mockImplementation' \
                   'createMock' 'mockReset' 'mockClear' 'mockRestore' 'MagicMock' 'unittest\.mock' \
                   '\.patch(' 'gomock' 'mockgen' '.EXPECT()'; do
-          c=$(grep -c "$kw" "$test_file" 2>/dev/null)
+          # Use grep -o piped to wc -l for reliable single-number output (grep -c can emit
+          # multi-line output with filenames under some grep versions, causing bash arithmetic
+          # syntax errors). grep -o extracts each match on its own line, wc -l counts them.
+          c=$(grep -o "$kw" "$test_file" 2>/dev/null | wc -l || true)
+          c=${c//[^0-9]/}
           c=${c:-0}
           MOCK_COUNT=$((MOCK_COUNT + c))
         done
@@ -1219,8 +1298,9 @@ else
   echo "Running tests..."
   
   # Route to appropriate test runner via adapter
-  if [ "${PROJECT_LANG}" != "unknown" ] && [ -f "$ADAPTER_DIR/adapters/${PROJECT_LANG}.sh" ]; then
-    if source "$ADAPTER_DIR/adapters/${PROJECT_LANG}.sh" 2>/dev/null; then
+  ADAPTER_FILE=$(resolve_adapter_path "$PROJECT_LANG")
+  if [ "${PROJECT_LANG}" != "unknown" ] && [ -n "$ADAPTER_FILE" ]; then
+    if source "$ADAPTER_FILE" 2>/dev/null; then
       TESTS_OUTPUT=$(run_tests 2>&1)
       TESTS_EXIT_CODE=$?
       echo "$TESTS_OUTPUT" | head -50
@@ -1232,17 +1312,17 @@ else
         echo "✅ PASSED - Unit tests passed."
       fi
     else
-      echo "✅ PASSED - No adapter for tests, assuming none to run."
+      echo "✅ PASSED - Could not source ${PROJECT_LANG} adapter for tests, assuming none to run."
     fi
   else
-    echo "✅ PASSED - No specific adapter, no tests to run."
+    echo "✅ PASSED - No ${PROJECT_LANG} adapter found for tests, assuming none to run."
   fi
   
   # Next, run coverage check
   echo "Running coverage check..."
 
-  if [ "${PROJECT_LANG}" != "unknown" ] && [ -f "$ADAPTER_DIR/adapters/${PROJECT_LANG}.sh" ]; then
-    if source "$ADAPTER_DIR/adapters/${PROJECT_LANG}.sh" 2>/dev/null; then
+  if [ "${PROJECT_LANG}" != "unknown" ] && [ -n "$ADAPTER_FILE" ]; then
+    if source "$ADAPTER_FILE" 2>/dev/null; then
       case "$PROJECT_LANG" in
         "typescript")
           if [ -f "package.json" ] && grep -q '"test:coverage"' package.json 2>/dev/null; then
@@ -1299,12 +1379,12 @@ else
       esac
     else
       # Adapter source failed — warn and let Stage 2 attempt file-based enforcement
-      echo "⚠️  Could not source ${PROJECT_LANG} adapter, will check coverage files directly..."
+      echo "⚠️  Could not source ${PROJECT_LANG} adapter from ${ADAPTER_FILE}, will check coverage files directly..."
       COV_EXIT=0
     fi
   else
     # No adapter available — warn and let Stage 2 attempt file-based enforcement
-    echo "⚠️  No adapter for ${PROJECT_LANG}, will check coverage files directly..."
+    echo "⚠️  No adapter found for ${PROJECT_LANG} (searched: ${ADAPTER_DIR}/, ${ADAPTER_DIR}/adapters/, ${PROJECT_GITHOOKS}/adapters/, ${SCRIPT_DIR}/adapters/) — will check coverage files directly..."
     COV_EXIT=0
   fi
 
@@ -1488,7 +1568,7 @@ if [ "$PROJECT_LANG" = "documentation-only" ]; then
 
 elif [ "$PROJECT_LANG" = "powershell" ]; then
   echo "     ℹ️  No PowerShell architecture tooling available"
-  echo "     ✅ Architecture validation (SKIP, no tool for PowerShell)"
+     echo "     ⏭️  SKIPPED - Architecture validation (no tool for PowerShell)"
 
 else
   # Check if architecture config exists
@@ -1549,7 +1629,7 @@ else
           fi
         else
           echo "     ℹ️  No .import-linter.yml found - skipping Python architecture"
-          echo "     ✅ Python architecture validation (SKIP, no config)"
+          echo "     ⏭️  SKIPPED - Python architecture validation (no config)"
         fi
         ;;
       "go")
@@ -1565,7 +1645,7 @@ else
           fi
         else
           echo "     ℹ️  No arch-go.yaml found - skipping Go architecture"
-          echo "     ✅ Go architecture validation (SKIP, no config)"
+          echo "     ⏭️  SKIPPED - Go architecture validation (no config)"
         fi
         ;;
       "java")
@@ -1581,19 +1661,19 @@ else
           echo "     ✅ Java architecture validation completed."
         else
           echo "     ℹ️  No architecture test files found - skipping"
-          echo "     ✅ Architecture validation (SKIP, no tests)"
+          echo "     ⏭️  SKIPPED - Architecture validation (no tests)"
         fi
         ;;
       *)
         echo "     ℹ️  Architecture validation not configured for $PROJECT_LANG"
-        echo "     ✅ Architecture validation (SKIP, not configured)"
+        echo "     ⏭️  SKIPPED - Architecture validation (not configured for $PROJECT_LANG)"
         ;;
     esac
   else
     # Architecture config is REQUIRED — BLOCK if missing
     if [ -f ".architecture-skip" ]; then
       echo "     ⚠️  Architecture config missing but .architecture-skip present — allowed to skip"
-      echo "     ✅ Architecture validation (SKIP, .architecture-skip exemption)"
+      echo "     ⏭️  SKIPPED - Architecture validation (.architecture-skip exemption)"
     else
       echo ""
       echo "❌ ARCHITECTURE CONFIG MISSING - COMMIT BLOCKED"
@@ -1626,8 +1706,15 @@ if [ "$PROJECT_LANG" = "documentation-only" ]; then
   echo "     ✅ Skipped (documentation project)."
   
 else
-  # Check if principles directory exists for Boy Scout
-  if [ -f "src/principles/boy-scout.ts" ]; then
+  # Check for Boy Scout script in installed modules first, then project src/
+  BOY_SCOUT_SCRIPT=""
+  if [ -f ".xp-gate/modules/principles/boy-scout.ts" ]; then
+    BOY_SCOUT_SCRIPT=".xp-gate/modules/principles/boy-scout.ts"
+  elif [ -f "src/principles/boy-scout.ts" ]; then
+    BOY_SCOUT_SCRIPT="src/principles/boy-scout.ts"
+  fi
+  
+  if [ -n "$BOY_SCOUT_SCRIPT" ]; then
     echo "     Checking Boy Scout Rule compliance..."
     
     # Separate new files and modified files
@@ -1643,7 +1730,7 @@ else
         if [ -z "$(echo "$NEW_FILES" | tr -d ' ')" ] && [ -z "$(echo "$MODIFIED_FILES" | tr -d ' ')" ]; then
           echo "     ✅ No new or modified source files for Boy Scout check."
         else
-          BOY_SCOUT_OUTPUT=$(npx tsx src/principles/boy-scout.ts \
+          BOY_SCOUT_OUTPUT=$(npx tsx $BOY_SCOUT_SCRIPT \
             --new-files "$(echo "$NEW_FILES" | tr ' ' ',')" \
             --modified-files "$(echo "$MODIFIED_FILES" | tr ' ' ',')" \
             --baseline ".warnings-baseline.json" 2>&1)
@@ -1675,12 +1762,12 @@ else
         fi
       else
         echo "     ℹ️  npx not available - skipping Boy Scout Rule"
-        echo "     ✅ Boy Scout Rule (SKIP, Node.js not available)"
+        echo "     ⏭️  SKIPPED - Boy Scout Rule (Node.js/npx not available)"
       fi
     fi
   else
     echo "     ℹ️  Boy scout rule not available in project - skipping"
-    echo "     ✅ Boy Scout Rule (SKIP, not available in project)"
+    echo "     ⏭️  SKIPPED - Boy Scout Rule (not available in project)"
   fi
 fi
 GATE_6_STATUS="PASS"
@@ -1690,105 +1777,15 @@ record_gate_audit "gate-6" "architecture-boy-scout" "$GATE_6_STATUS" "${BS_BLOCK
 
 # ============================================================================
 # GATE 7: IaC Security Scanning (Terraform, Kubernetes, Docker)
-# Detects security issues in Infrastructure as Code files
-# Tools: checkov (recommended), hadolint, kube-score, tflint
+# Extracted to gate-7.sh for maintainability
 # ============================================================================
- 2>&1 echo ""
- 2>&1 echo "→ Gate 7: IaC Security Scanning (Terraform, Kubernetes, Docker)..."
-GATE_7_START=$(gate_start_ms)
-
-# Check if any IaC files are changed
-IAC_FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null | grep -E "\.(tf|yaml|yml)$|Dockerfile" || true)
-if [ -z "$IAC_FILES" ]; then
-  echo "✅ PASSED - No IaC files detected in changes."
-  GATE_7_STATUS="PASS"
-else
-  # Run IaC adapter
-  if [ -f "githooks/adapters/iac.sh" ]; then
-    # shellcheck source=githooks/adapters/iac.sh
-    source "githooks/adapters/iac.sh"
-    
-    # Run static analysis for IaC files
-    IAC_OUTPUT=$(run_static_analysis "$IAC_FILES" 2>&1)
-    IAC_EXIT=$?
-    
-    echo "$IAC_OUTPUT"
-    
-    if [ $IAC_EXIT -eq 0 ]; then
-      echo "✅ PASSED - IaC security scan."
-      GATE_7_STATUS="PASS"
-    else
-      echo ""
-      echo "❌ BLOCKED - IaC security issues detected"
-      echo "Fix the security issues above before committing."
-      echo "Tip: Install checkov for comprehensive IaC scanning: pip install checkov"
-      GATE_7_STATUS="FAIL"
-      exit 1
-    fi
-  else
-    echo "ℹ️  SKIP - IaC adapter not found"
-    echo "✅ PASSED - IaC Security (SKIP)"
-    GATE_7_STATUS="SKIP"
-  fi
-fi
-record_gate_audit "gate-7" "iac-security" "$GATE_7_STATUS" "0" "$GATE_7_START"
+source "$GATE_DIR/gate-7.sh"
 
 
 # GATE 8: Secret Scanning (gitleaks)
-# Detects secrets (API keys, passwords, tokens) in staged files
-# Tool: gitleaks -- https://github.com/gitleaks/gitleaks
+# Extracted to gate-8.sh for maintainability
 # ============================================================================
-
- 2>&1 echo ""
- 2>&1 echo "→ Gate 8: Secret scanning (gitleaks)..."
-GATE_8_START=$(gate_start_ms)
-
-# Gitleaks availability check
-GITLEAKS_CMD=""
-if command -v gitleaks >/dev/null 2>&1; then
-  GITLEAKS_CMD="gitleaks"
-elif [ -f "$HOME/.local/bin/gitleaks" ]; then
-  GIBLEAKS_CMD="$HOME/.local/bin/gitleaks"
-fi
-
-if [ -n "$GITLEAKS_CMD" ]; then
-  GITLEAKS_CONFIG=""
-  if [ -f ".gitleaks.toml" ]; then
-    GITLEAKS_CONFIG="--config=.gitleaks.toml"
-  fi
-
-  # Run gitleaks on staged changes only (pre-commit mode for speed)
-  GITLEAKS_OUTPUT=$($GITLEAKS_CMD git --pre-commit --redact --no-banner $GITLEAKS_CONFIG --report-format=json --report-path=/tmp/gitleaks-report.json 2>&1)
-  GITLEAKS_EXIT=$?
-
-  if [ "$GITLEAKS_EXIT" -eq 0 ]; then
-    echo "     ✅ PASSED - No secrets detected."
-    GATE_8_STATUS="PASS"
-  elif [ "$GITLEAKS_EXIT" -eq 1 ]; then
-    # Secrets found — output details
-    echo "$GITLEAKS_OUTPUT"
-    echo ""
-    echo "❌ BLOCKED - Secrets detected in staged files."
-    echo ""
-    echo "Remediation options:"
-    echo "  1. Remove the secret and use environment variables instead"
-    echo "  2. Add a false positive to .gitleaks.toml allowlist"
-    echo "  3. Use git secret or vault for sensitive data"
-    echo ""
-    echo "See: https://github.com/gitleaks/gitleaks"
-    exit 1
-  else
-    echo "     ⚠️  gitleaks exited with code $GITLEAKS_EXIT - skipping gate"
-    echo "     ✅ Secret Scanning (SKIP, gitleaks error)"
-    GATE_8_STATUS="SKIP"
-  fi
-else
-  echo "     ℹ️  gitleaks not installed — secret scanning unavailable"
-  echo "     Install: brew install gitleaks (macOS) | scripts/install-gitleaks.sh (Linux)"
-  echo "     ✅ Secret Scanning (SKIP, gitleaks not installed)"
-  GATE_8_STATUS="SKIP"
-fi
-record_gate_audit "gate-8" "secret-scanning" "$GATE_8_STATUS" "0" "$GATE_8_START"
+source "$GATE_DIR/gate-8.sh"
 
 # Switch back to original directory if we were in a subdirectory
 if [ -n "$ORIGINAL_DIR" ]; then
@@ -1797,134 +1794,42 @@ fi
 
 # ============================================================================
 # GATE 9: Semgrep SAST Security Scan
-# Detects security vulnerabilities (SQL injection, XSS, etc.) in staged files
-# Tool: semgrep -- https://semgrep.dev
+# Extracted to gate-9.sh for maintainability
+# ============================================================================
+source "$GATE_DIR/gate-9.sh"
 # ============================================================================
 
- 2>&1 echo ""
- 2>&1 echo "→ Gate 9: Semgrep SAST Security Scan..."
-GATE_9_START=$(gate_start_ms)
-
-GATE_9_STATUS="PASS"
-
-# Semgrep availability check
-SEMGREP_CMD=""
-if command -v semgrep >/dev/null 2>&1; then
-  SEMGREP_CMD="semgrep"
-elif [ -f "$HOME/.local/bin/semgrep" ]; then
-  SEMGREP_CMD="$HOME/.local/bin/semgrep"
+# ============================================================================
+# GATE 10: Sprint Flow Enforcement
+# Validates sprint state consistency (delphi-review APPROVED before BUILD)
+# Uses sprint-gate.sh for standalone validation logic
+# ============================================================================
+GATE_10_START=$(date +%s)
+GATE_10_STATUS="PASS"
+
+SPRINT_GATE_SCRIPT=""
+if [ -f "$GATE_DIR/sprint-gate.sh" ]; then
+  SPRINT_GATE_SCRIPT="$GATE_DIR/sprint-gate.sh"
+elif [ -f "$(git rev-parse --show-toplevel 2>/dev/null)/githooks/sprint-gate.sh" ]; then
+  SPRINT_GATE_SCRIPT="$(git rev-parse --show-toplevel)/githooks/sprint-gate.sh"
 fi
 
-if [ -z "$SEMGREP_CMD" ]; then
-  echo "     ⚠️  WARN - semgrep not installed — SAST scanning unavailable"
-  echo "     Install: brew install semgrep | pip install semgrep"
-  echo "     Pre-cache rules: semgrep --config=p/security-audit"
-  echo "     Gate 9: SAST Security (WARN, semgrep not installed)"
-  GATE_9_STATUS="WARN"
-else
-  # Get staged files filtered to Semgrep-supported languages
-  SEMGREP_FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null | grep -E '\.(ts|tsx|js|jsx|py|go|java|c|cpp|cs|rb|php|scala|swift)$' || true)
-
-  if [ -z "$SEMGREP_FILES" ]; then
-    echo "     ✅ PASSED - No supported language files in staged changes."
-    GATE_9_STATUS="PASS"
-  else
-    # Run semgrep with JSON output
-    # --config=p/security-audit: explicit security ruleset
-    # --json: machine-readable output
-    # --disable-version-check: skip network call
-    SEMGREP_OUTPUT=$($SEMGREP_CMD scan --config=p/security-audit --json --disable-version-check $SEMGREP_FILES 2>&1)
-    SEMGREP_EXIT=$?
-
-    if [ "$SEMGREP_EXIT" -eq 0 ]; then
-      echo "     ✅ PASSED - No security vulnerabilities found."
-      GATE_9_STATUS="PASS"
-    elif [ "$SEMGREP_EXIT" -eq 1 ]; then
-      # Findings detected - parse JSON to categorize
-      CRITICAL_HIGH=$(echo "$SEMGREP_OUTPUT" | python3 -c "
-import sys, json
-try:
-    data = json.load(sys.stdin)
-    results = data.get('results', [])
-    count = 0
-    for r in results:
-        extra = r.get('extra', {})
-        severity = extra.get('severity', '').upper()
-        if severity in ('CRITICAL', 'HIGH'):
-            count += 1
-    print(count)
-except:
-    print('0')
-" 2>/dev/null || echo "0")
-
-      MEDIUM_LOW=$(echo "$SEMGREP_OUTPUT" | python3 -c "
-import sys, json
-try:
-    data = json.load(sys.stdin)
-    results = data.get('results', [])
-    count = 0
-    for r in results:
-        extra = r.get('extra', {})
-        severity = extra.get('severity', '').upper()
-        if severity in ('MEDIUM', 'LOW'):
-            count += 1
-    print(count)
-except:
-    print('0')
-" 2>/dev/null || echo "0")
-
-      # Extract top finding details
-      FINDING_DETAILS=$(echo "$SEMGREP_OUTPUT" | python3 -c "
-import sys, json
-try:
-    data = json.load(sys.stdin)
-    results = data.get('results', [])
-    for r in results[:5]:  # Show top 5
-        extra = r.get('extra', {})
-        severity = extra.get('severity', 'UNKNOWN').upper()
-        rule_id = r.get('check_id', 'unknown')
-        path = r.get('path', 'unknown')
-        start_line = r.get('start', {}).get('line', '?')
-        message = extra.get('message', '')[:80]
-        print(f'  [{severity}] {rule_id}')
-        print(f'  {path}:{start_line} → {message}')
-        print()
-except:
-    print('  (Failed to parse semgrep output)')
-" 2>/dev/null || echo "  (Failed to parse semgrep output)")
-
-      if [ "$CRITICAL_HIGH" -gt 0 ]; then
-        echo ""
-        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-        echo "   GATE 9: Semgrep Security Gate"
-        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-        echo "  CRITICAL/HIGH: ${CRITICAL_HIGH}  ❌ BLOCKED"
-        echo "  MEDIUM/LOW:    ${MEDIUM_LOW}  ⚠️  warning"
-        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-        echo "  ❌ BLOCKED — Critical/High vulnerability found"
-        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-        echo "$FINDING_DETAILS"
-        echo "  Run 'semgrep scan --config=p/security-audit' to review all findings."
-        GATE_9_STATUS="FAIL"
-        exit 1
-      else
-        echo ""
-        echo "     ✅ PASSED - No critical/high vulnerabilities"
-        if [ "$MEDIUM_LOW" -gt 0 ]; then
-          echo "     ⚠️  ${MEDIUM_LOW} medium/low findings (warnings only)"
-          echo "$FINDING_DETAILS"
-        fi
-        GATE_9_STATUS="PASS"
-      fi
-    else
-      # semgrep runtime error (timeout, config error, etc.)
-      echo "     ⚠️  semgrep exited with code ${SEMGREP_EXIT} — skipping gate"
-      echo "     ✅ Semgrep SAST (SKIP, semgrep error)"
-      GATE_9_STATUS="SKIP"
-    fi
+if [ -n "$SPRINT_GATE_SCRIPT" ]; then
+  if ! bash "$SPRINT_GATE_SCRIPT" --pre-commit; then
+    GATE_10_STATUS="BLOCK"
+    echo "❌ BLOCKED - Gate 10: Sprint Flow Enforcement"
+    # Sprint gate failure is a hard block — exit immediately
+    exit 1
   fi
+else
+  echo "⏭️  SKIPPED - Gate 10: Sprint Flow (sprint-gate.sh not found)"
+  GATE_10_STATUS="SKIP"
 fi
-record_gate_audit "gate-9" "sast-security" "$GATE_9_STATUS" "0" "$GATE_9_START"
+
+GATE_10_END=$(date +%s)
+GATE_10_DURATION=$((GATE_10_END - GATE_10_START))
+echo "✅ Gate 10 completed in ${GATE_10_DURATION}s"
+echo ""
 # ============================================================================
 
 generate_quality_report() {
@@ -1933,13 +1838,13 @@ generate_quality_report() {
   local TIMESTAMP
   local BRANCH
   local PASSED_COUNT=0
-  local TOTAL_GATES=9
+  local TOTAL_GATES=10
 
   COMMIT_HASH=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
   BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
   TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 
-  for gate in 1 2 3 4 5 6 7 8 9; do
+  for gate in 1 2 3 4 5 6 7 8 9 10; do
     local status_var="GATE_${gate}_STATUS"
     if [ "${!status_var}" = "PASS" ]; then
       PASSED_COUNT=$((PASSED_COUNT + 1))
@@ -2042,6 +1947,11 @@ generate_quality_report() {
       "name": "SAST Security Scan",
       "status": "${GATE_9_STATUS:-PASS}",
       "tool": "semgrep"
+    },
+    "gate10_sprint_flow": {
+      "name": "Sprint Flow Enforcement",
+      "status": "${GATE_10_STATUS:-PASS}",
+      "tool": "sprint-gate.sh"
     }
   }
 }
@@ -2082,7 +1992,8 @@ PY
   GATES_JSON="${GATES_JSON}\"gate6\":{\"status\":\"${GATE_6_STATUS:-PASS}\",\"name\":\"Architecture+BoyScout\",\"bsBlocked\":${BS_BLOCKED}},"
   GATES_JSON="${GATES_JSON}\"gate7\":{\"status\":\"${GATE_7_STATUS:-PASS}\",\"name\":\"IaC Security\"},"
   GATES_JSON="${GATES_JSON}\"gate8\":{\"status\":\"${GATE_8_STATUS:-PASS}\",\"name\":\"Secret Scanning\"},"
-  GATES_JSON="${GATES_JSON}\"gate9\":{\"status\":\"${GATE_9_STATUS:-PASS}\",\"name\":\"SAST Security\"}}"
+  GATES_JSON="${GATES_JSON}\"gate9\":{\"status\":\"${GATE_9_STATUS:-PASS}\",\"name\":\"SAST Security\"},"
+  GATES_JSON="${GATES_JSON}\"gate10\":{\"status\":\"${GATE_10_STATUS:-PASS}\",\"name\":\"Sprint Flow\"}}"
   GATES_JSON="${GATES_JSON}}"
 
   echo "{\"timestamp\":\"$TIMESTAMP\",\"commit\":\"$COMMIT_HASH\",\"branch\":\"$BRANCH\",\"score\":$SCORE,\"passed\":$PASSED_COUNT,\"total\":$TOTAL_GATES,\"gates\":$GATES_JSON,\"coverage\":\"$COV_PCT\",\"complexityWarnings\":${CC_WARNINGS:-0},\"principleWarnings\":${WARNING_COUNT:-0},\"boyScoutBlocked\":${BS_BLOCKED}}" >> "$HISTORY_FILE"
@@ -2102,6 +2013,7 @@ PY
   printf "  %-45s %s\n" "Gate 7: IaC Security" "${GATE_7_STATUS:-PASS}"
   printf "  %-45s %s\n" "Gate 8: Secret Scanning" "${GATE_8_STATUS:-PASS}"
   printf "  %-45s %s\n" "Gate 9: SAST Security" "${GATE_9_STATUS:-PASS}"
+  printf "  %-45s %s\n" "Gate 10: Sprint Flow" "${GATE_10_STATUS:-PASS}"
   echo ""
   echo "  Overall Score: $SCORE/10 | $PASSED_COUNT/$TOTAL_GATES gates passed"
   echo "  Branch status: $REPORT_FILE"