fraim-framework 2.0.26 → 2.0.30

package/registry/scripts/code-quality-check.sh

@@ -1,559 +1,559 @@
-#!/bin/bash
-# Unified code quality check script
-# Can be run at different stages: pre-commit, pre-pr, or ci
-# Usage: bash code-quality-check.sh [pre-commit|pre-pr|ci]
-
-MODE="${1:-pre-pr}"  # Default to pre-pr if not specified
-
-set -e
-
-echo "🔍 Running code quality checks (mode: $MODE)..."
-echo ""
-
-FAILED=0
-WARNINGS=0
-
-# Determine what files to check based on mode
-if [ "$MODE" = "pre-commit" ]; then
-  # Pre-commit: only check staged files
-  TS_FILES=$(git diff --cached --name-only | grep -E '\.(ts|tsx)$' || true)
-  CHECK_SCOPE="staged files"
-elif [ "$MODE" = "ci" ]; then
-  # CI: check only files changed in this PR
-  # Compare against the base branch (e.g., master or feature/*)
-  BASE_BRANCH="${GITHUB_BASE_REF:-origin/master}"
-  echo "ℹ️  Comparing against base: $BASE_BRANCH"
-  
-  # Get all changed TypeScript files in the PR
-  TS_FILES=$(git diff --name-only $BASE_BRANCH...HEAD | grep -E '\.(ts|tsx)$' || true)
-  
-  if [ -z "$TS_FILES" ]; then
-    echo "ℹ️  No TypeScript files changed in this PR"
-    CHECK_SCOPE="no files changed"
-  else
-    FILE_COUNT=$(echo "$TS_FILES" | wc -l | tr -d ' ')
-    CHECK_SCOPE="$FILE_COUNT changed file(s) in PR"
-  fi
-elif [ "$MODE" = "pre-pr" ]; then
-  # Pre-PR: check entire src directory (local development)
-  TS_FILES=$(find src -name "*.ts" -o -name "*.tsx" 2>/dev/null || true)
-  CHECK_SCOPE="entire codebase"
-fi
-# Load configuration from .fraim/config.json
-CONFIG_FILE=".fraim/config.json"
-if [ -f "$CONFIG_FILE" ]; then
-  # Extract OpenAPI path using node
-  OPENAPI_PATH=$(node -e "const fs = require('fs'); try { const config = JSON.parse(fs.readFileSync('$CONFIG_FILE', 'utf-8')); console.log(config.paths?.openapi || 'src/openapi/OpenAPI.json'); } catch(e) { console.log('src/openapi/OpenAPI.json'); }")
-  ARCH_DOC=$(node -e "const fs = require('fs'); try { const config = JSON.parse(fs.readFileSync('$CONFIG_FILE', 'utf-8')); console.log('.ai-agents/rules/' + (config.persona?.name?.toLowerCase() || 'persona') + '-architecture.md'); } catch(e) { console.log('.ai-agents/rules/persona-architecture.md'); }")
-else
-  OPENAPI_PATH="src/openapi/OpenAPI.json"
-  ARCH_DOC=".ai-agents/rules/persona-architecture.md"
-fi
-
-echo "Checking: $CHECK_SCOPE"
-echo ""
-
-# GATE 1: Check for 'as any' type bypassing
-echo "================================================"
-echo "📋 GATE 1: No 'as any' Type Bypassing"
-echo "================================================"
-
-if [ -z "$TS_FILES" ]; then
-  echo "ℹ️  No TypeScript files to check"
-else
-  if echo "$TS_FILES" | xargs grep -n ' as any' 2>/dev/null; then
-    echo ""
-    echo "❌ FAILED: Found 'as any' type assertions"
-    echo "   Rule: Use proper TypeScript interfaces, not 'as any'"
-    echo "   See: .ai-agents/rules/code-quality-and-debugging-patterns.md#rule-1"
-    FAILED=1
-  else
-    echo "✅ PASSED: No 'as any' type bypassing found"
-  fi
-fi
-echo ""
-
-# GATE 1.5: Tautological Tests Check
-echo "================================================"
-echo "📋 GATE 1.5: No Tautological Test Patterns"
-echo "================================================"
-
-if bash "$(dirname "$0")/detect-tautological-tests.sh"; then
-    echo "✅ PASSED: No tautological tests found"
-else
-    echo "❌ FAILED: Tautological test patterns detected"
-    echo "   Rule: Tests must fail if product code is removed. Don't test types/constants."
-    echo "   See: .ai-agents/rules/integrity-and-test-ethics.md#critical-invalid-test-patterns-tautology-type-testing"
-    FAILED=1
-fi
-echo ""
-
-
-# GATE 2: TypeScript Compilation
-echo "================================================"
-echo "📋 GATE 2: TypeScript Compilation"
-echo "================================================"
-
-if command -v npx &> /dev/null; then
-  if npx tsc --noEmit --skipLibCheck 2>&1 | head -50; then
-    echo "✅ PASSED: TypeScript compilation successful"
-  else
-    echo "❌ FAILED: TypeScript compilation errors"
-    echo "   Fix all TypeScript errors before proceeding"
-    FAILED=1
-  fi
-else
-  echo "ℹ️  npx not found - skipping TypeScript check"
-fi
-echo ""
-
-# GATE 3: Linter
-echo "================================================"
-echo "📋 GATE 3: Linter (ESLint)"
-echo "================================================"
-
-if command -v npm &> /dev/null; then
-  if npm run lint 2>&1 | head -50; then
-    echo "✅ PASSED: Linter checks passed"
-  else
-    echo "⚠️  WARNING: Linter has issues"
-    WARNINGS=1
-  fi
-else
-  echo "ℹ️  npm not found - skipping lint check"
-fi
-echo ""
-
-# GATE 4: Git Status (pre-pr and ci only)
-if [ "$MODE" != "pre-commit" ]; then
-  echo "================================================"
-  echo "📋 GATE 4: Git Status"
-  echo "================================================"
-
-  if [ -n "$(git status --porcelain)" ]; then
-    echo "⚠️  WARNING: Uncommitted changes detected"
-    git status --short
-    WARNINGS=1
-  else
-    echo "✅ PASSED: Working directory is clean"
-  fi
-  echo ""
-fi
-
-# GATE 5: Commits Pushed (pre-pr only)
-if [ "$MODE" = "pre-pr" ]; then
-  echo "================================================"
-  echo "📋 GATE 5: Commits Pushed to Remote"
-  echo "================================================"
-
-  CURRENT_BRANCH=$(git branch --show-current)
-  if git log origin/$CURRENT_BRANCH..$CURRENT_BRANCH --oneline 2>/dev/null | grep . > /dev/null; then
-    echo "⚠️  WARNING: Unpushed commits detected"
-    git log origin/$CURRENT_BRANCH..$CURRENT_BRANCH --oneline
-    WARNINGS=1
-  else
-    echo "✅ PASSED: All commits pushed to remote"
-  fi
-  echo ""
-fi
-
-# GATE 6: PR Comments Addressed (pre-pr only)
-if [ "$MODE" = "pre-pr" ]; then
-  echo "================================================"
-  echo "📋 GATE 6: PR Comments Addressed"
-  echo "================================================"
-
-  # Check if gh CLI is available
-  if ! command -v gh &> /dev/null; then
-    echo "ℹ️  gh CLI not found - skipping PR comment check"
-    echo ""
-  else
-    # Try to get PR number for current branch
-    PR_NUMBER=$(gh pr view --json number --jq '.number' 2>/dev/null || echo "")
-
-    if [ -z "$PR_NUMBER" ]; then
-      echo "ℹ️  No PR found for current branch - skipping comment check"
-    else
-      echo "Found PR #$PR_NUMBER"
-
-      # Get PR comments count
-      COMMENT_COUNT=$(gh api repos/:owner/:repo/pulls/$PR_NUMBER/comments --jq 'length' 2>/dev/null || echo "0")
-
-      if [ "$COMMENT_COUNT" -gt 0 ]; then
-        echo "⚠️  WARNING: PR has $COMMENT_COUNT review comments"
-        echo "   Please ensure all comments are addressed before marking ready for review"
-        echo ""
-        echo "   To view comments:"
-        echo "   gh pr view $PR_NUMBER --comments"
-        echo ""
-        echo "   To reply to a comment:"
-        echo "   gh api repos/:owner/:repo/pulls/comments/{comment_id}/replies -X POST -f body='your response'"
-        WARNINGS=1
-      else
-        echo "✅ PASSED: No outstanding PR comments"
-      fi
-    fi
-  fi
-  echo ""
-fi
-
-# GATE 7: Build Evidence Verification (pre-pr only)
-if [ "$MODE" = "pre-pr" ]; then
-  echo "================================================"
-  echo "📋 GATE 7: Build Evidence Verification"
-  echo "================================================"
-
-  # Check if build has been run (look for build output or recent dist/ directory)
-  BUILD_EVIDENCE_FOUND=0
-  
-  # Method 1: Check if dist/ directory exists and has recent files
-  if [ -d "dist" ]; then
-    # Check if dist has files modified in last 2 hours
-    if find dist -type f -newermt "2 hours ago" 2>/dev/null | grep -q .; then
-      BUILD_EVIDENCE_FOUND=1
-      echo "✅ Found: Recent files in dist/ directory"
-    fi
-  fi
-  
-  # Method 2: Check for build logs
-  if [ -f "server.log" ] && tail -50 server.log 2>/dev/null | grep -qiE "(Build.*success|Compiled successfully|build.*complete)"; then
-    BUILD_EVIDENCE_FOUND=1
-    echo "✅ Found: Build success in server.log"
-  fi
-  
-  # Method 3: Check if TypeScript compilation succeeds now
-  if command -v npx &> /dev/null; then
-    if npx tsc --noEmit --skipLibCheck > /dev/null 2>&1; then
-      BUILD_EVIDENCE_FOUND=1
-      echo "✅ Found: TypeScript compilation succeeds (runtime check)"
-    fi
-  fi
-  
-  if [ $BUILD_EVIDENCE_FOUND -eq 0 ]; then
-    echo "❌ FAILED: No build evidence found"
-    echo "   Required: Run 'npm run build' and verify it succeeds before marking PR ready"
-    echo "   Evidence can be: dist/ files, build logs, or successful compilation"
-    FAILED=1
-  else
-    echo "✅ PASSED: Build evidence verified"
-  fi
-  echo ""
-fi
-
-# GATE 8: Test Execution Verification (pre-pr only)
-if [ "$MODE" = "pre-pr" ]; then
-  echo "================================================"
-  echo "📋 GATE 8: Test Execution Verification"
-  echo "================================================"
-
-  # Check if test files were created in this PR/branch
-  NEW_TEST_FILES=$(find . -name "test-*.ts" -newer .git/HEAD 2>/dev/null | grep -v node_modules | head -10 || true)
-
-  if [ -n "$NEW_TEST_FILES" ]; then
-    echo "⚠️  WARNING: New test files detected:"
-    echo "$NEW_TEST_FILES" | sed 's/^/   - /'
-    echo "   Rule: All new test files must be executed before submitting evidence"
-    echo "   Check: Verify test execution results are included in PR evidence"
-    WARNINGS=1
-  else
-    echo "✅ PASSED: No new test files detected (or tests were executed)"
-  fi
-  
-  # Check evidence files for "pending" automated validations
-  EVIDENCE_FILES=$(find . -name "implementation-evidence-*.md" -o -name "*evidence*.md" 2>/dev/null | head -5 || true)
-  if [ -n "$EVIDENCE_FILES" ]; then
-    PENDING_AUTO=$(grep -l "pending.*automated\|pending.*test\|manual validation.*pending" $EVIDENCE_FILES 2>/dev/null | head -3 || true)
-    if [ -n "$PENDING_AUTO" ]; then
-      echo "⚠️  WARNING: Evidence files mention 'pending' automated validations:"
-      echo "$PENDING_AUTO" | sed 's/^/   - /'
-      echo "   Rule: Cannot mark automated validations as 'pending' without attempting them first"
-      echo "   Check: Verify all test files have been executed before submitting evidence"
-      WARNINGS=1
-    fi
-  fi
-  echo ""
-fi
-
-# GATE 9: Test Evidence Verification (pre-pr only)
-if [ "$MODE" = "pre-pr" ]; then
-  echo "================================================"
-  echo "📋 GATE 9: Test Evidence Verification"
-  echo "================================================"
-
-  TEST_EVIDENCE_FOUND=0
-  
-  # Method 1: Check PR comments for test evidence
-  if command -v gh &> /dev/null; then
-    PR_NUMBER=$(gh pr view --json number --jq '.number' 2>/dev/null || echo "")
-    if [ -n "$PR_NUMBER" ]; then
-      # Search PR comments for test evidence keywords
-      if gh api repos/:owner/:repo/pulls/$PR_NUMBER/comments --jq '.[].body' 2>/dev/null | grep -qiE "(test.*pass|test.*evidence|test.*result|exit code.*0|✅.*test)" 2>/dev/null; then
-        TEST_EVIDENCE_FOUND=1
-        echo "✅ Found: Test evidence in PR comments"
-      fi
-    fi
-  fi
-  
-  # Method 2: Check for test log files with pass indicators
-  if [ -f "test.log" ] && grep -qE "(pass|PASS|✅|exit code.*0)" test.log 2>/dev/null; then
-    TEST_EVIDENCE_FOUND=1
-    echo "✅ Found: Test evidence in test.log"
-  fi
-  
-  # Method 3: Check for npm test exit codes (if test.log exists and shows recent runs)
-  # Note: We don't run tests here (too slow), just check for evidence of recent test runs
-  if [ -f "test.log" ] && [ -n "$(find test.log -mmin -60 2>/dev/null)" ]; then
-    # If test.log was modified in last hour, assume tests were run
-    if grep -qE "(pass|PASS|✅)" test.log 2>/dev/null; then
-      TEST_EVIDENCE_FOUND=1
-      echo "✅ Found: Recent test run in test.log"
-    fi
-  fi
-  
-  if [ $TEST_EVIDENCE_FOUND -eq 0 ]; then
-    echo "❌ FAILED: No test evidence found"
-    echo "   Required: Provide test evidence before marking PR ready"
-    echo "   Evidence can be: PR comment with test results, test.log file, or passing test run"
-    echo "   Evidence must include exit codes and test names"
-    FAILED=1
-  else
-    echo "✅ PASSED: Test evidence verified"
-  fi
-  echo ""
-fi
-
-# GATE 11: Issue Label Verification (pre-pr only)
-if [ "$MODE" = "pre-pr" ]; then
-  echo "================================================"
-  echo "📋 GATE 10: Issue Label Verification"
-  echo "================================================"
-
-  if ! command -v gh &> /dev/null; then
-    echo "ℹ️  gh CLI not found - skipping issue label check"
-    echo ""
-  else
-    # Extract issue number from branch name
-    CURRENT_BRANCH=$(git branch --show-current)
-    ISSUE_NUMBER=$(echo "$CURRENT_BRANCH" | sed -n 's/feature\/\([0-9]\+\).*/\1/p')
-    
-    if [ -z "$ISSUE_NUMBER" ]; then
-      echo "⚠️  WARNING: Could not extract issue number from branch: $CURRENT_BRANCH"
-      echo "   Expected format: feature/533-slug"
-      echo "   Skipping label verification"
-    else
-      echo "Checking labels for issue #$ISSUE_NUMBER"
-      
-      # Get issue labels
-      LABELS=$(gh api repos/:owner/:repo/issues/$ISSUE_NUMBER --jq '.labels[].name' 2>/dev/null || echo "")
-      
-      if [ -z "$LABELS" ]; then
-        echo "❌ FAILED: Could not fetch issue labels"
-        echo "   Check that issue #$ISSUE_NUMBER exists and is accessible"
-        FAILED=1
-      else
-        # Check for phase label
-        HAS_PHASE_LABEL=false
-        PHASE_LABEL=""
-        while IFS= read -r label; do
-          case "$label" in
-            phase:spec|phase:design|phase:impl|phase:tests)
-              HAS_PHASE_LABEL=true
-              PHASE_LABEL="$label"
-              break
-              ;;
-          esac
-        done <<< "$LABELS"
-        
-        # Check status labels
-        HAS_STATUS_WIP=false
-        HAS_STATUS_NEEDS_REVIEW=false
-        while IFS= read -r label; do
-          case "$label" in
-            status:wip)
-              HAS_STATUS_WIP=true
-              ;;
-            status:needs-review)
-              HAS_STATUS_NEEDS_REVIEW=true
-              ;;
-          esac
-        done <<< "$LABELS"
-        
-        # Validation
-        if [ "$HAS_PHASE_LABEL" = false ]; then
-          echo "❌ FAILED: Issue missing phase label"
-          echo "   Required: phase:spec, phase:design, phase:impl, or phase:tests"
-          echo "   Current labels: $LABELS"
-          FAILED=1
-        elif [ "$HAS_STATUS_NEEDS_REVIEW" = true ] && [ "$HAS_STATUS_WIP" = true ]; then
-          echo "❌ FAILED: Issue has both status:wip and status:needs-review"
-          echo "   Remove status:wip before marking ready for review"
-          echo "   Current labels: $LABELS"
-          FAILED=1
-        else
-          echo "✅ PASSED: Issue labels correct"
-          echo "   Phase: $PHASE_LABEL"
-          if [ "$HAS_STATUS_NEEDS_REVIEW" = true ]; then
-            echo "   Status: status:needs-review"
-          elif [ "$HAS_STATUS_WIP" = true ]; then
-            echo "   Status: status:wip"
-          else
-            echo "   Status: (none)"
-          fi
-        fi
-      fi
-    fi
-  fi
-  echo ""
-fi
-
-# GATE 10: Validation Plan Coverage (pre-pr only)
-if [ "$MODE" = "pre-pr" ]; then
-  echo "================================================"
-  echo "📋 GATE 9: Test Coverage Alignment"
-  echo "================================================"
-
-  # Extract issue number from branch
-  CURRENT_BRANCH=$(git branch --show-current)
-  ISSUE_NUMBER=$(echo "$CURRENT_BRANCH" | sed -n 's/feature\/\([0-9]\+\).*/\1/p')
-  
-  if [ -z "$ISSUE_NUMBER" ]; then
-    echo "ℹ️  Could not extract issue number from branch - skipping validation plan check"
-  elif command -v npx &> /dev/null; then
-    # Run validation coverage checker
-    COVERAGE_OUTPUT=$(GIT_BRANCH="$CURRENT_BRANCH" npx tsx "$(dirname "$0")/validate-test-coverage.ts" "$ISSUE_NUMBER" 2>&1)
-    COVERAGE_EXIT=$?
-    
-    echo "$COVERAGE_OUTPUT"
-    
-    if [ $COVERAGE_EXIT -eq 1 ]; then
-      # Coverage incomplete
-      FAILED=1
-    elif echo "$COVERAGE_OUTPUT" | grep -qi "skipped\|no.*validation plan\|no spec"; then
-      # No spec/design or no validation plan - Gate 9 warns but doesn't block
-      echo "⚠️  WARNING: Validation plan check skipped (no spec/design or no validation plan)"
-      echo "   This is acceptable, but consider adding validation plan to spec/design for future issues"
-      WARNINGS=1
-    fi
-  else
-    echo "ℹ️  npx not available - skipping validation plan coverage check"
-    echo "   Install: npm (Node.js package manager)"
-  fi
-  echo ""
-fi
-
-# GATE 12: ChatGPT Length Limits (pre-pr only)
-if [ "$MODE" = "pre-pr" ]; then
-  echo "================================================"
-  echo "📋 GATE 11: ChatGPT Length Limits"
-  echo "================================================"
-
-  CHATGPT_LIMITS_FAILED=0
-
-  # Check instructions.txt length (8,000 char limit)
-  if [ -f "src/openapi/instructions.txt" ]; then
-    if command -v python &> /dev/null || command -v python3 &> /dev/null; then
-      PYTHON_CMD=$(command -v python3 2>/dev/null || command -v python 2>/dev/null)
-      INST_LENGTH=$($PYTHON_CMD -c "f = open('src/openapi/instructions.txt', 'r', encoding='utf-8'); content = f.read(); f.close(); print(len(content))" 2>/dev/null || echo "0")
-      
-      if [ "$INST_LENGTH" -gt 8000 ]; then
-        echo "❌ FAILED: instructions.txt exceeds 8,000 character limit"
-        echo "   Current length: $INST_LENGTH characters"
-        echo "   Limit: 8,000 characters"
-        echo "   Solution: Move detailed content to KB files (KB-*.txt) and reference them"
-        echo "   See: $ARCH_DOC#chatgpt-length-limitations"
-        CHATGPT_LIMITS_FAILED=1
-      else
-        echo "✅ PASSED: instructions.txt length ($INST_LENGTH chars) within limit (8,000)"
-      fi
-    else
-      echo "ℹ️  python not found - skipping instructions.txt length check"
-    fi
-  fi
-
-  # Check OpenAPI operation description lengths (300 char limit)
-  if [ -f "$OPENAPI_PATH" ]; then
-    if command -v python &> /dev/null || command -v python3 &> /dev/null; then
-      PYTHON_CMD=$(command -v python3 2>/dev/null || command -v python 2>/dev/null)
-      LONG_DESCS=$($PYTHON_CMD -c "
-import json
-try:
-    f = open('$OPENAPI_PATH', 'r', encoding='utf-8')
-    spec = json.load(f)
-    f.close()
-    violations = []
-    for path, methods in spec.get('paths', {}).items():
-        for method, details in methods.items():
-            if isinstance(details, dict) and 'description' in details:
-                desc = details['description']
-                if len(desc) > 300:
-                    violations.append(f'{path} {method.upper()}: {len(desc)} chars')
-    if violations:
-        print('\n'.join(violations))
-    else:
-        print('OK')
-except Exception as e:
-    print(f'ERROR: {e}')
-" 2>/dev/null || echo "ERROR")
-
-      if [ "$LONG_DESCS" != "OK" ] && [ -n "$LONG_DESCS" ] && [ "$LONG_DESCS" != "ERROR" ]; then
-        echo "❌ FAILED: OpenAPI operation descriptions exceed 300 character limit"
-        echo "$LONG_DESCS" | while IFS= read -r line; do
-          echo "   $line"
-        done
-        echo "   Solution: Shorten descriptions, move details to KB files, reference KB files"
-        echo "   See: $ARCH_DOC#chatgpt-length-limitations"
-        CHATGPT_LIMITS_FAILED=1
-      elif [ "$LONG_DESCS" = "ERROR" ]; then
-        echo "⚠️  WARNING: Could not validate OpenAPI description lengths (JSON parsing error)"
-        WARNINGS=1
-      else
-        echo "✅ PASSED: All OpenAPI operation descriptions within limit (300 chars)"
-      fi
-    else
-      echo "ℹ️  python not found - skipping OpenAPI description length check"
-    fi
-  fi
-
-  if [ $CHATGPT_LIMITS_FAILED -eq 1 ]; then
-    FAILED=1
-  fi
-  echo ""
-fi
-
-# Summary
-echo "================================================"
-echo "📊 QUALITY CHECK SUMMARY ($MODE mode)"
-echo "================================================"
-echo ""
-
-if [ $FAILED -eq 1 ]; then
-  echo "❌ CHECKS FAILED"
-  echo ""
-  echo "Critical issues found. Cannot proceed."
-  echo "See .ai-agents/rules/code-quality-and-debugging-patterns.md"
-  exit 1
-elif [ $WARNINGS -gt 0 ]; then
-  echo "⚠️  CHECKS PASSED WITH WARNINGS"
-  echo ""
-  echo "Some warnings found. Consider addressing before proceeding."
-
-  if [ "$MODE" = "pre-commit" ]; then
-    echo "You can still commit, but consider fixing warnings."
-    exit 0
-  else
-    exit 0
-  fi
-else
-  echo "✅ ALL CHECKS PASSED"
-  echo ""
-
-  if [ "$MODE" = "pre-commit" ]; then
-    echo "Ready to commit!"
-  elif [ "$MODE" = "pre-pr" ]; then
-    echo "Ready to create PR!"
-    echo "Run: gh pr create --title \"your title\" --body \"your description\""
-  else
-    echo "CI checks complete!"
-  fi
-  exit 0
-fi
+#!/bin/bash
+# Unified code quality check script
+# Can be run at different stages: pre-commit, pre-pr, or ci
+# Usage: bash code-quality-check.sh [pre-commit|pre-pr|ci]
+
+MODE="${1:-pre-pr}"  # Default to pre-pr if not specified
+
+set -e
+
+echo "🔍 Running code quality checks (mode: $MODE)..."
+echo ""
+
+FAILED=0
+WARNINGS=0
+
+# Determine what files to check based on mode
+if [ "$MODE" = "pre-commit" ]; then
+  # Pre-commit: only check staged files
+  TS_FILES=$(git diff --cached --name-only | grep -E '\.(ts|tsx)$' || true)
+  CHECK_SCOPE="staged files"
+elif [ "$MODE" = "ci" ]; then
+  # CI: check only files changed in this PR
+  # Compare against the base branch (e.g., master or feature/*)
+  BASE_BRANCH="${GITHUB_BASE_REF:-origin/master}"
+  echo "ℹ️  Comparing against base: $BASE_BRANCH"
+  
+  # Get all changed TypeScript files in the PR
+  TS_FILES=$(git diff --name-only $BASE_BRANCH...HEAD | grep -E '\.(ts|tsx)$' || true)
+  
+  if [ -z "$TS_FILES" ]; then
+    echo "ℹ️  No TypeScript files changed in this PR"
+    CHECK_SCOPE="no files changed"
+  else
+    FILE_COUNT=$(echo "$TS_FILES" | wc -l | tr -d ' ')
+    CHECK_SCOPE="$FILE_COUNT changed file(s) in PR"
+  fi
+elif [ "$MODE" = "pre-pr" ]; then
+  # Pre-PR: check entire src directory (local development)
+  TS_FILES=$(find src -name "*.ts" -o -name "*.tsx" 2>/dev/null || true)
+  CHECK_SCOPE="entire codebase"
+fi
+# Load configuration from config.json
+CONFIG_FILE=".fraim/config.json"
+if [ -f "$CONFIG_FILE" ]; then
+  # Extract OpenAPI path using node
+  OPENAPI_PATH=$(node -e "const fs = require('fs'); try { const config = JSON.parse(fs.readFileSync('$CONFIG_FILE', 'utf-8')); console.log(config.paths?.openapi || 'src/openapi/OpenAPI.json'); } catch(e) { console.log('src/openapi/OpenAPI.json'); }")
+  ARCH_DOC=$(node -e "const fs = require('fs'); try { const config = JSON.parse(fs.readFileSync('$CONFIG_FILE', 'utf-8')); console.log('rules/' + (config.persona?.name?.toLowerCase() || 'persona') + '-architecture.md'); } catch(e) { console.log('rules/persona-architecture.md'); }")
+else
+  OPENAPI_PATH="src/openapi/OpenAPI.json"
+  ARCH_DOC="rules/persona-architecture.md"
+fi
+
+echo "Checking: $CHECK_SCOPE"
+echo ""
+
+# GATE 1: Check for 'as any' type bypassing
+echo "================================================"
+echo "📋 GATE 1: No 'as any' Type Bypassing"
+echo "================================================"
+
+if [ -z "$TS_FILES" ]; then
+  echo "ℹ️  No TypeScript files to check"
+else
+  if echo "$TS_FILES" | xargs grep -n ' as any' 2>/dev/null; then
+    echo ""
+    echo "❌ FAILED: Found 'as any' type assertions"
+    echo "   Rule: Use proper TypeScript interfaces, not 'as any'"
+    echo "   See: rules/code-quality-and-debugging-patterns.md#rule-1"
+    FAILED=1
+  else
+    echo "✅ PASSED: No 'as any' type bypassing found"
+  fi
+fi
+echo ""
+
+# GATE 1.5: Tautological Tests Check
+echo "================================================"
+echo "📋 GATE 1.5: No Tautological Test Patterns"
+echo "================================================"
+
+if bash "$(dirname "$0")/detect-tautological-tests.sh"; then
+    echo "✅ PASSED: No tautological tests found"
+else
+    echo "❌ FAILED: Tautological test patterns detected"
+    echo "   Rule: Tests must fail if product code is removed. Don't test types/constants."
+    echo "   See: rules/integrity-and-test-ethics.md#critical-invalid-test-patterns-tautology-type-testing"
+    FAILED=1
+fi
+echo ""
+
+
+# GATE 2: TypeScript Compilation
+echo "================================================"
+echo "📋 GATE 2: TypeScript Compilation"
+echo "================================================"
+
+if command -v npx &> /dev/null; then
+  if npx tsc --noEmit --skipLibCheck 2>&1 | head -50; then
+    echo "✅ PASSED: TypeScript compilation successful"
+  else
+    echo "❌ FAILED: TypeScript compilation errors"
+    echo "   Fix all TypeScript errors before proceeding"
+    FAILED=1
+  fi
+else
+  echo "ℹ️  npx not found - skipping TypeScript check"
+fi
+echo ""
+
+# GATE 3: Linter
+echo "================================================"
+echo "📋 GATE 3: Linter (ESLint)"
+echo "================================================"
+
+if command -v npm &> /dev/null; then
+  if npm run lint 2>&1 | head -50; then
+    echo "✅ PASSED: Linter checks passed"
+  else
+    echo "⚠️  WARNING: Linter has issues"
+    WARNINGS=1
+  fi
+else
+  echo "ℹ️  npm not found - skipping lint check"
+fi
+echo ""
+
+# GATE 4: Git Status (pre-pr and ci only)
+if [ "$MODE" != "pre-commit" ]; then
+  echo "================================================"
+  echo "📋 GATE 4: Git Status"
+  echo "================================================"
+
+  if [ -n "$(git status --porcelain)" ]; then
+    echo "⚠️  WARNING: Uncommitted changes detected"
+    git status --short
+    WARNINGS=1
+  else
+    echo "✅ PASSED: Working directory is clean"
+  fi
+  echo ""
+fi
+
+# GATE 5: Commits Pushed (pre-pr only)
+if [ "$MODE" = "pre-pr" ]; then
+  echo "================================================"
+  echo "📋 GATE 5: Commits Pushed to Remote"
+  echo "================================================"
+
+  CURRENT_BRANCH=$(git branch --show-current)
+  if git log origin/$CURRENT_BRANCH..$CURRENT_BRANCH --oneline 2>/dev/null | grep . > /dev/null; then
+    echo "⚠️  WARNING: Unpushed commits detected"
+    git log origin/$CURRENT_BRANCH..$CURRENT_BRANCH --oneline
+    WARNINGS=1
+  else
+    echo "✅ PASSED: All commits pushed to remote"
+  fi
+  echo ""
+fi
+
+# GATE 6: PR Comments Addressed (pre-pr only)
+if [ "$MODE" = "pre-pr" ]; then
+  echo "================================================"
+  echo "📋 GATE 6: PR Comments Addressed"
+  echo "================================================"
+
+  # Check if gh CLI is available
+  if ! command -v gh &> /dev/null; then
+    echo "ℹ️  gh CLI not found - skipping PR comment check"
+    echo ""
+  else
+    # Try to get PR number for current branch
+    PR_NUMBER=$(gh pr view --json number --jq '.number' 2>/dev/null || echo "")
+
+    if [ -z "$PR_NUMBER" ]; then
+      echo "ℹ️  No PR found for current branch - skipping comment check"
+    else
+      echo "Found PR #$PR_NUMBER"
+
+      # Get PR comments count
+      COMMENT_COUNT=$(gh api repos/:owner/:repo/pulls/$PR_NUMBER/comments --jq 'length' 2>/dev/null || echo "0")
+
+      if [ "$COMMENT_COUNT" -gt 0 ]; then
+        echo "⚠️  WARNING: PR has $COMMENT_COUNT review comments"
+        echo "   Please ensure all comments are addressed before marking ready for review"
+        echo ""
+        echo "   To view comments:"
+        echo "   gh pr view $PR_NUMBER --comments"
+        echo ""
+        echo "   To reply to a comment:"
+        echo "   gh api repos/:owner/:repo/pulls/comments/{comment_id}/replies -X POST -f body='your response'"
+        WARNINGS=1
+      else
+        echo "✅ PASSED: No outstanding PR comments"
+      fi
+    fi
+  fi
+  echo ""
+fi
+
+# GATE 7: Build Evidence Verification (pre-pr only)
+if [ "$MODE" = "pre-pr" ]; then
+  echo "================================================"
+  echo "📋 GATE 7: Build Evidence Verification"
+  echo "================================================"
+
+  # Check if build has been run (look for build output or recent dist/ directory)
+  BUILD_EVIDENCE_FOUND=0
+  
+  # Method 1: Check if dist/ directory exists and has recent files
+  if [ -d "dist" ]; then
+    # Check if dist has files modified in last 2 hours
+    if find dist -type f -newermt "2 hours ago" 2>/dev/null | grep -q .; then
+      BUILD_EVIDENCE_FOUND=1
+      echo "✅ Found: Recent files in dist/ directory"
+    fi
+  fi
+  
+  # Method 2: Check for build logs
+  if [ -f "server.log" ] && tail -50 server.log 2>/dev/null | grep -qiE "(Build.*success|Compiled successfully|build.*complete)"; then
+    BUILD_EVIDENCE_FOUND=1
+    echo "✅ Found: Build success in server.log"
+  fi
+  
+  # Method 3: Check if TypeScript compilation succeeds now
+  if command -v npx &> /dev/null; then
+    if npx tsc --noEmit --skipLibCheck > /dev/null 2>&1; then
+      BUILD_EVIDENCE_FOUND=1
+      echo "✅ Found: TypeScript compilation succeeds (runtime check)"
+    fi
+  fi
+  
+  if [ $BUILD_EVIDENCE_FOUND -eq 0 ]; then
+    echo "❌ FAILED: No build evidence found"
+    echo "   Required: Run 'npm run build' and verify it succeeds before marking PR ready"
+    echo "   Evidence can be: dist/ files, build logs, or successful compilation"
+    FAILED=1
+  else
+    echo "✅ PASSED: Build evidence verified"
+  fi
+  echo ""
+fi
+
+# GATE 8: Test Execution Verification (pre-pr only)
+if [ "$MODE" = "pre-pr" ]; then
+  echo "================================================"
+  echo "📋 GATE 8: Test Execution Verification"
+  echo "================================================"
+
+  # Check if test files were created in this PR/branch
+  NEW_TEST_FILES=$(find . -name "test-*.ts" -newer .git/HEAD 2>/dev/null | grep -v node_modules | head -10 || true)
+
+  if [ -n "$NEW_TEST_FILES" ]; then
+    echo "⚠️  WARNING: New test files detected:"
+    echo "$NEW_TEST_FILES" | sed 's/^/   - /'
+    echo "   Rule: All new test files must be executed before submitting evidence"
+    echo "   Check: Verify test execution results are included in PR evidence"
+    WARNINGS=1
+  else
+    echo "✅ PASSED: No new test files detected (or tests were executed)"
+  fi
+  
+  # Check evidence files for "pending" automated validations
+  EVIDENCE_FILES=$(find . -name "implementation-evidence-*.md" -o -name "*evidence*.md" 2>/dev/null | head -5 || true)
+  if [ -n "$EVIDENCE_FILES" ]; then
+    PENDING_AUTO=$(grep -l "pending.*automated\|pending.*test\|manual validation.*pending" $EVIDENCE_FILES 2>/dev/null | head -3 || true)
+    if [ -n "$PENDING_AUTO" ]; then
+      echo "⚠️  WARNING: Evidence files mention 'pending' automated validations:"
+      echo "$PENDING_AUTO" | sed 's/^/   - /'
+      echo "   Rule: Cannot mark automated validations as 'pending' without attempting them first"
+      echo "   Check: Verify all test files have been executed before submitting evidence"
+      WARNINGS=1
+    fi
+  fi
+  echo ""
+fi
+
+# GATE 9: Test Evidence Verification (pre-pr only)
+if [ "$MODE" = "pre-pr" ]; then
+  echo "================================================"
+  echo "📋 GATE 9: Test Evidence Verification"
+  echo "================================================"
+
+  TEST_EVIDENCE_FOUND=0
+  
+  # Method 1: Check PR comments for test evidence
+  if command -v gh &> /dev/null; then
+    PR_NUMBER=$(gh pr view --json number --jq '.number' 2>/dev/null || echo "")
+    if [ -n "$PR_NUMBER" ]; then
+      # Search PR comments for test evidence keywords
+      if gh api repos/:owner/:repo/pulls/$PR_NUMBER/comments --jq '.[].body' 2>/dev/null | grep -qiE "(test.*pass|test.*evidence|test.*result|exit code.*0|✅.*test)" 2>/dev/null; then
+        TEST_EVIDENCE_FOUND=1
+        echo "✅ Found: Test evidence in PR comments"
+      fi
+    fi
+  fi
+  
+  # Method 2: Check for test log files with pass indicators
+  if [ -f "test.log" ] && grep -qE "(pass|PASS|✅|exit code.*0)" test.log 2>/dev/null; then
+    TEST_EVIDENCE_FOUND=1
+    echo "✅ Found: Test evidence in test.log"
+  fi
+  
+  # Method 3: Check for npm test exit codes (if test.log exists and shows recent runs)
+  # Note: We don't run tests here (too slow), just check for evidence of recent test runs
+  if [ -f "test.log" ] && [ -n "$(find test.log -mmin -60 2>/dev/null)" ]; then
+    # If test.log was modified in last hour, assume tests were run
+    if grep -qE "(pass|PASS|✅)" test.log 2>/dev/null; then
+      TEST_EVIDENCE_FOUND=1
+      echo "✅ Found: Recent test run in test.log"
+    fi
+  fi
+  
+  if [ $TEST_EVIDENCE_FOUND -eq 0 ]; then
+    echo "❌ FAILED: No test evidence found"
+    echo "   Required: Provide test evidence before marking PR ready"
+    echo "   Evidence can be: PR comment with test results, test.log file, or passing test run"
+    echo "   Evidence must include exit codes and test names"
+    FAILED=1
+  else
+    echo "✅ PASSED: Test evidence verified"
+  fi
+  echo ""
+fi
+
+# GATE 11: Issue Label Verification (pre-pr only)
+if [ "$MODE" = "pre-pr" ]; then
+  echo "================================================"
+  echo "📋 GATE 10: Issue Label Verification"
+  echo "================================================"
+
+  if ! command -v gh &> /dev/null; then
+    echo "ℹ️  gh CLI not found - skipping issue label check"
+    echo ""
+  else
+    # Extract issue number from branch name
+    CURRENT_BRANCH=$(git branch --show-current)
+    ISSUE_NUMBER=$(echo "$CURRENT_BRANCH" | sed -n 's/feature\/\([0-9]\+\).*/\1/p')
+    
+    if [ -z "$ISSUE_NUMBER" ]; then
+      echo "⚠️  WARNING: Could not extract issue number from branch: $CURRENT_BRANCH"
+      echo "   Expected format: feature/533-slug"
+      echo "   Skipping label verification"
+    else
+      echo "Checking labels for issue #$ISSUE_NUMBER"
+      
+      # Get issue labels
+      LABELS=$(gh api repos/:owner/:repo/issues/$ISSUE_NUMBER --jq '.labels[].name' 2>/dev/null || echo "")
+      
+      if [ -z "$LABELS" ]; then
+        echo "❌ FAILED: Could not fetch issue labels"
+        echo "   Check that issue #$ISSUE_NUMBER exists and is accessible"
+        FAILED=1
+      else
+        # Check for phase label
+        HAS_PHASE_LABEL=false
+        PHASE_LABEL=""
+        while IFS= read -r label; do
+          case "$label" in
+            phase:spec|phase:design|phase:impl|phase:tests)
+              HAS_PHASE_LABEL=true
+              PHASE_LABEL="$label"
+              break
+              ;;
+          esac
+        done <<< "$LABELS"
+        
+        # Check status labels
+        HAS_STATUS_WIP=false
+        HAS_STATUS_NEEDS_REVIEW=false
+        while IFS= read -r label; do
+          case "$label" in
+            status:wip)
+              HAS_STATUS_WIP=true
+              ;;
+            status:needs-review)
+              HAS_STATUS_NEEDS_REVIEW=true
+              ;;
+          esac
+        done <<< "$LABELS"
+        
+        # Validation
+        if [ "$HAS_PHASE_LABEL" = false ]; then
+          echo "❌ FAILED: Issue missing phase label"
+          echo "   Required: phase:spec, phase:design, phase:impl, or phase:tests"
+          echo "   Current labels: $LABELS"
+          FAILED=1
+        elif [ "$HAS_STATUS_NEEDS_REVIEW" = true ] && [ "$HAS_STATUS_WIP" = true ]; then
+          echo "❌ FAILED: Issue has both status:wip and status:needs-review"
+          echo "   Remove status:wip before marking ready for review"
+          echo "   Current labels: $LABELS"
+          FAILED=1
+        else
+          echo "✅ PASSED: Issue labels correct"
+          echo "   Phase: $PHASE_LABEL"
+          if [ "$HAS_STATUS_NEEDS_REVIEW" = true ]; then
+            echo "   Status: status:needs-review"
+          elif [ "$HAS_STATUS_WIP" = true ]; then
+            echo "   Status: status:wip"
+          else
+            echo "   Status: (none)"
+          fi
+        fi
+      fi
+    fi
+  fi
+  echo ""
+fi
+
+# GATE 10: Validation Plan Coverage (pre-pr only)
+if [ "$MODE" = "pre-pr" ]; then
+  echo "================================================"
+  echo "📋 GATE 9: Test Coverage Alignment"
+  echo "================================================"
+
+  # Extract issue number from branch
+  CURRENT_BRANCH=$(git branch --show-current)
+  ISSUE_NUMBER=$(echo "$CURRENT_BRANCH" | sed -n 's/feature\/\([0-9]\+\).*/\1/p')
+  
+  if [ -z "$ISSUE_NUMBER" ]; then
+    echo "ℹ️  Could not extract issue number from branch - skipping validation plan check"
+  elif command -v npx &> /dev/null; then
+    # Run validation coverage checker
+    COVERAGE_OUTPUT=$(GIT_BRANCH="$CURRENT_BRANCH" npx tsx "$(dirname "$0")/validate-test-coverage.ts" "$ISSUE_NUMBER" 2>&1)
+    COVERAGE_EXIT=$?
+    
+    echo "$COVERAGE_OUTPUT"
+    
+    if [ $COVERAGE_EXIT -eq 1 ]; then
+      # Coverage incomplete
+      FAILED=1
+    elif echo "$COVERAGE_OUTPUT" | grep -qi "skipped\|no.*validation plan\|no spec"; then
+      # No spec/design or no validation plan - Gate 9 warns but doesn't block
+      echo "⚠️  WARNING: Validation plan check skipped (no spec/design or no validation plan)"
+      echo "   This is acceptable, but consider adding validation plan to spec/design for future issues"
+      WARNINGS=1
+    fi
+  else
+    echo "ℹ️  npx not available - skipping validation plan coverage check"
+    echo "   Install: npm (Node.js package manager)"
+  fi
+  echo ""
+fi
+
+# GATE 12: ChatGPT Length Limits (pre-pr only)
+if [ "$MODE" = "pre-pr" ]; then
+  echo "================================================"
+  echo "📋 GATE 11: ChatGPT Length Limits"
+  echo "================================================"
+
+  CHATGPT_LIMITS_FAILED=0
+
+  # Check instructions.txt length (8,000 char limit)
+  if [ -f "src/openapi/instructions.txt" ]; then
+    if command -v python &> /dev/null || command -v python3 &> /dev/null; then
+      PYTHON_CMD=$(command -v python3 2>/dev/null || command -v python 2>/dev/null)
+      INST_LENGTH=$($PYTHON_CMD -c "f = open('src/openapi/instructions.txt', 'r', encoding='utf-8'); content = f.read(); f.close(); print(len(content))" 2>/dev/null || echo "0")
+      
+      if [ "$INST_LENGTH" -gt 8000 ]; then
+        echo "❌ FAILED: instructions.txt exceeds 8,000 character limit"
+        echo "   Current length: $INST_LENGTH characters"
+        echo "   Limit: 8,000 characters"
+        echo "   Solution: Move detailed content to KB files (KB-*.txt) and reference them"
+        echo "   See: $ARCH_DOC#chatgpt-length-limitations"
+        CHATGPT_LIMITS_FAILED=1
+      else
+        echo "✅ PASSED: instructions.txt length ($INST_LENGTH chars) within limit (8,000)"
+      fi
+    else
+      echo "ℹ️  python not found - skipping instructions.txt length check"
+    fi
+  fi
+
+  # Check OpenAPI operation description lengths (300 char limit)
+  if [ -f "$OPENAPI_PATH" ]; then
+    if command -v python &> /dev/null || command -v python3 &> /dev/null; then
+      PYTHON_CMD=$(command -v python3 2>/dev/null || command -v python 2>/dev/null)
+      LONG_DESCS=$($PYTHON_CMD -c "
+import json
+try:
+    f = open('$OPENAPI_PATH', 'r', encoding='utf-8')
+    spec = json.load(f)
+    f.close()
+    violations = []
+    for path, methods in spec.get('paths', {}).items():
+        for method, details in methods.items():
+            if isinstance(details, dict) and 'description' in details:
+                desc = details['description']
+                if len(desc) > 300:
+                    violations.append(f'{path} {method.upper()}: {len(desc)} chars')
+    if violations:
+        print('\n'.join(violations))
+    else:
+        print('OK')
+except Exception as e:
+    print(f'ERROR: {e}')
+" 2>/dev/null || echo "ERROR")
+
+      if [ "$LONG_DESCS" != "OK" ] && [ -n "$LONG_DESCS" ] && [ "$LONG_DESCS" != "ERROR" ]; then
+        echo "❌ FAILED: OpenAPI operation descriptions exceed 300 character limit"
+        echo "$LONG_DESCS" | while IFS= read -r line; do
+          echo "   $line"
+        done
+        echo "   Solution: Shorten descriptions, move details to KB files, reference KB files"
+        echo "   See: $ARCH_DOC#chatgpt-length-limitations"
+        CHATGPT_LIMITS_FAILED=1
+      elif [ "$LONG_DESCS" = "ERROR" ]; then
+        echo "⚠️  WARNING: Could not validate OpenAPI description lengths (JSON parsing error)"
+        WARNINGS=1
+      else
+        echo "✅ PASSED: All OpenAPI operation descriptions within limit (300 chars)"
+      fi
+    else
+      echo "ℹ️  python not found - skipping OpenAPI description length check"
+    fi
+  fi
+
+  if [ $CHATGPT_LIMITS_FAILED -eq 1 ]; then
+    FAILED=1
+  fi
+  echo ""
+fi
+
+# Summary
+echo "================================================"
+echo "📊 QUALITY CHECK SUMMARY ($MODE mode)"
+echo "================================================"
+echo ""
+
+if [ $FAILED -eq 1 ]; then
+  echo "❌ CHECKS FAILED"
+  echo ""
+  echo "Critical issues found. Cannot proceed."
+  echo "See rules/code-quality-and-debugging-patterns.md"
+  exit 1
+elif [ $WARNINGS -gt 0 ]; then
+  echo "⚠️  CHECKS PASSED WITH WARNINGS"
+  echo ""
+  echo "Some warnings found. Consider addressing before proceeding."
+
+  if [ "$MODE" = "pre-commit" ]; then
+    echo "You can still commit, but consider fixing warnings."
+    exit 0
+  else
+    exit 0
+  fi
+else
+  echo "✅ ALL CHECKS PASSED"
+  echo ""
+
+  if [ "$MODE" = "pre-commit" ]; then
+    echo "Ready to commit!"
+  elif [ "$MODE" = "pre-pr" ]; then
+    echo "Ready to create PR!"
+    echo "Run: gh pr create --title \"your title\" --body \"your description\""
+  else
+    echo "CI checks complete!"
+  fi
+  exit 0
+fi