@boyingliu01/xp-gate 0.27.6 → 0.28.1

package/hooks/lib/ccn-ratchet.sh

@@ -0,0 +1,183 @@
+#!/bin/bash
+# ============================================================================
+# ccn-ratchet.sh — Gate 3 baseline ratchet (sprint-20261018-quality REQ-D)
+#
+# The repo carries years of complex-but-alive functions. Blocking them today
+# would freeze the codebase; ignoring them lets complexity grow silently. The
+# ratchet splits the difference: .ccn-baseline.json records the CCN each
+# known function has TODAY, and the gate only fires when a recorded function
+# gets WORSE (strictly greater — equal passes). Functions with no entry are
+# new code and face the live warn/block thresholds unchanged. When a function
+# improves we say so and suggest refreshing the baseline, because a stale
+# ceiling invites nobody to finish the job.
+#
+# Key = "<relative/path>::<functionName>". Rename or move = new key = treated
+# as a new function. That is deliberate: fuzzy matching would hide debt moves.
+# `node scripts/ccn-report.cjs --write-baseline` regenerates the file after a
+# legitimate refactor.
+#
+# evaluate_ccn_ratchet <baseline-json> reads lizard --csv rows on stdin and
+# prints "OK|WARN|BLOCK|LOWER <fn> ..." verdict lines for every function row.
+# ============================================================================
+
+# Convert lizard CSV rows to unit-separator-delimited fields.
+#
+# The CSV is only ever parsed once, here, with the quote rules written out in
+# one place; downstream code then reads positional fields with no quoting to
+# worry about. gawk arrays are pass-by-value, so a helper function CANNOT fill
+# a caller-visible array, and `split($0, F, ",")` tears apart lizard's quoted
+# signature column (signatures contain commas). Both of those were live bugs:
+# every lookup fell through to the "new function" branch, so recorded
+# functions were graded against the flat threshold instead of their baseline.
+#
+# Output columns (this is real lizard 1.21.3 --csv output, 11 columns):
+#   1 NLOC, 2 CCN, 3 token_len, 4 param_count, 5 48 (location size),
+#   6 fn@start-end@path, 7 path, 8 name, 9 signature, 10 start, 11 end
+#
+# The separator is ASCII Unit Separator written via sprintf so the byte never
+# has to survive a shell/awk escape round trip: -F'\001' is NOT a reliable way
+# to name a control character (gawk treats the argument as a regex, and the
+# literal backslash path silently yields a separator that matches nothing, so
+# every row is read as a single field).
+CSV_FS=$'\x1f'
+
+csv_to_unit_separated() {
+  awk '
+    function emit(line,   cur, i, ch, q, nf) {
+      nf = 1; cur = ""; q = 0
+      for (i = 1; i <= length(line); i++) {
+        ch = substr(line, i, 1)
+        if (q) {
+          if (ch == "\"") { if (substr(line, i + 1, 1) == "\"") { cur = cur "\""; i++ } else q = 0 }
+          else cur = cur ch
+        } else if (ch == "\"") q = 1
+        else if (ch == ",") { f[nf++] = cur; cur = "" }
+        else cur = cur ch
+      }
+      f[nf] = cur
+      out = f[1]
+      for (i = 2; i <= nf; i++) out = out FS_OUT f[i]
+      print out
+    }
+    # Build the 0x1F byte from its numeric code: shell escapes into awk strings
+    # are fragile across gawk/mawk/Windows builds, but printf to an awk variable
+    # is unambiguous.
+    BEGIN { FS_OUT = sprintf("%c", 0x1F) }
+    { emit($0) }
+  '
+}
+
+evaluate_ccn_ratchet() {
+  local baseline_file="$1"
+  local warn_threshold="${CCN_WARN_THRESHOLD:-5}"
+  local block_threshold="${CCN_BLOCK_THRESHOLD:-10}"
+
+  # Capture stdin up front: it is consumed twice (baseline rows and verdicts).
+  local awk_input
+  awk_input=$(cat)
+
+  local baseline_json=""
+  if [ -f "$baseline_file" ]; then
+    baseline_json=$(cat "$baseline_file")
+  fi
+
+  # Flatten {"path::fn": 12, ...} to "path::fn=12" lines without spawning a
+  # JSON parser per commit (every spawn is expensive on Windows AV filters).
+  local flat
+  flat=$(printf '%s' "$baseline_json" \
+    | tr -d '\n' \
+    | sed 's/^[^{]*{//; s/}[^}]*$//' \
+    | grep -oE '"[^"]+"[[:space:]]*:[[:space:]]*[0-9]+' \
+    | sed 's/[[:space:]]//g; s/":/=/; s/"//g' || true)
+
+  # An empty or unparseable baseline must not read as "everything is new code,
+  # nothing is protected". `{}` and a truncated file both flatten to zero lines,
+  # and the grader then silently degrades to flat thresholds for a repository
+  # that explicitly opted into the ratchet. Say so on stderr (verdict lines stay
+  # clean for the caller) rather than passing quietly — the caller decides
+  # whether an empty baseline is fatal, but it must be able to tell.
+  if [ -z "$flat" ]; then
+    echo "WARN - complexity baseline '${baseline_file}' is empty or unparseable; grading against flat thresholds only (no function is protected by the ratchet)" >&2
+  fi
+
+  # Convert the CSV rows once into position-only fields, then grade them. The
+  # CSV quote rules live in csv_to_unit_separated and nowhere else; see the
+  # comment there for why parsing in-place inside awk does not work.
+  # Columns: $1 NLOC, $2 CCN, $3 token_len, $4 param_count, $5 location size,
+  #          $6 fn@start-end@path, $7 path, $8 name, $9 signature,
+  #          $10 start, $11 end
+  local csv_rows
+  csv_rows=$(printf '%s\n' "$awk_input" | csv_to_unit_separated || true)
+
+  # Only function rows survive the conversion with a numeric CCN, which is what
+  # the $2 guard below keys on.
+  #
+  # Duplicate-name tally: baselineKey() in scripts/ccn-report.cjs keys a name by
+  # line when it occurs more than once in a file, because two rows can otherwise
+  # share one entry and each regresses against the other. The rule is mirrored
+  # here so the hook and CI cannot disagree; the count is computed in shell
+  # because awk cannot see the whole file before grading its first row.
+  local dup_names
+  dup_names=$(printf '%s\n' "$csv_rows" | awk -F"$CSV_FS" '
+    $2 ~ /^[0-9]+$/ {
+      n = split($6, p, "@")
+      name = p[1]
+      path = (n >= 3) ? p[n] : $7
+      gsub(/\\/, "/", path)
+      count[path "::" name]++
+    }
+    END {
+      for (k in count) if (count[k] > 1) print k
+    }
+  ' || true)
+
+  printf '%s\n' "$csv_rows" | awk -F"$CSV_FS" -v flat="$flat" -v warn="$warn_threshold" -v block="$block_threshold" -v dups="$dup_names" -v anon_marker="(anonymous)" -v anon_short="(anon)" '
+    BEGIN {
+      n = split(flat, kv, "\n")
+      for (i = 1; i <= n; i++) {
+        eq = index(kv[i], "=")
+        if (eq > 0) base[substr(kv[i], 1, eq - 1)] = substr(kv[i], eq + 1) + 0
+      }
+      m = split(dups, duprow, "\n")
+      for (i = 1; i <= m; i++) if (length(duprow[i]) > 0) dup[duprow[i]] = 1
+    }
+    # FIELD INDEXING: $1 NLOC, $2 CCN, $3 token_len, $4 param_count,
+    # $5 location size, $6 fn@start-end@path, $7 path, $8 name,
+    # $9 signature, $10 start, $11 end.
+    # Those two lines are the entire column contract. Earlier revisions read
+    # CCN out of the identity column and name/path out of a shifted column, so
+    # nothing ever matched its baseline entry and every recorded function was
+    # graded as new code against the flat thresholds.
+    # NOTE: this awk program is single-quoted in shell. The two hazards that
+    # silently broke earlier revisions: an apostrophe anywhere below, and a
+    # bare double-quote pair that the shell re-pairs across the awk text. The
+    # anonymous marker is therefore passed in as a -v value, not written inline.
+    $2 ~ /^[0-9]+$/ {
+      ccn = $2 + 0
+      n2 = split($6, parts, "@")
+      name = parts[1]
+      path = (n2 >= 3) ? parts[n2] : $7
+      gsub(/\\/, "/", path)
+      # Anonymous callbacks are keyed by position: a file holds many of them and
+      # the baseline would otherwise keep only the last one parsed, so every
+      # other callback was graded against the number of a different function.
+      is_anon = 0
+      if (name == anon_marker) is_anon = 1
+      if (name == anon_short) is_anon = 1
+      start = (n2 >= 3) ? parts[2] : $10
+      sub(/-.*/, "", start)
+      key = path "::" name
+      if (is_anon) key = path "::" anon_marker "@" start
+      else if ((path "::" name) in dup) key = path "::" name "@" start
+      if (key in base) {
+        if (ccn > base[key])      printf "BLOCK %s CCN=%d baseline=%d (ratchet: worse than recorded)\n", name, ccn, base[key]
+        else if (ccn < base[key]) printf "LOWER %s CCN=%d baseline=%d (improved — refresh baseline when convenient)\n", name, ccn, base[key]
+        else                      printf "OK %s CCN=%d at baseline\n", name, ccn
+      } else {
+        if (ccn > block)     printf "BLOCK %s CCN=%d (%s exceeds block threshold)\n", name, ccn, path
+        else if (ccn > warn) printf "WARN %s CCN=%d (%s new/over warn threshold)\n", name, ccn, path
+        else                 printf "OK %s CCN=%d\n", name, ccn
+      }
+    }
+  '
+}

package/hooks/lib/docs-only.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# ============================================================================
+# docs-only.sh — commit-level documentation-only detection (REQ-F2)
+#
+# The pre-commit hook already knows about PROJECT-level documentation repos
+# (PROJECT_LANG=documentation-only: the repo has no code files at all). This
+# is the COMMIT-level sibling: xp-gate's own docs churn — typo fixes, changelog
+# entries, plan docs — used to pay the full ~46s gate bill even though tests,
+# jscpd, tsc and file hygiene cannot observe a markdown edit. When every
+# staged file is documentation, those heavy gates SKIP with reason
+# docs_only_change; light gates (secrets, version, principles) still run.
+#
+# Fail-closed by construction: an empty list or any single non-matching path
+# prints "false" and the gates run as before.
+#
+# detect_docs_only_commit reads newline-separated staged paths on stdin and
+# prints true|false.
+# ============================================================================
+
+detect_docs_only_commit() {
+  local f ext saw=0
+  while IFS= read -r f || [ -n "$f" ]; do
+    [ -n "$f" ] || continue
+    saw=1
+    # Any recognizable source extension is code, wherever it lives — a .ts
+    # under docs/ (sample snippets, doc tooling) still deserves its gates.
+    ext="${f##*.}"
+    case "$ext" in
+      ts|tsx|js|jsx|mjs|cjs|py|go|java|kt|kts|swift|cpp|cc|c|h|hpp|m|mm|rs|rb|php|cs|dart|sh|bash|ps1|psm1)
+        printf 'false'
+        return 0
+        ;;
+    esac
+    case "$f" in
+      *.md|*.mdx|*.rst|*.txt|*.adoc) continue ;;
+      docs/*|docs-*/**|.github/ISSUE_TEMPLATE/**) continue ;;
+      *)
+        printf 'false'
+        return 0
+        ;;
+    esac
+  done
+  if [ "$saw" = 1 ]; then
+    printf 'true'
+    return 0
+  fi
+  printf 'false'
+  return 0
+}

package/hooks/pre-commit

@@ -243,6 +243,12 @@ source_gate_lib() {
 
 # Issue #370: source cross-platform now_ms() helper (node-preferred, regex-validated)
 source_gate_lib "${AUDIT_SCRIPT_DIR}/lib/now-ms.sh"
+# REQ-B: duration bookkeeping sanitizer used by record_gate_audit below.
+source_gate_lib "${AUDIT_SCRIPT_DIR}/lib/audit-sanitize.sh"
+# REQ-F2 (sprint-20261018-quality): commit-level docs-only detection used to
+# short-circuit the heavy, code-blind gates below. Distinct from the
+# PROJECT-level documentation_project detection further down.
+source_gate_lib "${AUDIT_SCRIPT_DIR}/lib/docs-only.sh"
 
 # Issue #473 (+ #454): Gate 5's vitest exit-code judgement, sourced as a library
 # so the fail-closed contract is unit-testable without executing this hook.
@@ -293,16 +299,33 @@ record_gate_audit() {
   local detail="${6:-}"
   local end_ms
   end_ms=$(now_ms)
-  local duration_ms=$((end_ms - start_ms))
-  if [ "$duration_ms" -lt 0 ] 2>/dev/null; then
-    duration_ms=0
+  # REQ-B: sanitize BEFORE subtracting. A poisoned start (empty -> arithmetic
+  # 0, or a seconds-unit value from an old code path) used to survive as an
+  # epoch-sized duration_ms that only the anomaly flag papered over. Now the
+  # record carries null + reason so every consumer can exclude it honestly.
+  local clean_start duration_reason=""
+  clean_start=$(sanitize_start "$start_ms")
+  local duration_ms
+  if [ "$clean_start" = "null" ]; then
+    duration_ms="null"
+    duration_reason="poisoned_start_ms"
+  else
+    duration_ms=$((end_ms - clean_start))
+    if [ "$duration_ms" -lt 0 ] 2>/dev/null; then
+      duration_ms="null"
+      duration_reason="clock_skew"
+    fi
   fi
 
   # Issue #370: detect anomalous duration (poisoned timestamp arithmetic)
   local duration_anomaly_flag=""
-  if [ "$duration_ms" -gt "$_MAX_DURATION_MS" ] 2>/dev/null; then
+  if [ "$duration_ms" != "null" ] && [ "$duration_ms" -gt "$_MAX_DURATION_MS" ] 2>/dev/null; then
     duration_anomaly_flag="--duration-anomaly true"
   fi
+  local duration_reason_flag=""
+  if [ -n "$duration_reason" ]; then
+    duration_reason_flag="--duration-reason $duration_reason"
+  fi
 
   # Determine gate result: PASS or FAIL based on status variable
   local gate_result="true"
@@ -312,13 +335,14 @@ record_gate_audit() {
 
   # Fire-and-forget: audit must never block the commit
   {
-    npx tsx "${PROJECT_ROOT_FOR_AUDIT}/src/npm-package/lib/gate-audit.ts" record \
+    run_tsx "${PROJECT_ROOT_FOR_AUDIT}/src/npm-package/lib/gate-audit.ts" record \
       --gate-id "$gate_id" \
       --gate-name "$gate_name" \
       --passed "$gate_result" \
       --issues-found "$issues_found" \
       --duration-ms "$duration_ms" \
       $duration_anomaly_flag \
+      $duration_reason_flag \
       --trigger commit \
       ${detail:+--detail "$detail"} \
       2>/dev/null
@@ -538,6 +562,14 @@ DASHBOARD_PATH_FILTER='^dashboard/'
 RAW_CHANGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
 CHANGED_FILES=$(printf '%s\n' "$RAW_CHANGED_FILES" | grep -v "$MIRROR_PATH_FILTER" | grep -v "$DASHBOARD_PATH_FILTER" || true)
 
+# REQ-F2: one commit-level docs-only verdict, computed once and reused by the
+# heavy gates (2/5/9/12). Light gates never consult it — a secret in a README
+# is still a secret.
+DOCS_ONLY_COMMIT=false
+if printf '%s\n' "$CHANGED_FILES" | detect_docs_only_commit | grep -q '^true$'; then
+  DOCS_ONLY_COMMIT=true
+fi
+
 if [ -z "$RAW_CHANGED_FILES" ]; then
   echo "No files changed. Skipping gates."
   exit 0
@@ -1031,14 +1063,24 @@ fi
 # ============================================================================
  2>&1 echo ""
  2>&1 echo "→ Gate 1: Code Quality (static analysis + linting)..."
+# REQ-B: the start stamp is taken OUTSIDE the branches below. It used to be
+# assigned only on the lint path, so every skipped Gate 1 recorded an empty
+# GATE_1_START -> duration_ms=null with reason=poisoned_start_ms. That null is
+# honest but it answers the wrong question: those commits never ran the gate, so
+# the log should say SKIP, not "measurement failed".
+GATE_1_START=$(gate_start_ms)
+GATE_1_STATUS="PASS"
+GATE_1_DETAIL=""
 if ! any_changed_files_match "\.(ts|tsx|js|jsx|py|go|java|kt|cpp|c|swift|m|mm|dart|sh)$" "\.ya?ml$" "\.json$" "Dockerfile" "\.tf$"; then
   echo "✅ PASSED - No code files changed, skipping lint."
+  GATE_1_STATUS="SKIP"
+  GATE_1_DETAIL="no_matching_files"
 else
-GATE_1_START=$(gate_start_ms)
-
 if [ "$PROJECT_LANG" = "documentation-only" ]; then
   # Documentation-only project - skip static analysis
   echo "⏭️  SKIPPED - Code quality (documentation project)."
+  GATE_1_STATUS="SKIP"
+  GATE_1_DETAIL="documentation_project"
   
 else
   for CURRENT_LANG in $PROJECT_LANGS; do
@@ -1596,7 +1638,6 @@ GATE_1_TOOL="${PROJECT_LANGS}"
 # trail via the S2 detail plumbing so a WARN verdict is diagnosable, not
 # silent. WARN stays IN the scoring denominator (Delphi round-2 A-MAJOR-1).
 record_gate_audit "gate-1" "code-quality" "$GATE_1_STATUS" "0" "$GATE_1_START" "${GATE_1_DETAIL:-}"
-
 # ============================================================================
 # GATE 2: Duplicate Code Detection (NEW gate)
 # Uses jscpd, or similar tools, specific to language
@@ -1606,8 +1647,14 @@ record_gate_audit "gate-1" "code-quality" "$GATE_1_STATUS" "0" "$GATE_1_START" "
 GATE_2_START=$(gate_start_ms)
 GATE_2_STATUS="PASS"
 
-if [ "$PROJECT_LANG" = "documentation-only" ]; then
-echo "⏭️  SKIPPED - Duplicate code (documentation project)."
+if [ "$PROJECT_LANG" = "documentation-only" ] || [ "$DOCS_ONLY_COMMIT" = true ]; then
+echo "⏭️  SKIPPED - Duplicate code (documentation-only ${DOCS_ONLY_COMMIT:+commit})."
+GATE_2_STATUS="SKIP"
+ # GATE_2_DETAIL feeds record_gate_audit's detail field. The previous
+ # GATE_2_REASON was assigned and never read by anything, which is worse than
+ # useless: it looks like the skip reason reaches the audit journal when it does
+ # not (no set -u, so nothing complained).
+ GATE_2_DETAIL="docs_only_change"
 
 else
   for CURRENT_LANG in $PROJECT_LANGS; do
@@ -1715,7 +1762,7 @@ else
 fi
 # Set at the top of this gate; a branch may already have marked it SKIP (#477). The
 # audit must record what happened, not what the gate defaults to.
-record_gate_audit "gate-2" "duplicate-code" "$GATE_2_STATUS" "0" "$GATE_2_START"
+record_gate_audit "gate-2" "duplicate-code" "$GATE_2_STATUS" "0" "$GATE_2_START" "${GATE_2_DETAIL:-}"
 
 # ============================================================================
 # GATE 3: Cyclomatic Complexity Check
@@ -1744,8 +1791,10 @@ source "$GATE_DIR/gate-4.sh"
  2>&1 echo "→ Gate 5: Tests & coverage..."
 GATE_5_START=$(gate_start_ms)
 
-if [ "$PROJECT_LANG" = "documentation-only" ]; then
-  echo "✅ PASSED - Skipped (documentation project)."
+if [ "$PROJECT_LANG" = "documentation-only" ] || [ "$DOCS_ONLY_COMMIT" = true ]; then
+  echo "⏭️  SKIPPED - Tests & coverage (documentation-only commit — no code changed to test)."
+  GATE_5_STATUS="SKIP"
+  GATE_5_DETAIL="docs_only_change"
 
 else
   # ========================================================================
@@ -2822,7 +2871,7 @@ else
   fi
 fi
 GATE_5_STATUS="PASS"
-record_gate_audit "gate-5" "tests-coverage" "$GATE_5_STATUS" "0" "$GATE_5_START"
+record_gate_audit "gate-5" "tests-coverage" "$GATE_5_STATUS" "0" "$GATE_5_START" "${GATE_5_DETAIL:-}"
 
 # ============================================================================
 # GATE 6: Architecture & Tech Debt (Combines Old Gate 8 - Boy Scout and Gate 9 - Architecture)
@@ -3183,7 +3232,17 @@ GATE_9_TS_STATUS="SKIP"
 GATE_9_JAVA_STATUS="SKIP"
 GATE_9_STATUS="SKIP"
 
-if [ -f "package.json" ] && [ -f "tsconfig.json" ]; then
+if [ "$DOCS_ONLY_COMMIT" = true ]; then
+  # REQ-F2: tsc cannot observe a markdown edit. The commit-level docs-only
+  # verdict was already consulted by Gates 2 and 5 but not here, so a pure docs
+  # commit still paid ~11s for a compile that had nothing new to compile.
+  # Recorded as SKIP (not PASS): nothing was verified.
+  GATE_9_TS_STATUS="SKIP"
+  GATE_9_JAVA_STATUS="SKIP"
+  echo "   ⏭️  SKIPPED - Build integrity (docs-only commit)."
+elif [ "$PROJECT_LANG" = "documentation-only" ]; then
+  echo "   ⏭️  SKIPPED - Build integrity (documentation project)."
+elif [ -f "package.json" ] && [ -f "tsconfig.json" ]; then
   GATE_9_SCRIPT=""
   if [ -f "$PROJECT_ROOT/src/build-integrity/gate-10.ts" ]; then
     GATE_9_SCRIPT="$PROJECT_ROOT/src/build-integrity/gate-10.ts"

package/hooks/pre-push

@@ -153,8 +153,15 @@ fi
 DOC_ONLY=true
 SOURCE_EXTENSIONS="\.py$|\.js$|\.cjs$|\.mjs$|\.ts$|\.tsx$|\.java$|\.go$|\.rs$|\.cpp$|\.c$|\.swift$|\.kt$|\.sh$|\.dart$|\.ps1$|\.m$|\.mm$|\.h$|\.hpp$"
 
+# Extensionless hook scripts and test files are CODE, not documentation.
+# Measured consequence of the old list: a commit touching githooks/pre-push and
+# its .bats suite was classified "Documentation-only push (no source code
+# files)" and the walkthrough was skipped — the single most safety-critical
+# script in the repo, exempt from review by a filename-shape accident.
+NON_EXT_SOURCE_RE='^(githooks/(pre-commit|pre-push|post-merge|install\.sh|verify\.sh)|[^/]+\.bats)$|/__tests__/'
+
 for file in $PUSHED_FILES; do
-  if echo "$file" | grep -qE "$SOURCE_EXTENSIONS"; then
+  if echo "$file" | grep -qE "$SOURCE_EXTENSIONS" || echo "$file" | grep -qE "$NON_EXT_SOURCE_RE"; then
     DOC_ONLY=false
     break
   fi
@@ -954,6 +961,20 @@ else
 # GATE MW: VALIDATE CODE WALKTHROUGH RESULT FILE
 # ============================================================================
 RESULT_FILE=".code-walkthrough-result.json"
+MW_SKIPPED=0
+
+# Skipped on main/master by design, exactly like Gate ML and Gate UI above.
+# Work is already walkthrough-reviewed on the feature branch before it lands, so
+# demanding a fresh three-model sweep against the merge commit would only
+# re-review identical code — and it made every release commit unpushable, since
+# the release commit itself changes nothing anyone reviewed. githooks/AGENTS.md
+# documented this skip; the code did not implement it (drift fixed here).
+if [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "master" ]; then
+  MW_SKIPPED=1
+  echo ""
+  echo "   ℹ️  Gate MW skipped (pushing to ${CURRENT_BRANCH} — pre-reviewed via branch walkthrough)"
+  echo ""
+else
 
 
 if [ ! -f "$RESULT_FILE" ]; then
@@ -1019,22 +1040,32 @@ if ! VALIDATION_ERROR=$(node "$MW_VALIDATOR" "$RESULT_FILE" "$EXPECTED_COMMIT" "
   echo ""
   exit 1
 fi
+fi
 
 # ============================================================================
 # ALL CHECKS PASSED
 # ============================================================================
 echo ""
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+# Say what actually happened. Printing "VERIFIED" on a skipped gate would be a
+# claim the hook cannot support — the same dishonesty (evidence asserting an
+# unperformed check) that Gate MW exists to prevent.
+if [ "$MW_SKIPPED" = "1" ]; then
+  echo "   ℹ️  GATE MW: CODE WALKTHROUGH SKIPPED (main-branch push)"
+else
   echo "   ✅ GATE MW: CODE WALKTHROUGH VERIFIED"
+fi
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo ""
 echo "Branch: $CURRENT_BRANCH"
 echo "Files changed: $FILES_CHANGED"
 echo "Lines: +$LINES_ADDED -$LINES_DELETED"
-echo ""
-echo "Code walkthrough result:"
-echo "  Commit: $EXPECTED_COMMIT"
-echo "  Verdict: APPROVED"
+if [ "$MW_SKIPPED" != "1" ] && [ -f "$RESULT_FILE" ]; then
+  echo ""
+  echo "Code walkthrough result:"
+  echo "  Commit: $EXPECTED_COMMIT"
+  echo "  Verdict: APPROVED"
+fi
 
 echo ""
 echo "Proceeding with push..."