@boyingliu01/xp-gate 0.28.1 → 0.30.0

package/gate-3.sh

@@ -77,7 +77,24 @@ else
     
     # 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)
-    
+
+    # Grade exactly the population the baseline was written from. The two must
+    # match or the ratchet reports pre-existing code as "new", which is a false
+    # BLOCK no repair can clear (the exact failure #495 Round 3 called out, in a
+    # different place). scripts/ccn-report.cjs --write-baseline records only
+    # bucket === 'production' rows; its bucketFor() classifies two other buckets:
+    #   mirror     src/npm-package/**, plugins/*/src/** — regenerated by prepack
+    #              from a canonical source that IS graded here. Editing a mirror
+    #              is reverted at the next publish, so grading it cannot be acted
+    #              on (doctorDelphi CCN=106 blocked every src/npm-package commit,
+    #              on HEAD too — no baseline entry could ever exist for it).
+    #   test       __tests__/, *.test.*, *_test.{py,go}, *Test(s).java — recorded
+    #              in the report's test bucket, never in the baseline.
+    # Both prefixes and the test pattern mirror ccn-report.cjs so the gate and
+    # the writer cannot drift apart again (pinned by __tests__/gate-3-*.bats).
+    CC_FILES=$(echo "$CC_FILES" | grep -vE \
+      '^"?src/npm-package/|^"?plugins/[^/]+/src/|(^|/)__tests__?/|\.test\.[cm]?[jt]sx?$|_test\.(py|go)$|Test(s)?\.java$' || true)
+
     if [ -n "$CC_FILES" ]; then
       echo "Checking complexity for source files..."
       

package/hooks/gate-3.sh

@@ -77,7 +77,24 @@ else
     
     # 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)
-    
+
+    # Grade exactly the population the baseline was written from. The two must
+    # match or the ratchet reports pre-existing code as "new", which is a false
+    # BLOCK no repair can clear (the exact failure #495 Round 3 called out, in a
+    # different place). scripts/ccn-report.cjs --write-baseline records only
+    # bucket === 'production' rows; its bucketFor() classifies two other buckets:
+    #   mirror     src/npm-package/**, plugins/*/src/** — regenerated by prepack
+    #              from a canonical source that IS graded here. Editing a mirror
+    #              is reverted at the next publish, so grading it cannot be acted
+    #              on (doctorDelphi CCN=106 blocked every src/npm-package commit,
+    #              on HEAD too — no baseline entry could ever exist for it).
+    #   test       __tests__/, *.test.*, *_test.{py,go}, *Test(s).java — recorded
+    #              in the report's test bucket, never in the baseline.
+    # Both prefixes and the test pattern mirror ccn-report.cjs so the gate and
+    # the writer cannot drift apart again (pinned by __tests__/gate-3-*.bats).
+    CC_FILES=$(echo "$CC_FILES" | grep -vE \
+      '^"?src/npm-package/|^"?plugins/[^/]+/src/|(^|/)__tests__?/|\.test\.[cm]?[jt]sx?$|_test\.(py|go)$|Test(s)?\.java$' || true)
+
     if [ -n "$CC_FILES" ]; then
       echo "Checking complexity for source files..."
       

package/hooks/hook-module-resolution.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# GENERATED FILE — DO NOT EDIT.
+# Source of truth: src/npm-package/lib/hook-module-resolution.js
+# Regenerate: node scripts/generate-hook-resolution.cjs
+#
+# The module resolution order (#505) lives in one place, as data. This file
+# is its shell projection. Editing it by hand makes the hook disagree with
+# doctor.js, which reads the JS module directly — the exact divergence
+# #495/#500 were about.
+
+# Probe file used to pick the gate tier.
+HOOK_GATE_PROBE="gate-3.sh"
+
+# ADAPTER_DIR cascade, highest priority first.
+# Each entry is "tier_id|base_var|probe_file".
+HOOK_ADAPTER_DIR_TIERS=(
+  'global|GLOBAL_ADAPTER_DIR|adapter-common.sh'
+  'project|PROJECT_GITHOOKS|adapter-common.sh'
+  'script|SCRIPT_DIR|adapter-common.sh'
+)
+
+# Adapter resolution tiers, highest priority first.
+# Each entry is "tier_id|base_var|template" with {name} as the basename.
+HOOK_ADAPTER_TIERS=(
+  'adapter_flat|ADAPTER_DIR|{name}.sh'
+  'adapter_nested|ADAPTER_DIR|adapters/{name}.sh'
+  'project_nested|PROJECT_GITHOOKS|adapters/{name}.sh'
+  'script_nested|SCRIPT_DIR|adapters/{name}.sh'
+)
+
+# Gate resolution tiers, highest priority first.
+# Semantics differ from adapter tiers: each entry names the DIRECTORY that
+# would hold the gate probe, so a match yields the directory (GATE_DIR), not
+# the probe file itself. Entry format: "tier_id|base_var|(empty suffix)".
+HOOK_GATE_TIERS=(
+  'gate_adapter_dir|ADAPTER_DIR|'
+  'gate_project|PROJECT_GITHOOKS|'
+  'gate_script_dir|SCRIPT_DIR|'
+)

package/hooks/pre-commit

@@ -15,6 +15,89 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ADAPTER_DIR=""
 GLOBAL_ADAPTER_DIR="$HOME/.config/xp-gate/adapters"
 
+# #505: load the resolution-order data BEFORE any tier decision runs. The file is
+# generated from src/npm-package/lib/hook-module-resolution.js, which doctor.js
+# also reads, so the hook and the diagnostic share one order instead of two
+# hand-written copies that a parity test had to keep honest.
+#
+# It is looked up beside the hook (SCRIPT_DIR — always present, since this file
+# IS the hook) and beside adapter-common.sh (ADAPTER_DIR — where `xp-gate init`
+# and setup-global install the supporting modules). Either location works; the
+# hook-dir copy is what `doctor --sync-hooks` and sync-package-content maintain.
+# Note this runs BEFORE ADAPTER_DIR is resolved, which is why the script dir is
+# the primary location: reading the order cannot depend on the order.
+HOOK_RESOLUTION_SH="${SCRIPT_DIR}/hook-module-resolution.sh"
+if [ ! -f "$HOOK_RESOLUTION_SH" ] && [ -f "$GLOBAL_ADAPTER_DIR/hook-module-resolution.sh" ]; then
+  HOOK_RESOLUTION_SH="$GLOBAL_ADAPTER_DIR/hook-module-resolution.sh"
+fi
+if [ ! -f "$HOOK_RESOLUTION_SH" ]; then
+  # Fail closed: a hook that cannot load its resolution order must not fall back
+  # to an invented one — that would silently resurrect the duplication removed
+  # here, and doctor would report a different surface than the hook executes.
+  echo "FATAL: cannot load hook-module-resolution.sh (module resolution order is unavailable)" >&2
+  echo "Fix: reinstall the hooks (xp-gate init, or xp-gate doctor --sync-hooks in the xp-gate repo)." >&2
+  exit 1
+fi
+# shellcheck source=/dev/null
+. "$HOOK_RESOLUTION_SH"
+
+# Look up one tier's directory variable by name without eval-ing arbitrary input:
+# the base names are a closed set baked into the generated file.
+_hook_tier_base() {
+  case "$1" in
+    ADAPTER_DIR)      printf '%s' "$ADAPTER_DIR" ;;
+    GLOBAL_ADAPTER_DIR) printf '%s' "$GLOBAL_ADAPTER_DIR" ;;
+    PROJECT_GITHOOKS) printf '%s' "$PROJECT_GITHOOKS" ;;
+    SCRIPT_DIR)       printf '%s' "$SCRIPT_DIR" ;;
+    *)                printf '%s' "" ;;
+  esac
+}
+
+# Walk a "tier_id|base|suffix" table in order and print the first existing match.
+# Usage: _hook_resolve <module_filename> <tiers_array_name>
+_hook_resolve() {
+  local module_name="$1"
+  local tiers_var="$2"
+  local entry base suffix base_dir candidate
+  eval "set -- \"\${${tiers_var}[@]}\""
+  for entry in "$@"; do
+    entry="${entry#*|}"
+    base="${entry%%|*}"
+    suffix="${entry#*|}"
+    base_dir="$(_hook_tier_base "$base")"
+    [ -n "$base_dir" ] || continue
+    candidate="$base_dir/${suffix/\{name\}/$module_name}"
+    if [ -f "$candidate" ]; then
+      printf '%s' "$candidate"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# Walk a gate tier table and print the first DIRECTORY that contains the probe.
+# The adapter table yields a file; this one yields the directory the gate suite
+# lives in (GATE_DIR), which is why it probes rather than substitutes.
+# Usage: _hook_resolve_dir <probe_filename> <tiers_array_name>
+_hook_resolve_dir() {
+  local probe="$1"
+  local tiers_var="$2"
+  local entry base suffix base_dir
+  eval "set -- \"\${${tiers_var}[@]}\""
+  for entry in "$@"; do
+    entry="${entry#*|}"
+    base="${entry%%|*}"
+    suffix="${entry#*|}"
+    base_dir="$(_hook_tier_base "$base")"
+    [ -n "$base_dir" ] || continue
+    if [ -f "$base_dir${suffix}/$probe" ]; then
+      printf '%s' "$base_dir${suffix}"
+      return 0
+    fi
+  done
+  return 1
+}
+
 # BEGIN GIT CONTEXT FALLBACK
 if ! declare -F run_without_git_context >/dev/null 2>&1; then
   run_without_git_context() (
@@ -51,39 +134,25 @@ source "$ADAPTER_DIR/adapter-common.sh" 2>/dev/null || {
 # ADAPTER_DIR points to the base directory that contains either
 # adapter-common.sh directly (global) or adapter-common.sh in a flat layout.
 # Gate scripts live alongside adapter-common.sh.
+#
+# #505: the ORDER is not written here. HOOK_ADAPTER_TIERS is generated from
+# src/npm-package/lib/hook-module-resolution.js, which doctor.js reads directly,
+# so the hook and the diagnostic cannot disagree about which file wins.
 resolve_adapter_path() {
-  local lang="$1"
-  # Try flat layout first (global: typescript.sh next to adapter-common.sh)
-  if [ -f "$ADAPTER_DIR/${lang}.sh" ]; then
-    echo "$ADAPTER_DIR/${lang}.sh"
-    return 0
-  fi
-  # Try nested layout (project: adapters/typescript.sh)
-  if [ -f "$ADAPTER_DIR/adapters/${lang}.sh" ]; then
-    echo "$ADAPTER_DIR/adapters/${lang}.sh"
-    return 0
-  fi
-  # Try project githooks as fallback
-  if [ -f "$PROJECT_GITHOOKS/adapters/${lang}.sh" ]; then
-    echo "$PROJECT_GITHOOKS/adapters/${lang}.sh"
-    return 0
-  fi
-  # Try script dir as last resort
-  if [ -f "$SCRIPT_DIR/adapters/${lang}.sh" ]; then
-    echo "$SCRIPT_DIR/adapters/${lang}.sh"
-    return 0
-  fi
-  return 1
+  # ADAPTER templates carry the extension ("{name}.sh"), so pass the bare language
+  # name here. GATE templates are "{name}", so their call passes the full filename.
+  _hook_resolve "${1}" HOOK_ADAPTER_TIERS
 }
 
-# Gate scripts directory — falls back to project githooks if ADAPTER_DIR doesn't have them
-if [ -f "$ADAPTER_DIR/gate-3.sh" ]; then
-  GATE_DIR="$ADAPTER_DIR"
-elif [ -f "$PROJECT_GITHOOKS/gate-3.sh" ]; then
-  GATE_DIR="$PROJECT_GITHOOKS"
-elif [ -f "$SCRIPT_DIR/gate-3.sh" ]; then
-  GATE_DIR="$SCRIPT_DIR"
-else
+# Gate scripts directory — falls back to project githooks if ADAPTER_DIR doesn't have them.
+# #505: the probe file and the tier order come from the generated data file, so
+# this cascade cannot drift from what doctor.js reports.
+GATE_DIR="$(_hook_resolve_dir "$HOOK_GATE_PROBE" HOOK_GATE_TIERS)" || GATE_DIR=""
+# Deliberate last resort: when no tier carries the gate suite, point at
+# ADAPTER_DIR anyway rather than leaving GATE_DIR empty. The gate-N.sh sources
+# further down check for the file before sourcing, so an absent suite still
+# degrades to a reported skip instead of a path built from an empty string.
+if [ -z "$GATE_DIR" ]; then
   GATE_DIR="$ADAPTER_DIR"
 fi
 
@@ -285,6 +354,104 @@ gate_start_ms() {
   now_ms
 }
 
+# ---------------------------------------------------------------------------
+# #537: per-language coverage classification.
+#
+# A gate that SKIPs tells the reader nothing on its own — "documentation
+# project", "tool not installed" and "nothing changed" are wildly different
+# facts that used to collapse into one word. A PowerShell-primary repo could
+# therefore look fully covered while 3.3k lines were measured by nothing.
+#
+# classify_coverage_reason REASON GATE_STATUS
+#   -> covered | not_applicable | no_changes | tool_missing | unknown
+#
+# FAIL CLOSED: an unrecognised reason is `unknown`, never `covered`. `covered`
+# is reachable ONLY by a gate that actually passed (PASS / WARN /
+# PASS_WITH_WARNINGS) with no skip reason attached.
+# ---------------------------------------------------------------------------
+classify_coverage_reason() {
+  local reason="${1:-}"
+  local gate_status="${2:-}"
+
+  case "$reason" in
+    documentation_project)        echo "not_applicable" ;;
+    architecture_skip_exemption)  echo "not_applicable" ;;
+    no_source_files_changed)      echo "no_changes" ;;
+    # Gate 4 names the same concept "no_matching_files_changed"; Gate 3/6 use
+    # the shorter form. Both mean "the tool exists, nothing to look at".
+    no_matching_files_changed)    echo "no_changes" ;;
+    tool_missing|tool_not_installed|no_powershell_tool|no_archlint_detector|checker_not_found)
+                                  echo "tool_missing" ;;
+    # archlint / import-linter / arch-go / Java arch tests exist as concepts but
+    # this repo carries no config for the language, so nothing was measured.
+    architecture_not_configured)  echo "tool_missing" ;;
+    # Gate 4's checker ran but crashed. Not covered, not "tool missing" — the
+    # measurement was attempted and failed, so the honest answer is unknown.
+    checker_execution_error)      echo "unknown" ;;
+    "")
+      case "$gate_status" in
+        PASS|WARN|PASS_WITH_WARNINGS|PASSED) echo "covered" ;;
+        *) echo "unknown" ;;
+      esac
+      ;;
+    *) echo "unknown" ;;
+  esac
+}
+
+# #537: record where the language key set came from. PROJECT_LANGS is derived
+# from the CURRENTLY CHANGED files, not from a static inventory of the repo, so
+# a docs-only commit legitimately yields an empty set. Reporting the matrix
+# without this provenance would repeat the sin the matrix exists to fix.
+resolve_languages_source() {
+  local override_langs="${1:-}"
+  local config_langs="${2:-}"
+  local resolved_langs="${3:-}"
+  if [ -n "$override_langs" ]; then
+    echo "override"
+  elif [ -n "$config_langs" ]; then
+    echo "config"
+  elif [ -n "$resolved_langs" ]; then
+    echo "changed_files"
+  else
+    echo "none"
+  fi
+}
+
+# #537: resolve Gate 6's reason for ONE language.
+#
+# Reads the flattened GATE_6_LANG_REASONS ("lang=reason,lang=reason") because
+# the associate array that produced it is function-local to the gate and
+# invisible to generate_quality_report().
+#
+# The scalar GATE_6_REASON is a SUMMARY across languages and must NOT be used
+# as a per-language fallback when per-language detail exists: with langs
+# "typescript iac" where only iac lacks a detector, the scalar reads
+# no_archlint_detector and would relabel typescript — the exact language
+# archlint had just measured. A real probe run exposed this:
+#   langs=[typescript iac] reasons=[iac=no_archlint_detector]
+#
+# So: an explicit pair wins; otherwise there is no skip reason for this
+# language, and "no reason" + PASS status is precisely what `covered` means.
+# The scalar only speaks for every language when there is no detail at all
+# (config-missing / bash<4 paths).
+coverage_g6_reason_for() {
+  local lang="${1:-}"
+  local detail="${GATE_6_LANG_REASONS:-}"
+  local scalar="${GATE_6_REASON:-}"
+  local pairs=",${detail},"
+  local reason=""
+  case "$pairs" in
+    *",${lang}="*)
+      reason="${pairs#*",${lang}="}"
+      reason="${reason%%,*}"
+      ;;
+  esac
+  if [ -z "$reason" ] && [ -z "$detail" ] && [ -n "$scalar" ]; then
+    reason="$scalar"
+  fi
+  echo "$reason"
+}
+
 # Audit helper — records gate execution to .xp-gate/audit.jsonl
 # NEVER blocks commit on failure (try/catch around npx tsx).
 # Usage: record_gate_audit <gate_id> <gate_name> <passed> <issues_found> <start_ms>
@@ -2902,6 +3069,15 @@ else
 
   # Check if architecture config exists (use $PROJECT_ROOT — hook may have cd'd to a subdir via ARCH-03)
   if [ -f "$PROJECT_ROOT/architecture.yaml" ] || [ -f "$PROJECT_ROOT/.architecturerc" ] || [ -f "$PROJECT_ROOT/.archlint.yaml" ]; then
+    # #537: per-language reason bookkeeping. Gate 3/4 are single-language gates
+    # and get away with one scalar reason; Gate 6 loops, so a scalar would lose
+    # information ("TS passed, PS has no detector" cannot be one string).
+    # Bash 4 associative array, with a scalar aggregate for the legacy field.
+    GATE_6_REASON=""
+    GATE_6_LANG_REASONS=""
+    if [ "${BASH_VERSINFO[0]:-0}" -ge 4 ]; then
+      declare -A GATE_6_REASON_BY_LANG=()
+    fi
     # Different architecture tools per language
     for CURRENT_LANG in $PROJECT_LANGS; do
     case "$CURRENT_LANG" in
@@ -2947,6 +3123,8 @@ else
          else
            echo "     ✅ TypeScript architecture validation completed (zero-tolerance mode). no baseline found."
          fi
+         # #537: archlint actually ran here, so there is no skip reason. The
+         # matrix reads an absent reason + PASS status as `covered`.
          ;;
       "python")
         # detect any import-linter carrier (incl. pyproject.toml [tool.importlinter])
@@ -2972,6 +3150,12 @@ else
         else
           echo "     ℹ️  No import-linter config found (.import-linter.yml/.importlinter/[tool.importlinter]) - skipping"
           echo "     ⏭️  SKIPPED - Python architecture validation (no config)"
+          # #537: no config means Python architecture was NOT measured. Without
+          # this the matrix would call it `covered` simply because the branch
+          # recorded nothing — the exact false-confidence the matrix prevents.
+          if [ "${BASH_VERSINFO[0]:-0}" -ge 4 ]; then
+            GATE_6_REASON_BY_LANG["$CURRENT_LANG"]="architecture_not_configured"
+          fi
         fi
         ;;
       "go")
@@ -2988,6 +3172,10 @@ else
         else
           echo "     ℹ️  No arch-go.yaml found - skipping Go architecture"
           echo "     ⏭️  SKIPPED - Go architecture validation (no config)"
+          # #537: same reasoning as the Python branch above.
+          if [ "${BASH_VERSINFO[0]:-0}" -ge 4 ]; then
+            GATE_6_REASON_BY_LANG["$CURRENT_LANG"]="architecture_not_configured"
+          fi
         fi
         ;;
       "java")
@@ -3004,19 +3192,63 @@ else
         else
           echo "     ℹ️  No architecture test files found - skipping"
           echo "     ⏭️  SKIPPED - Architecture validation (no tests)"
+          # #537: no test files means Java architecture was NOT measured.
+          if [ "${BASH_VERSINFO[0]:-0}" -ge 4 ]; then
+            GATE_6_REASON_BY_LANG["$CURRENT_LANG"]="architecture_not_configured"
+          fi
         fi
         ;;
       *)
         echo "     ℹ️  Architecture validation not configured for $CURRENT_LANG"
         echo "     ⏭️  SKIPPED - Architecture validation (not configured for $CURRENT_LANG)"
+        # #537: archlint ships no detector for this language. Say so in a way
+        # the quality report can read, instead of leaving the dimension silent.
+        if [ "${BASH_VERSINFO[0]:-0}" -ge 4 ]; then
+          GATE_6_REASON_BY_LANG["$CURRENT_LANG"]="no_archlint_detector"
+        fi
         ;;
     esac
     done  # end for CURRENT_LANG (architecture)
+
+    # #537: fold the per-language reasons into the legacy scalar. Homogeneous
+    # reasons survive as-is; a genuine mix becomes the `mixed` sentinel, which
+    # classify_coverage_reason() maps to `unknown` (fail closed) rather than
+    # pretending one language's verdict covers all of them.
+    #
+    # `declare -A` inside a function is FUNCTION-LOCAL in bash, and the report
+    # is written by generate_quality_report() — a different function. So the
+    # assoc array is flattened into this global string, which the report parses.
+    # (Found by running the hook: the matrix reported tool_missing for
+    # typescript because the lookup saw an empty array.)
+    GATE_6_LANG_REASONS=""
+    _g6_seen=""
+    _g6_mixed=0
+    for _g6_lang in $PROJECT_LANGS; do
+      _g6_r=""
+      if [ "${BASH_VERSINFO[0]:-0}" -ge 4 ]; then
+        _g6_r="${GATE_6_REASON_BY_LANG[$_g6_lang]:-}"
+      fi
+      if [ -n "$_g6_r" ]; then
+        GATE_6_LANG_REASONS="${GATE_6_LANG_REASONS:+$GATE_6_LANG_REASONS,}${_g6_lang}=${_g6_r}"
+        if [ -z "$_g6_seen" ]; then
+          _g6_seen="$_g6_r"
+        elif [ "$_g6_seen" != "$_g6_r" ]; then
+          _g6_mixed=1
+        fi
+      fi
+    done
+    if [ "$_g6_mixed" = "1" ]; then
+      GATE_6_REASON="mixed"
+    else
+      GATE_6_REASON="$_g6_seen"
+    fi
   else
     # Architecture config is REQUIRED — BLOCK if missing
     if [ -f "$PROJECT_ROOT/.architecture-skip" ]; then
       echo "     ⚠️  Architecture config missing but .architecture-skip present — allowed to skip"
       echo "     ⏭️  SKIPPED - Architecture validation (.architecture-skip exemption)"
+      # #537: an explicit exemption is "not applicable", not "tool missing".
+      GATE_6_REASON="architecture_skip_exemption"
     else
       echo ""
       echo "❌ ARCHITECTURE CONFIG MISSING - COMMIT BLOCKED"
@@ -3133,7 +3365,14 @@ else
     echo "     ⏭️  SKIPPED - Boy Scout Rule (not available in project)"
   fi
 fi
-GATE_6_STATUS="PASS"
+# A PASS here must mean 'the checks ran and found nothing'. The two
+# branches above print 'SKIPPED - not configured/available'; stamping PASS
+# after them turned 'nothing was checked' into a scored success.
+if [ -n "${GATE_6_STATUS:-}" ]; then
+  : # a branch that really ran already decided the verdict
+else
+  GATE_6_STATUS="SKIP"
+fi
 record_gate_audit "gate-6" "architecture-boy-scout" "$GATE_6_STATUS" "${BS_BLOCKED:-0}" "$GATE_6_START"
 
 # ============================================================================
@@ -3490,7 +3729,10 @@ generate_quality_report() {
     # applicable" and must render and score identically. A previous scoring
     # default of FAIL produced self-contradictory reports -- the gate showed
     # PASS in JSON but scored as FAIL (#507 Delphi round-1 A-MAJOR-2).
-    if [ "$gate" -eq 12 ]; then gate_default="WARN"; else gate_default="PASS"; fi
+    # Default direction is "did not run", never "passed": an unassigned status
+    # is a gate that never reached a verdict, and scoring it PASS both claims a
+    # success that did not happen and hides the gap in the effective rate.
+    if [ "$gate" -eq 12 ]; then gate_default="WARN"; else gate_default="SKIP"; fi
     gate_status="${!status_var:-$gate_default}"
     case "$gate_status" in
       PASS) PASSED_COUNT=$((PASSED_COUNT + 1)) ;;
@@ -3563,6 +3805,37 @@ generate_quality_report() {
   local REPORT_FILE="${STATUS_DIR}/${BRANCH}.json"
   mkdir -p "$(dirname "$REPORT_FILE")"
 
+  # ── #537: per-language coverage matrix ───────────────────────────────────────
+  # Answers "was this dimension actually measured for this language?" instead of
+  # letting every SKIP read as a pass. Built by whitelist splicing (the same
+  # technique as DEGRADED_JSON above) rather than jq, because jq is an OPTIONAL
+  # dependency here (see the `command -v jq` guard earlier in this file) and a
+  # missing jq must not silently cost us the whole matrix.
+  #
+  # Safety: every spliced value is one of the five enum literals below — no
+  # quotes, backslashes or newlines can reach the JSON. Language names are
+  # whitelisted too, and a name that fails the whitelist is reported in
+  # coverageWarnings instead of being silently dropped.
+  local COVERAGE_MATRIX_JSON=""
+  local COVERAGE_WARNINGS_JSON=""
+  local _cm_lang _cm_g3 _cm_g4 _cm_g6 _cm_entry
+  for _cm_lang in $PROJECT_LANGS; do
+    if ! echo "$_cm_lang" | grep -qE '^[a-z][a-z0-9+]*$'; then
+      COVERAGE_WARNINGS_JSON="${COVERAGE_WARNINGS_JSON:+$COVERAGE_WARNINGS_JSON, }\"unsupported_language_name\""
+      continue
+    fi
+    _cm_g3=$(classify_coverage_reason "${GATE_3_REASON:-}" "${GATE_3_STATUS:-PASS}")
+    _cm_g4=$(classify_coverage_reason "${GATE_4_REASON:-}" "${GATE_4_STATUS:-PASS}")
+    # Gate 6 reason for this language — extracted so the rule is testable
+    # rather than inlined (see coverage_g6_reason_for below).
+    _cm_g6_reason=$(coverage_g6_reason_for "$_cm_lang")
+    _cm_g6=$(classify_coverage_reason "$_cm_g6_reason" "${GATE_6_STATUS:-SKIP}")
+    _cm_entry="\"${_cm_lang}\": {\"gate3_complexity\": \"${_cm_g3}\", \"gate4_principles\": \"${_cm_g4}\", \"gate6_architecture\": \"${_cm_g6}\"}"
+    COVERAGE_MATRIX_JSON="${COVERAGE_MATRIX_JSON:+$COVERAGE_MATRIX_JSON, }${_cm_entry}"
+  done
+  local LANGUAGES_SOURCE
+  LANGUAGES_SOURCE=$(resolve_languages_source "${_RESOLVED_LANG_OVERRIDE:-}" "${_CONFIG_LANGS:-}" "${PROJECT_LANGS:-}")
+
   cat > "$REPORT_FILE" << ENDJSON
 {
   "reportVersion": "2.0",
@@ -3581,6 +3854,9 @@ generate_quality_report() {
     "score": $SCORE_JSON,
     "verdict": "$VERDICT"
   },
+  "languagesSource": "${LANGUAGES_SOURCE}",
+  "coverageMatrix": {${COVERAGE_MATRIX_JSON}},
+  "coverageWarnings": [${COVERAGE_WARNINGS_JSON}],
   "gates": {
     "gate1_static_analysis": {
       "name": "Code Quality (Static + Lint + Shell)",
@@ -3589,7 +3865,7 @@ generate_quality_report() {
     },
     "gate2_dup_code": {
       "name": "Duplicate Code",
-      "status": "${GATE_2_STATUS:-PASS}",
+      "status": "${GATE_2_STATUS:-SKIP}",
       "metric": "similarity <= 5%"
     },
     "gate3_complexity": {
@@ -3615,7 +3891,8 @@ generate_quality_report() {
     },
     "gate6_arch_boyscout": {
       "name": "Architecture + Boy Scout Rule",
-      "status": "${GATE_6_STATUS:-PASS}",
+      "status": "${GATE_6_STATUS:-SKIP}",
+      "reason": "${GATE_6_REASON:-}",
       "boyScoutPassed": $BS_PASSED,
       "boyScoutBlocked": $BS_BLOCKED
     },
@@ -3667,11 +3944,11 @@ ENDJSON
   # ── History append (unchanged — append-only for trend) ────────────────────────────
   local GATES_JSON="{"
   GATES_JSON="${GATES_JSON}\"gate1\":{\"status\":\"${GATE_1_STATUS:-PASS}\",\"name\":\"Code Quality\"},"
-  GATES_JSON="${GATES_JSON}\"gate2\":{\"status\":\"${GATE_2_STATUS:-PASS}\",\"name\":\"Duplicate Code\"},"
+  GATES_JSON="${GATES_JSON}\"gate2\":{\"status\":\"${GATE_2_STATUS:-SKIP}\",\"name\":\"Duplicate Code\"},"
   GATES_JSON="${GATES_JSON}\"gate3\":{\"status\":\"${GATE_3_STATUS:-PASS}\",\"name\":\"Complexity\",\"warnings\":${CC_WARNINGS:-0}},"
   GATES_JSON="${GATES_JSON}\"gate4\":{\"status\":\"${GATE_4_STATUS:-PASS}\",\"name\":\"Principles\",\"warnings\":${WARNING_COUNT:-0}},"
   GATES_JSON="${GATES_JSON}\"gate5\":{\"status\":\"${GATE_5_STATUS:-PASS}\",\"name\":\"Tests+Coverage\",\"coverage\":\"${COV_PCT}\"},"
-  GATES_JSON="${GATES_JSON}\"gate6\":{\"status\":\"${GATE_6_STATUS:-PASS}\",\"name\":\"Architecture+BoyScout\",\"bsBlocked\":${BS_BLOCKED}},"
+  GATES_JSON="${GATES_JSON}\"gate6\":{\"status\":\"${GATE_6_STATUS:-SKIP}\",\"name\":\"Architecture+BoyScout\",\"bsBlocked\":${BS_BLOCKED}},"
   GATES_JSON="${GATES_JSON}\"gate7\":{\"status\":\"${GATE_7_STATUS:-PASS}\",\"name\":\"IaC Security\"},"
   GATES_JSON="${GATES_JSON}\"gate8\":{\"status\":\"${GATE_8_STATUS:-PASS}\",\"name\":\"Secret Scanning\"},"
   GATES_JSON="${GATES_JSON}\"gate9\":{\"status\":\"${GATE_9_STATUS:-PASS}\",\"name\":\"Build Integrity\"},"
@@ -3688,11 +3965,11 @@ ENDJSON
   echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
   echo ""
   printf "  %-45s %s\n" "Gate 1: Code Quality" "${GATE_1_STATUS:-PASS}"
-  printf "  %-45s %s\n" "Gate 2: Duplicate Code" "${GATE_2_STATUS:-PASS}"
+  printf "  %-45s %s\n" "Gate 2: Duplicate Code" "${GATE_2_STATUS:-SKIP}"
   printf "  %-45s %s (warnings: ${CC_WARNINGS:-0})\n" "Gate 3: Complexity" "${GATE_3_STATUS:-PASS}"
   printf "  %-45s %s (warnings: ${WARNING_COUNT:-0})\n" "Gate 4: Principles" "${GATE_4_STATUS:-PASS}"
   printf "  %-45s %s (coverage: ${COV_PCT}%%)\n" "Gate 5: Tests + Coverage" "${GATE_5_STATUS:-PASS}"
-  printf "  %-45s %s\n" "Gate 6: Architecture + Boy Scout" "${GATE_6_STATUS:-PASS}"
+  printf "  %-45s %s\n" "Gate 6: Architecture + Boy Scout" "${GATE_6_STATUS:-SKIP}"
   printf "  %-45s %s\n" "Gate 7: IaC Security" "${GATE_7_STATUS:-PASS}"
   printf "  %-45s %s\n" "Gate 8: Secret Scanning" "${GATE_8_STATUS:-PASS}"
   printf "  %-45s %s\n" "Gate 9: Build Integrity" "${GATE_9_STATUS:-PASS}"

package/hooks/pre-push

@@ -51,7 +51,7 @@ report = {
   'gates': [
     {'id': 'MP', 'name': 'Gate-Script Mirror Parity', 'status': '${GATE_MP_STATUS:-SKIP}', 'details': {'duration_ms': '${MP_DURATION_MS:-0}'}},
     {'id': '10', 'name': 'Build Integrity', 'status': '${GATE_10_STATUS:-SKIP}', 'details': {}},
-    {'id': 'M', 'name': 'Mutation Testing', 'status': '${GATE_M_STATUS:-SKIP}', 'details': {}},
+    {'id': 'M', 'name': 'Mutation Testing', 'status': '${GATE_M_STATUS:-SKIP}', 'details': {'skip_reason': '${GATE_M_SKIP_REASON:-}', 'duration_ms': '${M_DURATION_MS:-0}', 'mutation_score': '${M_SCORE:-}'}},
     {'id': 'M-Python', 'name': 'Mutation Testing (Python)', 'status': '${GATE_M_PYTHON_STATUS:-SKIP}', 'details': {}},
     {'id': 'M-Go', 'name': 'Mutation Testing (Go)', 'status': '${GATE_M_GO_STATUS:-SKIP}', 'details': {}},
     {'id': 'M-Java', 'name': 'Mutation Testing (Java)', 'status': '${GATE_M_JAVA_STATUS:-SKIP}', 'details': {}},
@@ -373,16 +373,22 @@ fi
 # shellcheck source=githooks/adapter-common.sh
 source "$ADAPTER_COMMON" 2>/dev/null || {
   echo "⚠️ Could not source adapter-common.sh. SKIP — Gate M."
+  GATE_M_SKIP_REASON="adapter-common.sh could not be sourced"
 }
 
-# Only run for TypeScript projects
+# #404 P0: every Gate M skip records WHY. Without this the journals carried
+# `details: {}` on 62 of 68 runs, so the RFC's "SKIP rate" question was
+# unanswerable — a missing tool and "no mutable file in this push" are opposite
+# findings that looked identical after the fact.
 if [[ ! -f "package.json" ]] || [[ ! -f "tsconfig.json" ]]; then
   echo "📚 Not a TypeScript project. SKIP — Gate M."
+  GATE_M_SKIP_REASON="not a TypeScript project (package.json+tsconfig.json required)"
 else
   # Check if mutation testing is configured
   if ! detect_mutation_testable 2>/dev/null; then
     echo "⚠️ Stryker config not found or @stryker-mutator not installed."
     echo "   SKIP — Gate M mutation testing."
+    GATE_M_SKIP_REASON="stryker config missing or @stryker-mutator not installed"
   else
     # Filter to source files (exclude tests). The tree-segment grep excludes
     # test infrastructure (helpers/fixtures under tests/, test/, __tests__/)
@@ -392,6 +398,7 @@ else
 
     if [ -z "$CHANGED_SOURCE_FILES" ]; then
       echo "📚 No changed TypeScript source files. SKIP — Gate M."
+      GATE_M_SKIP_REASON="no changed TypeScript source files in this push"
     else
       echo "🧬 Running mutation tests on changed files..."
       echo "$CHANGED_SOURCE_FILES"
@@ -408,15 +415,28 @@ else
 
       if [[ -z "$MUTATION_SCRIPT" ]]; then
         echo "⚠️ Gate M script not found. SKIP — Gate M."
+        GATE_M_SKIP_REASON="gate-m.ts not found in .xp-gate/modules, src/mutation, or global modules"
       else
         # Run mutation gate with timeout matching stryker.conf.json (timeoutMS: 600000 = 10min)
         MUTATION_OUTPUT=$(mktemp)
+        M_START_MS=$(date +%s%3N 2>/dev/null || python -c 'import time;print(int(time.time()*1000))' 2>/dev/null || echo 0)
         RUN_TSX_TIMEOUT=600s run_tsx $MUTATION_SCRIPT --changed-files "$CHANGED_SOURCE_FILES" > "$MUTATION_OUTPUT" 2>&1
         MUTATION_EXIT=$?
+        M_END_MS=$(date +%s%3N 2>/dev/null || python -c 'import time;print(int(time.time()*1000))' 2>/dev/null || echo 0)
+        if [ "$M_START_MS" != "0" ] && [ "$M_END_MS" != "0" ]; then
+          M_DURATION_MS=$((M_END_MS - M_START_MS))
+          [ "$M_DURATION_MS" -ge 0 ] || M_DURATION_MS=0
+        else
+          M_DURATION_MS=0
+        fi
+        # #404: the mutation score is the number the RFC wants a distribution for.
+        # It is printed by gate-m.ts; take the last percentage it reported.
+        M_SCORE=$(sed -n 's/.*[Mm]utation score[: ]*\([0-9][0-9]*\(\.[0-9][0-9]*\)\?\)%.*/\1/p' "$MUTATION_OUTPUT" 2>/dev/null | tail -1)
 
         case $MUTATION_EXIT in
           0)
             echo "✅ Gate M: PASS"
+            GATE_M_STATUS="PASS"
             # Update baseline after successful mutation test
             if [ -f ".stryker-baseline.json" ]; then
               echo "📝 Updating mutation baseline..."
@@ -437,11 +457,15 @@ else
           124)
             echo "⏱️ Gate M: TIMEOUT (120s). Mutation testing incomplete."
             echo "   Allowing push with warning — review mutation coverage manually."
+            GATE_M_STATUS="TIMEOUT"
+            GATE_M_SKIP_REASON="mutation run exceeded the 600s timeout; score is unknown"
             ;;
           *)
             echo "⚠️ Gate M: Unexpected exit code $MUTATION_EXIT"
             cat "$MUTATION_OUTPUT"
             echo "   Allowing push with warning."
+            GATE_M_STATUS="WARN"
+            GATE_M_SKIP_REASON="gate-m.ts exited $MUTATION_EXIT (unexpected); score is unknown"
             ;;
         esac