@boyingliu01/xp-gate 0.27.4 → 0.27.5

package/adapters/gate-3.sh

@@ -1,3 +1,4 @@
+# shellcheck shell=bash
 # ============================================================================
 # GATE 3: Cyclomatic Complexity Check
 # Uses lizard - checks cyclomatic complexity of changed source files
@@ -6,18 +7,62 @@
  2>&1 echo ""
  2>&1 echo "→ Gate 3: Cyclomatic complexity..."
 GATE_3_START=$(gate_start_ms)
+# #537: every non-run records WHY so the report can say why a gate is SKIP.
+GATE_3_REASON=""
 
 if [ "$PROJECT_LANG" = "documentation-only" ]; then
   echo "⏭️  SKIPPED - Complexity (documentation project)."
   GATE_3_STATUS="SKIP"
+  GATE_3_REASON="documentation_project"
 
 elif [ "$PROJECT_LANG" = "powershell" ]; then
   echo "ℹ️  No PowerShell Clean Code / SOLID tool available"
   echo "⏭️  SKIPPED - Complexity (no PowerShell tool)"
   GATE_3_STATUS="SKIP"
+  # #537: a PowerShell-primary repo was invisible to this dimension while the
+  # score implied full coverage — say exactly why nothing ran.
+  GATE_3_REASON="no_powershell_tool"
   
 else
-  CCN_THRESHOLD=5
+  # S2 (#507): three-level CCN threshold override --
+  # .xp-gate/ccn-threshold (positive integer) > XP_GATE_CCN_THRESHOLD > 5.
+  # Invalid values WARN on stderr and fall back to the default; the resolved
+  # value reaches the gate-3 audit record via the --detail argument below.
+  # Implemented with bash builtins only (no tr/grep spawns): every process
+  # spawn is expensive on Windows under AV filter drivers.
+  resolve_ccn_threshold() {
+    local default=5 val
+    if [ -f ".xp-gate/ccn-threshold" ]; then
+      val=$(<".xp-gate/ccn-threshold")
+      val="${val//[[:space:]]/}"
+      case "$val" in
+        ''|*[!0-9]*|0)
+          echo "WARN - invalid .xp-gate/ccn-threshold value '${val}' (expected a positive integer), falling back to ${default}" >&2
+          ;;
+        *)
+          echo "$val"
+          return 0
+          ;;
+      esac
+      echo "$default"
+      return 0
+    fi
+    val=${XP_GATE_CCN_THRESHOLD:-}
+    if [ -n "$val" ]; then
+      case "$val" in
+        ''|*[!0-9]*|0)
+          echo "WARN - invalid XP_GATE_CCN_THRESHOLD value '${val}' (expected a positive integer), falling back to ${default}" >&2
+          ;;
+        *)
+          echo "$val"
+          return 0
+          ;;
+      esac
+    fi
+    echo "$default"
+  }
+
+  CCN_THRESHOLD=$(resolve_ccn_threshold)
   
   # Check lizard availability
   LIZARD_CMD=""
@@ -37,7 +82,16 @@ else
       echo "Checking complexity for source files..."
       
       # Run lizard with CCN threshold
-      CC_OUTPUT=$($LIZARD_PATH -C $CCN_THRESHOLD $CC_FILES 2>&1 || true)
+      # One path per line, into an array. Unquoted $CC_FILES relied on word
+      # splitting, which also splits any path containing a space -- handing
+      # lizard two bogus paths and checking neither (#457 defect class, same
+      # fix as gate-4's PRINCIPLES_ARGS). Quoting the scalar would instead
+      # collapse the list into one argument. An array does both.
+      CC_FILES_ARGS=()
+      while IFS= read -r _cc_file; do
+        [ -n "$_cc_file" ] && CC_FILES_ARGS+=("$_cc_file")
+      done <<< "$CC_FILES"
+      CC_OUTPUT=$("$LIZARD_PATH" -C "$CCN_THRESHOLD" ${CC_FILES_ARGS[@]+"${CC_FILES_ARGS[@]}"} 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)
@@ -57,12 +111,14 @@ else
     else
       echo "⏭️  SKIPPED - Complexity (no source files to check)."
       GATE_3_STATUS="SKIP"
+      GATE_3_REASON="no_source_files_changed"
     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"
+    GATE_3_REASON="tool_not_installed"
   fi
 fi
-record_gate_audit "gate-3" "complexity" "$GATE_3_STATUS" "${CC_WARNINGS:-0}" "$GATE_3_START"
+record_gate_audit "gate-3" "complexity" "$GATE_3_STATUS" "${CC_WARNINGS:-0}" "$GATE_3_START" "ccn_threshold=${CCN_THRESHOLD:-5}"

package/adapters/gate-4.sh

@@ -1,17 +1,67 @@
+# shellcheck shell=bash
 # ============================================================================
 # GATE 4: Principles Checker (Clean Code + SOLID)
 # Reuses existing principles checker logic
 # ============================================================================
 
+# Run a TypeScript entrypoint under tsx without routing arguments through the
+# npx shim: Windows cmd.exe caps command lines at 8191 chars and long staged
+# file lists overflow it, turning a healthy run into a false BLOCK. Prefer the
+# repo-local tsx CLI driven by node directly; keep npx as fallback for consumer
+# repos relying on a global install. Defined here as well so this module also
+# works when sourced outside pre-commit.
+if ! declare -F run_tsx >/dev/null 2>&1; then
+  run_tsx() {
+    local _root="${PROJECT_ROOT:-$(pwd)}" _timeout=()
+    if [ -n "${RUN_TSX_TIMEOUT:-}" ]; then
+      _timeout=(timeout "$RUN_TSX_TIMEOUT")
+    fi
+    if [ -f "$_root/node_modules/tsx/dist/cli.mjs" ] && command -v node >/dev/null 2>&1; then
+      "${_timeout[@]}" node "$_root/node_modules/tsx/dist/cli.mjs" "$@"
+    else
+      "${_timeout[@]}" npx tsx "$@"
+    fi
+  }
+fi
+
+# Java rule coverage annotation (#507 S4, AC-507-04-02). The normative matrix
+# lives in docs/java-principles-coverage.md; these constants mirror it. Before
+# #507 the Java adapter fed rules only {name,type,line,code}, so the 12 rules
+# reading structured metrics silently saw `undefined` and a Java commit got a
+# green "checked" with zero effective coverage. 12/15 now fire; the three
+# inert ones are rule-side gaps documented in the coverage doc -- they must
+# NOT be announced as covered.
+JAVA_COVERAGE_EFFECTIVE=12
+JAVA_COVERAGE_TOTAL=15
+JAVA_COVERAGE_INERT="lsp, many-exports, code-duplication"
+
+# Print the coverage annotation when (and only when) the staged file list
+# contains Java sources. Non-Java commits keep the original output byte for
+# byte. Pure shell builtins: no subprocess per file.
+java_coverage_note() {
+  local _f _has_java=""
+  for _f in "$@"; do
+    case "$_f" in
+      *.java|*.Java|*.JAVA) _has_java=1; break ;;
+    esac
+  done
+  [ -n "$_has_java" ] || return 0
+  echo "ℹ️  Java rule coverage: $JAVA_COVERAGE_EFFECTIVE/$JAVA_COVERAGE_TOTAL rules effective (inert on Java: $JAVA_COVERAGE_INERT -- see docs/java-principles-coverage.md)"
+}
+
  2>&1 echo ""
  2>&1 echo "→ Gate 4: Principles checker (Clean Code + SOLID)..."
 GATE_4_START=$(gate_start_ms)
 
 GATE_4_STATUS=""
+# #537: every non-run records WHY (no files / tool missing / unsupported lang)
+# so the quality report can distinguish "not applicable" from "not covered".
+GATE_4_REASON=""
 
 if [ "$PROJECT_LANG" = "documentation-only" ]; then
   echo "⏭️  SKIPPED - Principles check (documentation project)."
   GATE_4_STATUS="SKIP"
+  GATE_4_REASON="documentation_project"
   
 else
   # Get source files to check against principles
@@ -28,10 +78,13 @@ else
   done <<< "$PRINCIPLES_FILES"
   
   if [ -n "$PRINCIPLES_FILES" ]; then
-    # Same anchoring as githooks/gate-4.sh: CHANGED_FILES paths are repo-root relative
-    # and the checker resolves them against its own working directory, so both the
-    # probes and the invocation run from the repo root. Resolving them against the
-    # hook's CWD lost the checker in single-language subdir mode (#478).
+    # The checker resolves every path it is given -- and every path in CHANGED_FILES
+    # comes from `git diff`, so it is repo-root relative -- against its own working
+    # directory. Resolving against the hook's CWD broke in single-language subdir
+    # mode, where pre-commit has already cd'd into $PROJECT_SUBDIR: web/src/a.ts was
+    # looked up as web/web/src/a.ts, the probes below missed the checker that was
+    # installed one level up, and a working gate degraded to SKIPPED (#478).
+    # Everything this gate reads is therefore anchored at the repo root.
     PRINCIPLES_BASE="${PROJECT_ROOT:-$(pwd)}"
 
     PRINCIPLES_DIR=""
@@ -49,8 +102,13 @@ else
     
     if [ -n "$PRINCIPLES_DIR" ]; then
       echo "Checking Clean Code + SOLID principles..."
-      
-      if command -v npx > /dev/null 2>&1; then
+
+      # AC-507-04-02: say what a Java commit is actually covered for, instead
+      # of implying a full 15-rule check (#507). Printed before the run so it
+      # appears on both the PASS and the FAIL path.
+      java_coverage_note ${PRINCIPLES_ARGS[@]+"${PRINCIPLES_ARGS[@]}"}
+
+      if command -v npx > /dev/null 2>&1 || [ -f "$PRINCIPLES_BASE/node_modules/tsx/dist/cli.mjs" ]; then
         # Run principles checker and store results.
         #
         # Do NOT wrap this in `if ...; then`: the checker's exit codes are
@@ -72,6 +130,7 @@ else
         # Sending it to /dev/null made an exit-2 SKIP undiagnosable and hid every
         # .principlesrc typo (Delphi walkthrough MC-03). Captured to a file so a clean
         # run stays quiet, then replayed only when the checker had a problem.
+        #
         # `cd || exit 2`: a base we cannot enter means the checker never ran, which is
         # this module's tool-failure code. Falling through would return the exit status
         # of the failed cd (1), and 1 asserts "I examined files and found errors" -- an
@@ -86,7 +145,7 @@ else
         PRINCIPLES_JSON=$(mktemp)
         export PRINCIPLES_JSON
         ( cd "$PRINCIPLES_BASE" 2>/dev/null || exit 2
-          npx tsx "$PRINCIPLES_DIR/index.ts" --files ${PRINCIPLES_ARGS[@]+"${PRINCIPLES_ARGS[@]}"} --format json ) > "$PRINCIPLES_JSON" 2>"$PRINCIPLES_STDERR" || PRINCIPLES_EXIT=$?
+          run_tsx "$PRINCIPLES_DIR/index.ts" --files ${PRINCIPLES_ARGS[@]+"${PRINCIPLES_ARGS[@]}"} --format json ) > "$PRINCIPLES_JSON" 2>"$PRINCIPLES_STDERR" || PRINCIPLES_EXIT=$?
 
         if [ -s "$PRINCIPLES_STDERR" ]; then
           sed 's/^/     /' "$PRINCIPLES_STDERR"
@@ -97,6 +156,7 @@ else
           echo "⚠️  Warning: Principles checker execution failed"
           echo "⏭️  SKIPPED - Principles check (execution issue)"
           GATE_4_STATUS="SKIP"
+          GATE_4_REASON="checker_execution_error"
           rm -f "$PRINCIPLES_JSON"
         else
           # Check severity levels. The reporter emits JSON.stringify(out, null, 2),
@@ -116,7 +176,7 @@ else
             echo "  - SOLID principle violations"
             echo "  - architectural violations"
             ( cd "$PRINCIPLES_BASE" 2>/dev/null || exit 2
-              npx tsx "$PRINCIPLES_DIR/index.ts" --files ${PRINCIPLES_ARGS[@]+"${PRINCIPLES_ARGS[@]}"} --format console )
+              run_tsx "$PRINCIPLES_DIR/index.ts" --files ${PRINCIPLES_ARGS[@]+"${PRINCIPLES_ARGS[@]}"} --format console )
             GATE_4_STATUS="FAIL"
             exit 1
           fi
@@ -128,18 +188,21 @@ else
           fi
         fi
       else
-        echo "ℹ️  npx not available - skipping principles check"
-        echo "⏭️  SKIPPED - Principles check (no Node.js/npx)"
+        echo "ℹ️  npx/tsx not available - skipping principles check"
+        echo "⏭️  SKIPPED - Principles check (no Node.js/tsx)"
         GATE_4_STATUS="SKIP"
+        GATE_4_REASON="tool_not_installed"
       fi
     else
       echo "ℹ️  Principles checker not found in project - skipping"
       echo "⏭️  SKIPPED - Principles check (checker not in project)"
       GATE_4_STATUS="SKIP"
+      GATE_4_REASON="checker_not_found"
     fi
   else
     echo "⏭️  SKIPPED - Principles check (no matching source files changed)"
     GATE_4_STATUS="SKIP"
+    GATE_4_REASON="no_matching_files_changed"
   fi
 fi
 record_gate_audit "gate-4" "principles" "$GATE_4_STATUS" "${WARNING_COUNT:-0}" "$GATE_4_START"

package/adapters/gate-7.sh

@@ -10,10 +10,14 @@ 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)
+# #536: scanned_files makes a trivial PASS (nothing to scan) auditable in the
+# quality report instead of reading like a covered security check.
+GATE_7_SCANNED_FILES=0
 if [ -z "$IAC_FILES" ]; then
   echo "✅ PASSED - No IaC files detected in changes."
   GATE_7_STATUS="PASS"
 else
+  GATE_7_SCANNED_FILES=$(printf '%s\n' "$IAC_FILES" | sed -n '/./p' | wc -l | tr -d '[:space:]')
   # Run IaC adapter. Resolution follows the documented 3-tier convention
   # (adapter-common.sh): global ~/.config/xp-gate/adapters -> project
   # githooks/adapters -> script dir. The old cwd-only test silently SKIPped

package/adapters/powershell.sh

@@ -31,12 +31,20 @@ _detect_pwsh() {
 
 _find_powershell_files() {
   local name_pattern="$1"
+  # #538: gitignored drill/review artifact dirs hold hundreds of non-product
+  # .ps1 files (admin drills, Delphi review copies). Collecting them turned
+  # Gate 1 into an 800+ warning wall and made the pwsh gates unusable.
   find . \
     \( -type d \( \
       -name .git -o \
       -name node_modules -o \
       -name dist -o \
       -name coverage -o \
+      -name .worktrees -o \
+      -name .delphi-work -o \
+      -name .workbuddy -o \
+      -name .sprint-state -o \
+      -name wrc-drill -o \
       -path './plugins/claude-code/skills' -o \
       -path './plugins/opencode/skills' -o \
       -path './plugins/qoder/skills' -o \

package/gate-10.sh

@@ -10,6 +10,10 @@
 GATE_10_START=$(gate_start_ms)
 
 GATE_10_STATUS=""
+# #536: audit trail for "did this commit actually get scanned?". The report
+# surfaces reason + scanned_files so a non-scan never reads as a clean PASS.
+GATE_10_REASON=""
+GATE_10_SCANNED_FILES=0
 
 # Semgrep availability check
 SEMGREP_CMD=""
@@ -25,6 +29,7 @@ if [ -z "$SEMGREP_CMD" ]; then
   echo "     Pre-cache rules: semgrep --config=p/security-audit"
   echo "     Gate 10: SAST Security (WARN, semgrep not installed)"
   GATE_10_STATUS="WARN"
+  GATE_10_REASON="tool_not_installed"
 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)
@@ -32,6 +37,7 @@ else
   if [ -z "$SEMGREP_FILES" ]; then
     echo "     ⏭️  SKIPPED - SAST (no supported language files changed)"
     GATE_10_STATUS="SKIP"
+    GATE_10_REASON="no_supported_files"
   else
     # One path per line into an array. Quoting the newline-joined list would hand
     # semgrep ONE argument containing newlines -> "Invalid scanning root" once
@@ -66,6 +72,7 @@ EOF
       echo "     Install node (https://nodejs.org); without it SAST findings cannot be classified"
       echo "     ⏭️  SKIPPED - SAST (node not installed)"
       GATE_10_STATUS="SKIP"
+      GATE_10_REASON="tool_not_installed"
     else
 
     # Run semgrep with JSON output. stdout and stderr are captured SEPARATELY:
@@ -138,6 +145,7 @@ console.log("");});
       fi
       echo "     ⏭️  SKIPPED - SAST (semgrep output unparseable)"
       GATE_10_STATUS="SKIP"
+      GATE_10_REASON="output_unparseable"
     elif [ "$V_RESULTS" -eq 0 ] && { [ "$V_ERRORS" -gt 0 ] || [ "$SEMGREP_EXIT" -ne 0 ]; }; then
       # Nothing was scanned to a verdict: semgrep either failed outright
       # (nonzero exit) or completed but reported scan errors for every input
@@ -151,6 +159,7 @@ console.log("");});
       fi
       echo "     ⏭️  SKIPPED - SAST (semgrep runtime error)"
       GATE_10_STATUS="SKIP"
+      GATE_10_REASON="semgrep_runtime_error"
     elif [ "$V_BLOCKING" -gt 0 ]; then
       echo ""
       echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
@@ -164,8 +173,10 @@ console.log("");});
       echo "$FINDING_DETAILS"
       echo "  Run 'semgrep scan --config=p/security-audit' to review all findings."
       GATE_10_STATUS="FAIL"
+      GATE_10_SCANNED_FILES=${#SEMGREP_ARGS[@]}
       exit 1
     else
+      GATE_10_SCANNED_FILES=${#SEMGREP_ARGS[@]}
       echo ""
       echo "     ✅ PASSED - No blocking vulnerabilities (files scanned: ${#SEMGREP_ARGS[@]})"
       if [ "$V_WARNINGS" -gt 0 ]; then

package/gate-3.sh

@@ -7,15 +7,21 @@
  2>&1 echo ""
  2>&1 echo "→ Gate 3: Cyclomatic complexity..."
 GATE_3_START=$(gate_start_ms)
+# #537: every non-run records WHY so the report can say why a gate is SKIP.
+GATE_3_REASON=""
 
 if [ "$PROJECT_LANG" = "documentation-only" ]; then
   echo "⏭️  SKIPPED - Complexity (documentation project)."
   GATE_3_STATUS="SKIP"
+  GATE_3_REASON="documentation_project"
 
 elif [ "$PROJECT_LANG" = "powershell" ]; then
   echo "ℹ️  No PowerShell Clean Code / SOLID tool available"
   echo "⏭️  SKIPPED - Complexity (no PowerShell tool)"
   GATE_3_STATUS="SKIP"
+  # #537: a PowerShell-primary repo was invisible to this dimension while the
+  # score implied full coverage — say exactly why nothing ran.
+  GATE_3_REASON="no_powershell_tool"
   
 else
   # S2 (#507): three-level CCN threshold override --
@@ -105,12 +111,14 @@ else
     else
       echo "⏭️  SKIPPED - Complexity (no source files to check)."
       GATE_3_STATUS="SKIP"
+      GATE_3_REASON="no_source_files_changed"
     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"
+    GATE_3_REASON="tool_not_installed"
   fi
 fi
 record_gate_audit "gate-3" "complexity" "$GATE_3_STATUS" "${CC_WARNINGS:-0}" "$GATE_3_START" "ccn_threshold=${CCN_THRESHOLD:-5}"

package/gate-4.sh

@@ -54,10 +54,14 @@ java_coverage_note() {
 GATE_4_START=$(gate_start_ms)
 
 GATE_4_STATUS=""
+# #537: every non-run records WHY (no files / tool missing / unsupported lang)
+# so the quality report can distinguish "not applicable" from "not covered".
+GATE_4_REASON=""
 
 if [ "$PROJECT_LANG" = "documentation-only" ]; then
   echo "⏭️  SKIPPED - Principles check (documentation project)."
   GATE_4_STATUS="SKIP"
+  GATE_4_REASON="documentation_project"
   
 else
   # Get source files to check against principles
@@ -152,6 +156,7 @@ else
           echo "⚠️  Warning: Principles checker execution failed"
           echo "⏭️  SKIPPED - Principles check (execution issue)"
           GATE_4_STATUS="SKIP"
+          GATE_4_REASON="checker_execution_error"
           rm -f "$PRINCIPLES_JSON"
         else
           # Check severity levels. The reporter emits JSON.stringify(out, null, 2),
@@ -186,15 +191,18 @@ else
         echo "ℹ️  npx/tsx not available - skipping principles check"
         echo "⏭️  SKIPPED - Principles check (no Node.js/tsx)"
         GATE_4_STATUS="SKIP"
+        GATE_4_REASON="tool_not_installed"
       fi
     else
       echo "ℹ️  Principles checker not found in project - skipping"
       echo "⏭️  SKIPPED - Principles check (checker not in project)"
       GATE_4_STATUS="SKIP"
+      GATE_4_REASON="checker_not_found"
     fi
   else
     echo "⏭️  SKIPPED - Principles check (no matching source files changed)"
     GATE_4_STATUS="SKIP"
+    GATE_4_REASON="no_matching_files_changed"
   fi
 fi
 record_gate_audit "gate-4" "principles" "$GATE_4_STATUS" "${WARNING_COUNT:-0}" "$GATE_4_START"

package/gate-7.sh

@@ -10,10 +10,14 @@ 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)
+# #536: scanned_files makes a trivial PASS (nothing to scan) auditable in the
+# quality report instead of reading like a covered security check.
+GATE_7_SCANNED_FILES=0
 if [ -z "$IAC_FILES" ]; then
   echo "✅ PASSED - No IaC files detected in changes."
   GATE_7_STATUS="PASS"
 else
+  GATE_7_SCANNED_FILES=$(printf '%s\n' "$IAC_FILES" | sed -n '/./p' | wc -l | tr -d '[:space:]')
   # Run IaC adapter. Resolution follows the documented 3-tier convention
   # (adapter-common.sh): global ~/.config/xp-gate/adapters -> project
   # githooks/adapters -> script dir. The old cwd-only test silently SKIPped

package/hooks/gate-10.sh

@@ -10,6 +10,10 @@
 GATE_10_START=$(gate_start_ms)
 
 GATE_10_STATUS=""
+# #536: audit trail for "did this commit actually get scanned?". The report
+# surfaces reason + scanned_files so a non-scan never reads as a clean PASS.
+GATE_10_REASON=""
+GATE_10_SCANNED_FILES=0
 
 # Semgrep availability check
 SEMGREP_CMD=""
@@ -25,6 +29,7 @@ if [ -z "$SEMGREP_CMD" ]; then
   echo "     Pre-cache rules: semgrep --config=p/security-audit"
   echo "     Gate 10: SAST Security (WARN, semgrep not installed)"
   GATE_10_STATUS="WARN"
+  GATE_10_REASON="tool_not_installed"
 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)
@@ -32,6 +37,7 @@ else
   if [ -z "$SEMGREP_FILES" ]; then
     echo "     ⏭️  SKIPPED - SAST (no supported language files changed)"
     GATE_10_STATUS="SKIP"
+    GATE_10_REASON="no_supported_files"
   else
     # One path per line into an array. Quoting the newline-joined list would hand
     # semgrep ONE argument containing newlines -> "Invalid scanning root" once
@@ -66,6 +72,7 @@ EOF
       echo "     Install node (https://nodejs.org); without it SAST findings cannot be classified"
       echo "     ⏭️  SKIPPED - SAST (node not installed)"
       GATE_10_STATUS="SKIP"
+      GATE_10_REASON="tool_not_installed"
     else
 
     # Run semgrep with JSON output. stdout and stderr are captured SEPARATELY:
@@ -138,6 +145,7 @@ console.log("");});
       fi
       echo "     ⏭️  SKIPPED - SAST (semgrep output unparseable)"
       GATE_10_STATUS="SKIP"
+      GATE_10_REASON="output_unparseable"
     elif [ "$V_RESULTS" -eq 0 ] && { [ "$V_ERRORS" -gt 0 ] || [ "$SEMGREP_EXIT" -ne 0 ]; }; then
       # Nothing was scanned to a verdict: semgrep either failed outright
       # (nonzero exit) or completed but reported scan errors for every input
@@ -151,6 +159,7 @@ console.log("");});
       fi
       echo "     ⏭️  SKIPPED - SAST (semgrep runtime error)"
       GATE_10_STATUS="SKIP"
+      GATE_10_REASON="semgrep_runtime_error"
     elif [ "$V_BLOCKING" -gt 0 ]; then
       echo ""
       echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
@@ -164,8 +173,10 @@ console.log("");});
       echo "$FINDING_DETAILS"
       echo "  Run 'semgrep scan --config=p/security-audit' to review all findings."
       GATE_10_STATUS="FAIL"
+      GATE_10_SCANNED_FILES=${#SEMGREP_ARGS[@]}
       exit 1
     else
+      GATE_10_SCANNED_FILES=${#SEMGREP_ARGS[@]}
       echo ""
       echo "     ✅ PASSED - No blocking vulnerabilities (files scanned: ${#SEMGREP_ARGS[@]})"
       if [ "$V_WARNINGS" -gt 0 ]; then

package/hooks/gate-3.sh

@@ -7,15 +7,21 @@
  2>&1 echo ""
  2>&1 echo "→ Gate 3: Cyclomatic complexity..."
 GATE_3_START=$(gate_start_ms)
+# #537: every non-run records WHY so the report can say why a gate is SKIP.
+GATE_3_REASON=""
 
 if [ "$PROJECT_LANG" = "documentation-only" ]; then
   echo "⏭️  SKIPPED - Complexity (documentation project)."
   GATE_3_STATUS="SKIP"
+  GATE_3_REASON="documentation_project"
 
 elif [ "$PROJECT_LANG" = "powershell" ]; then
   echo "ℹ️  No PowerShell Clean Code / SOLID tool available"
   echo "⏭️  SKIPPED - Complexity (no PowerShell tool)"
   GATE_3_STATUS="SKIP"
+  # #537: a PowerShell-primary repo was invisible to this dimension while the
+  # score implied full coverage — say exactly why nothing ran.
+  GATE_3_REASON="no_powershell_tool"
   
 else
   # S2 (#507): three-level CCN threshold override --
@@ -105,12 +111,14 @@ else
     else
       echo "⏭️  SKIPPED - Complexity (no source files to check)."
       GATE_3_STATUS="SKIP"
+      GATE_3_REASON="no_source_files_changed"
     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"
+    GATE_3_REASON="tool_not_installed"
   fi
 fi
 record_gate_audit "gate-3" "complexity" "$GATE_3_STATUS" "${CC_WARNINGS:-0}" "$GATE_3_START" "ccn_threshold=${CCN_THRESHOLD:-5}"

package/hooks/gate-4.sh

@@ -54,10 +54,14 @@ java_coverage_note() {
 GATE_4_START=$(gate_start_ms)
 
 GATE_4_STATUS=""
+# #537: every non-run records WHY (no files / tool missing / unsupported lang)
+# so the quality report can distinguish "not applicable" from "not covered".
+GATE_4_REASON=""
 
 if [ "$PROJECT_LANG" = "documentation-only" ]; then
   echo "⏭️  SKIPPED - Principles check (documentation project)."
   GATE_4_STATUS="SKIP"
+  GATE_4_REASON="documentation_project"
   
 else
   # Get source files to check against principles
@@ -152,6 +156,7 @@ else
           echo "⚠️  Warning: Principles checker execution failed"
           echo "⏭️  SKIPPED - Principles check (execution issue)"
           GATE_4_STATUS="SKIP"
+          GATE_4_REASON="checker_execution_error"
           rm -f "$PRINCIPLES_JSON"
         else
           # Check severity levels. The reporter emits JSON.stringify(out, null, 2),
@@ -186,15 +191,18 @@ else
         echo "ℹ️  npx/tsx not available - skipping principles check"
         echo "⏭️  SKIPPED - Principles check (no Node.js/tsx)"
         GATE_4_STATUS="SKIP"
+        GATE_4_REASON="tool_not_installed"
       fi
     else
       echo "ℹ️  Principles checker not found in project - skipping"
       echo "⏭️  SKIPPED - Principles check (checker not in project)"
       GATE_4_STATUS="SKIP"
+      GATE_4_REASON="checker_not_found"
     fi
   else
     echo "⏭️  SKIPPED - Principles check (no matching source files changed)"
     GATE_4_STATUS="SKIP"
+    GATE_4_REASON="no_matching_files_changed"
   fi
 fi
 record_gate_audit "gate-4" "principles" "$GATE_4_STATUS" "${WARNING_COUNT:-0}" "$GATE_4_START"