@boyingliu01/xp-gate 0.18.1 → 0.18.3

package/adapters/gate-3.sh

@@ -0,0 +1,68 @@
+# ============================================================================
+# GATE 3: Cyclomatic Complexity Check
+# Uses lizard - checks cyclomatic complexity of changed source files
+# ============================================================================
+
+ 2>&1 echo ""
+ 2>&1 echo "→ Gate 3: Cyclomatic complexity..."
+GATE_3_START=$(gate_start_ms)
+
+if [ "$PROJECT_LANG" = "documentation-only" ]; then
+  echo "⏭️  SKIPPED - Complexity (documentation project)."
+  GATE_3_STATUS="SKIP"
+
+elif [ "$PROJECT_LANG" = "powershell" ]; then
+  echo "ℹ️  No PowerShell Clean Code / SOLID tool available"
+  echo "⏭️  SKIPPED - Complexity (no PowerShell tool)"
+  GATE_3_STATUS="SKIP"
+  
+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 (includes test files)
+    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)."
+        GATE_3_STATUS="PASS"
+      fi
+    else
+      echo "⏭️  SKIPPED - Complexity (no source files to check)."
+      GATE_3_STATUS="SKIP"
+    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
+record_gate_audit "gate-3" "complexity" "$GATE_3_STATUS" "${CC_WARNINGS:-0}" "$GATE_3_START"

package/adapters/gate-4.sh

@@ -0,0 +1,80 @@
+# ============================================================================
+# GATE 4: Principles Checker (Clean Code + SOLID)
+# Reuses existing principles checker logic
+# ============================================================================
+
+ 2>&1 echo ""
+ 2>&1 echo "→ Gate 4: Principles checker (Clean Code + SOLID)..."
+GATE_4_START=$(gate_start_ms)
+
+GATE_4_STATUS=""
+
+if [ "$PROJECT_LANG" = "documentation-only" ]; then
+  echo "⏭️  SKIPPED - Principles check (documentation project)."
+  GATE_4_STATUS="SKIP"
+  
+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 for principles checker in installed modules first, then project src/
+    PRINCIPLES_DIR=""
+    if [ -d ".xp-gate/modules/principles" ]; then
+      PRINCIPLES_DIR=".xp-gate/modules/principles"
+    elif [ -f "src/principles/index.ts" ]; then
+      PRINCIPLES_DIR="src/principles"
+    elif [ -d "$HOME/.config/xp-gate/modules/principles" ]; then
+      PRINCIPLES_DIR="$HOME/.config/xp-gate/modules/principles"
+    fi
+    
+    if [ -n "$PRINCIPLES_DIR" ]; 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 $PRINCIPLES_DIR/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 $PRINCIPLES_DIR/index.ts --files $PRINCIPLES_FILES --format console
+            GATE_4_STATUS="FAIL"
+            exit 1
+          fi
+          
+          echo "✅ PASSED - Principles checker (no errors found)."
+          GATE_4_STATUS="PASS"
+          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 "⏭️  SKIPPED - Principles check (execution issue)"
+          GATE_4_STATUS="SKIP"
+        fi
+      else
+        echo "ℹ️  npx not available - skipping principles check"
+        echo "⏭️  SKIPPED - Principles check (no Node.js/npx)"
+        GATE_4_STATUS="SKIP"
+      fi
+    else
+      echo "ℹ️  Principles checker not found in project - skipping"
+      echo "⏭️  SKIPPED - Principles check (checker not in project)"
+      GATE_4_STATUS="SKIP"
+    fi
+  else
+    echo "⏭️  SKIPPED - Principles check (no matching source files changed)"
+    GATE_4_STATUS="SKIP"
+  fi
+fi
+record_gate_audit "gate-4" "principles" "$GATE_4_STATUS" "${WARNING_COUNT:-0}" "$GATE_4_START"

package/adapters/gate-7.sh

@@ -0,0 +1,45 @@
+# ============================================================================
+# GATE 7: IaC Security Scanning (Terraform, Kubernetes, Docker)
+# Detects security issues in Infrastructure as Code files
+# Tools: checkov (recommended), hadolint, kube-score, tflint
+# ============================================================================
+
+ 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 "⏭️  SKIPPED - IaC security (no IaC adapter found)"
+    GATE_7_STATUS="SKIP"
+  fi
+fi
+record_gate_audit "gate-7" "iac-security" "$GATE_7_STATUS" "0" "$GATE_7_START"

package/adapters/gate-8.sh

@@ -0,0 +1,56 @@
+# ============================================================================
+# GATE 8: Secret Scanning (gitleaks)
+# Detects secrets (API keys, passwords, tokens) in staged files
+# Tool: gitleaks -- https://github.com/gitleaks/gitleaks
+# ============================================================================
+
+ 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
+  GITLEAKS_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) | winget install gitleaks (Windows) | scripts/install-gitleaks.sh (Linux)"
+  echo "     ⏭️  SKIPPED - Secret scanning (gitleaks not installed)"
+  GATE_8_STATUS="SKIP"
+fi
+record_gate_audit "gate-8" "secret-scanning" "$GATE_8_STATUS" "0" "$GATE_8_START"

package/adapters/gate-9.sh

@@ -0,0 +1,105 @@
+# ============================================================================
+# GATE 9: Semgrep SAST Security Scan
+# Detects security vulnerabilities (SQL injection, XSS, etc.) in staged files
+# Tool: semgrep -- https://semgrep.dev
+# ============================================================================
+
+ 2>&1 echo ""
+ 2>&1 echo "→ Gate 9: Semgrep SAST Security Scan..."
+GATE_9_START=$(gate_start_ms)
+
+GATE_9_STATUS=""
+
+# 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"
+fi
+
+if [ -z "$SEMGREP_CMD" ]; then
+  echo "     ⚠️  WARN - semgrep not installed — SAST scanning unavailable"
+  echo "     Install: brew install semgrep (macOS) | pip install semgrep (Linux) | pip install semgrep (Windows)"
+  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 "     ⏭️  SKIPPED - SAST (no supported language files changed)"
+    GATE_9_STATUS="SKIP"
+  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" | node -e "
+let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{
+try{const data=JSON.parse(d);const results=data.results||[];
+const count=results.filter(r=>{const s=(r.extra&&r.extra.severity||'').toUpperCase();return s==='CRITICAL'||s==='HIGH';}).length;
+console.log(count);}catch(e){console.log('0');}
+});" 2>/dev/null || echo "0")
+
+      MEDIUM_LOW=$(echo "$SEMGREP_OUTPUT" | node -e "
+let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{
+try{const data=JSON.parse(d);const results=data.results||[];
+const count=results.filter(r=>{const s=(r.extra&&r.extra.severity||'').toUpperCase();return s==='MEDIUM'||s==='LOW';}).length;
+console.log(count);}catch(e){console.log('0');}
+});" 2>/dev/null || echo "0")
+
+      # Extract top finding details
+      FINDING_DETAILS=$(echo "$SEMGREP_OUTPUT" | node -e "
+let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{
+try{const data=JSON.parse(d);const results=data.results||[];
+results.slice(0,5).forEach(r=>{const extra=r.extra||{};
+const severity=(extra.severity||'UNKNOWN').toUpperCase();
+const ruleId=r.check_id||'unknown';const path=r.path||'unknown';
+const line=(r.start&&r.start.line)||'?';const msg=(extra.message||'').slice(0,80);
+console.log('  ['+severity+'] '+ruleId);console.log('  '+path+':'+line+' → '+msg);console.log();});
+}catch(e){console.log('  (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 "     ⏭️  SKIPPED - SAST (semgrep runtime error)"
+      GATE_9_STATUS="SKIP"
+    fi
+  fi
+fi
+record_gate_audit "gate-9" "sast-security" "$GATE_9_STATUS" "0" "$GATE_9_START"
+

package/bin/xp-gate.js

@@ -28,6 +28,46 @@ function handleUIReview() {
   }
 }
 
+async function runAlignmentCheck(subargs) {
+  const specIdx = subargs.indexOf('--spec');
+  const specPath = specIdx >= 0 ? subargs[specIdx + 1] : path.join(process.cwd(), 'specification.yaml');
+
+  const testsIdx = subargs.indexOf('--tests');
+  const testDirs = testsIdx >= 0 ? [subargs[testsIdx + 1]] : undefined;
+
+  const outputIdx = subargs.indexOf('--output');
+  const outputPath = outputIdx >= 0 ? subargs[outputIdx + 1] : undefined;
+
+  const jsonMode = subargs.includes('--json');
+
+  // Load TS module via tsx
+  const { execSync } = require('child_process');
+  const alignmentPath = path.join(__dirname, '..', 'lib', 'test-alignment.ts');
+
+  try {
+    execSync(`npx tsx -e "
+      import { runFullAlignment } from '${alignmentPath}';
+      const report = runFullAlignment({
+        specPath: '${specPath}',
+        testDirs: ${JSON.stringify(testDirs || null)},
+        headCommit: require('child_process').execSync('git rev-parse HEAD 2>/dev/null || echo unknown').toString().trim(),
+        outputPath: ${outputPath ? `'${outputPath}'` : 'undefined'},
+      });
+      if (${jsonMode}) {
+        console.log(JSON.stringify(report, null, 2));
+      } else {
+        console.log('Status:', report.alignment_status);
+        console.log('Score:', report.score);
+        console.log('Misaligned:', report.misaligned_tests.length);
+      }
+      process.exit(report.alignment_status === 'PASS' ? 0 : 1);
+    "`, { stdio: 'inherit' });
+  } catch (err) {
+    return 1;
+  }
+  return 0;
+}
+
 const COMMANDS = {
   'init': {
     description: 'Initialize xp-gate (use --global for all projects)',
@@ -131,6 +171,11 @@ const COMMANDS = {
     run: subargs => arch(subargs).then(code => process.exit(code)),
     usage: 'xp-gate arch [--config <path>]'
   },
+  'check-alignment': {
+    description: 'Run test-specification alignment check (deterministic, no LLM)',
+    run: subargs => runAlignmentCheck(subargs).then(code => process.exit(code)),
+    usage: 'xp-gate check-alignment [--spec <path>] [--tests <dir>] [--json] [--output <path>]'
+  },
   'upgrade': {
     description: 'Check for xp-gate updates (--preview for JSON, --apply to upgrade)',
     run: subargs => upgrade(subargs).then(code => process.exit(code)),

package/hooks/pre-commit

@@ -1,10 +1,10 @@
 #!/bin/bash
-# OpenCode Quality Gates - Pre-Commit Hook - Refactored 6-Type-Based Gates
+# OpenCode Quality Gates - Pre-Commit Hook - 12 numbered gates (Gate 0–11)
 # 
-# DESIGN PRINCIPLE: Zero tolerance - tool unavailable = BLOCK (per CODE-OF-CONDUCT.md)
-# Each gate requires its tools to be installed; missing tools block the commit.
+# DESIGN PRINCIPLE: Tool unavailable = SKIP (graceful degradation), tool available + check fails = BLOCK
+# Missing tools do NOT block the commit — the gate degrades to SKIP. Block fires only when
+# the tool exists AND the check fails. This prevents broken toolchains from blocking work.
 #
-# Converts 9 sequential gates into 6 type-based comprehensive gates
 # Sourced from adapter-common.sh and language-specific adapters
 
 # Source the common adapter functions — 3-tier resolution:
@@ -1328,7 +1328,9 @@ source "$GATE_DIR/gate-4.sh"
 # v0.14.3+ (Issue #312): Skip test run when no code files changed.
 # Code files = src/**/*.ts, plugins/**/*.ts, *.ts, *.tsx, etc. (language-aware).
 # VERSION, CHANGELOG, docs, config-only changes → SKIP test run entirely.
-# Gate 5a (new file pairing) and Gate 5b (mock density) still run — they're lightweight.
+  # Gate 5a (new file pairing), 5b (mock density), and 5c (semantic annotation)
+  # are lightweight and still run even when no code files changed.
+  # Gate 5a (new file pairing) and Gate 5b (mock density) still run — they're lightweight.
 # ============================================================================
  2>&1 echo ""
  2>&1 echo "→ Gate 5: Tests & coverage..."
@@ -1640,6 +1642,82 @@ else
     done
   fi
 
+  # ============================================================================
+  # Gate 5c: Semantic Annotation Check (v0.19.0+)
+  # Validates @test REQ-XXX annotations against specification.yaml.
+  #
+  # Strategy: Reads pre-compiled req-ids.json (produced by xp-gate check-alignment).
+  # If req-ids.json is absent or stale, degrades to SKIP.
+  # If present: greps staged tests for @test REQ-XXX, cross-references against
+  # the pre-compiled REQ ID list. BLOCKs if any REQ ID doesn't exist in spec.
+  # If any REQ in spec has no annotated test, emits visible [FAIL] message
+  # (exit 0, appears in hook summary) — full alignment check runs at CLI time.
+  # ============================================================================
+  REQ_IDS_FILE=".sprint-state/phase-outputs/req-ids.json"
+  if [ -f "$REQ_IDS_FILE" ] && command -v jq >/dev/null 2>&1; then
+    # Check staleness: req-ids.json must be newer than specification.yaml
+    SPEC_FILE="specification.yaml"
+    REQ_IDS_STALE=false
+    if [ -f "$SPEC_FILE" ]; then
+      if [ "$REQ_IDS_FILE" -ot "$SPEC_FILE" ]; then
+        REQ_IDS_STALE=true
+      fi
+    fi
+
+    if [ "$REQ_IDS_STALE" = true ]; then
+      echo "⚠️  Gate 5c: req-ids.json is stale (specification.yaml updated since last check-alignment)"
+      echo "   Run 'xp-gate check-alignment' to regenerate before next commit."
+    else
+      CHANGED_TEST_FILES_ANNOTATED=$(echo "$CHANGED_FILES" | grep -E '\.(test|spec)\.(ts|tsx|js|jsx)$' || true)
+      if [ -n "$CHANGED_TEST_FILES_ANNOTATED" ]; then
+        echo "  → Checking @test REQ-XXX annotations..."
+        ANNOTATION_ERRORS=0
+        for tf in $CHANGED_TEST_FILES_ANNOTATED; do
+          if [ -f "$tf" ]; then
+            # Extract @test REQ-XXX annotations from staged test file (word-bounded)
+            ANNOTATED_REQS=$(grep -oE '@test\s+REQ-[A-Z0-9-]+' "$tf" 2>/dev/null | sed 's/@test\s*//' | sort -u || true)
+            for req_id in $ANNOTATED_REQS; do
+              # Cross-reference against pre-compiled REQ ID list
+              FOUND=$(jq -r --arg rid "$req_id" '.[] | select(. == $rid)' "$REQ_IDS_FILE" 2>/dev/null || true)
+              if [ -z "$FOUND" ]; then
+                echo "❌ Gate 5c: $tf — @test $req_id: REQ ID not found in specification.yaml"
+                ANNOTATION_ERRORS=$((ANNOTATION_ERRORS + 1))
+              fi
+            done
+          fi
+        done
+
+        if [ "$ANNOTATION_ERRORS" -gt 0 ]; then
+          echo ""
+          echo "❌ $ANNOTATION_ERRORS test annotation(s) reference non-existent REQ IDs — commit BLOCKED"
+          echo "   Fix: Verify REQ IDs against specification.yaml, or run 'xp-gate check-alignment'"
+          exit 1
+        fi
+
+        # Check reverse: any REQ in spec with no annotated test → visible FAIL (non-blocking)
+        ALL_SPEC_REQS=$(jq -r '.[]' "$REQ_IDS_FILE" 2>/dev/null)
+        ANNOTATED_ALL=""
+        for tf in $(echo "$CHANGED_FILES" | grep -E '\.(test|spec)\.(ts|tsx|js|jsx)$' || true); do
+          if [ -f "$tf" ]; then
+            ANNOTATED_ALL="$ANNOTATED_ALL $(grep -oE '@test\s+REQ-[A-Z0-9-]+' "$tf" 2>/dev/null | sed 's/@test\s*//' || true)"
+          fi
+        done
+        UNTESTED_COUNT=0
+        for spec_req in $ALL_SPEC_REQS; do
+          if ! echo "$ANNOTATED_ALL" | grep -qF "$spec_req"; then
+            UNTESTED_COUNT=$((UNTESTED_COUNT + 1))
+          fi
+        done
+        if [ "$UNTESTED_COUNT" -gt 0 ]; then
+          echo "⚠️  [FAIL] Gate 5c: $UNTESTED_COUNT REQ(s) in specification.yaml have no annotated tests"
+          echo "   This is non-blocking. Run 'xp-gate check-alignment' for full alignment report."
+        fi
+
+        echo "  ✅ @test annotation check complete."
+      fi
+    fi
+  fi
+
   # ============================================================================
   # v0.14.3+ (Issue #312): Early skip when no code files changed.
   # If the commit only touches VERSION, CHANGELOG, docs, config, .gitignore,
@@ -2439,13 +2517,13 @@ generate_quality_report() {
   local TIMESTAMP
   local BRANCH
   local PASSED_COUNT=0
-  local TOTAL_GATES=11
+  local TOTAL_GATES=12
 
   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 10 11; do
+  for gate in 1 2 3 4 5 6 7 8 9 10 11 12; do
     local status_var="GATE_${gate}_STATUS"
     if [ "${!status_var}" = "PASS" ]; then
       PASSED_COUNT=$((PASSED_COUNT + 1))
@@ -2558,6 +2636,11 @@ generate_quality_report() {
       "name": "Sprint Flow Enforcement",
       "status": "${GATE_11_STATUS:-PASS}",
       "tool": "sprint-gate.sh"
+    },
+    "gate12_file_hygiene": {
+      "name": "File Hygiene Check",
+      "status": "${GATE_12_STATUS:-WARN}",
+      "tool": "gate-12-file-hygiene.sh"
     }
   }
 }
@@ -2583,8 +2666,8 @@ ENDJSON
   GATES_JSON="${GATES_JSON}\"gate8\":{\"status\":\"${GATE_8_STATUS:-PASS}\",\"name\":\"Secret Scanning\"},"
   GATES_JSON="${GATES_JSON}\"gate9\":{\"status\":\"${GATE_9_STATUS:-PASS}\",\"name\":\"Build Integrity\"},"
   GATES_JSON="${GATES_JSON}\"gate10\":{\"status\":\"${GATE_10_STATUS:-PASS}\",\"name\":\"SAST Security\"},"
-  GATES_JSON="${GATES_JSON}\"gate11\":{\"status\":\"${GATE_11_STATUS:-PASS}\",\"name\":\"Sprint Flow\"}}"
-  GATES_JSON="${GATES_JSON}}"
+  GATES_JSON="${GATES_JSON}\"gate11\":{\"status\":\"${GATE_11_STATUS:-PASS}\",\"name\":\"Sprint Flow\"},"
+  GATES_JSON="${GATES_JSON}\"gate12\":{\"status\":\"${GATE_12_STATUS:-WARN}\",\"name\":\"File Hygiene\"}}"
 
   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"
 
@@ -2605,6 +2688,7 @@ ENDJSON
   printf "  %-45s %s\n" "Gate 9: Build Integrity" "${GATE_9_STATUS:-PASS}"
   printf "  %-45s %s\n" "Gate 10: SAST Security" "${GATE_10_STATUS:-PASS}"
   printf "  %-45s %s\n" "Gate 11: Sprint Flow" "${GATE_11_STATUS:-PASS}"
+  printf "  %-45s %s\n" "Gate 12: File Hygiene" "${GATE_12_STATUS:-WARN}"
   echo ""
   echo "  Overall Score: $SCORE/10 | $PASSED_COUNT/$TOTAL_GATES gates passed"
   echo "  Branch status: $REPORT_FILE"
@@ -2612,8 +2696,23 @@ ENDJSON
   echo "  History saved: $HISTORY_FILE"
   echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
   echo ""
+  # AI-friendly common footer: tells LLM agents how to fix issues instead of bypassing
+  echo "  ── AI AGENT DIRECTIVE ──"
+  echo "  If any gate FAILED above:"
+  echo "    - Each error includes a file path and rule identifier"
+  echo "    - Fix each issue, then re-run: git commit"
+  echo "    - Do NOT use --no-verify — bypassed commits block sprint progression"
+  echo "  ─────────────────────────"
+  echo ""
 }
 
+# Post-commit bypass marker: write a sentinel file in .git/ directory
+# that the post-commit hook checks to detect --no-verify bypasses
+_wp_marker="$(git rev-parse --git-dir 2>/dev/null)/xp-gate-precommit-marker"
+if [ -n "$_wp_marker" ] && [ "$_wp_marker" != "/xp-gate-precommit-marker" ]; then
+  echo "$(date +%s)" > "$_wp_marker"
+fi
+
 generate_quality_report
 
 exit 0