@boyingliu01/xp-gate 0.27.5 → 0.28.0

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

@@ -955,6 +955,18 @@ else
 # ============================================================================
 RESULT_FILE=".code-walkthrough-result.json"
 
+# 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
+  echo ""
+  echo "   ℹ️  Gate MW skipped (pushing to ${CURRENT_BRANCH} — pre-reviewed via branch walkthrough)"
+  echo ""
+else
+
 
 if [ ! -f "$RESULT_FILE" ]; then
   echo ""
@@ -1019,6 +1031,7 @@ if ! VALIDATION_ERROR=$(node "$MW_VALIDATOR" "$RESULT_FILE" "$EXPECTED_COMMIT" "
   echo ""
   exit 1
 fi
+fi
 
 # ============================================================================
 # ALL CHECKS PASSED
@@ -1031,10 +1044,12 @@ 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 [ -f "$RESULT_FILE" ]; then
+  echo ""
+  echo "Code walkthrough result:"
+  echo "  Commit: $EXPECTED_COMMIT"
+  echo "  Verdict: APPROVED"
+fi
 
 echo ""
 echo "Proceeding with push..."

package/lib/gate-audit.ts

@@ -32,11 +32,12 @@ export interface GateAuditEntry {
   gate_name: string;
   passed: boolean;
   issues_found: number;
-  duration_ms: number;
+  duration_ms: number | null; // REQ-B: null = deliberately unmeasurable (see duration_reason)
   trigger: 'commit' | 'push' | 'manual';
   repo_path: string;
   commit_hash: string;
   duration_anomaly?: boolean; // Issue #370: set when duration_ms > max_duration_ms
+  duration_reason?: 'poisoned_start_ms' | 'clock_skew'; // REQ-B: why duration_ms is null
   detail?: string; // #507: optional gate-specific payload (e.g. effective CCN threshold)
 }
 
@@ -154,10 +155,12 @@ function aggregateByGate(entries: GateAuditEntry[]): Map<string, { total: number
     const b = buckets.get(e.gate_id) ?? { total: 0, passed: 0, ms: 0, issues: 0, anomaly_count: 0 };
     b.total += 1;
     if (e.passed) b.passed += 1;
-    // Issue #370: exclude anomalous durations from ms aggregation
+    // Issue #370: exclude anomalous durations from ms aggregation. REQ-B: a
+    // null duration is the honest sibling of that flag — deliberately not
+    // measurable, so it stays out of the sums (and out of the denominator).
     if (e.duration_anomaly === true) {
       b.anomaly_count += 1;
-    } else {
+    } else if (typeof e.duration_ms === 'number') {
       b.ms += e.duration_ms;
     }
     b.issues += e.issues_found;
@@ -253,12 +256,14 @@ function runCli(): void {
       gate_name: opts['gate-name'] || 'unknown',
       passed: opts['passed'] === 'true',
       issues_found: parseInt(opts['issues-found'] || '0', 10),
-      duration_ms: parseInt(opts['duration-ms'] || '0', 10),
+      duration_ms: opts['duration-ms'] === 'null' ? null : parseInt(opts['duration-ms'] || '0', 10),
       trigger: (opts['trigger'] as 'commit' | 'push' | 'manual') || 'manual',
       repo_path: process.cwd(),
       commit_hash: getCommitHash(),
       // Issue #370: only set when explicitly flagged (omit field otherwise)
       ...(opts['duration-anomaly'] === 'true' ? { duration_anomaly: true } : {}),
+      // REQ-B: why the duration is null — never guess a number for it.
+      ...(opts['duration-reason'] ? { duration_reason: opts['duration-reason'] as 'poisoned_start_ms' | 'clock_skew' } : {}),
       // #507: only set when provided (omit field otherwise)
       ...(opts['detail'] ? { detail: opts['detail'] } : {}),
     };

package/lib/mattpocock-license-verdict.json

@@ -2,6 +2,6 @@
   "verdict": "PASS",
   "license_type": "MIT",
   "sha256": "0e7ac423bf2c6e223b7c5b156f8cf72da49d748e56a1641402c31f22ad07dbb5",
-  "checked_at": "2026-10-18T12:53:19.772Z",
+  "checked_at": "2026-10-19T12:19:52.510Z",
   "source": "network"
 }

package/lib/retro.js

@@ -15,6 +15,14 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 
+/**
+ * Upper bound for a believable gate runtime. A gate that reports more than two
+ * hours did not take two hours; it took a corrupted clock. Used to exclude
+ * samples from the duration average rather than let one poisoned row dominate
+ * it (the symptom was an "average" of 2.2e12 ms).
+ */
+const MAX_SANE_DURATION_MS = 2 * 60 * 60 * 1000;
+
 /**
  * Get git commit subjects within a date window.
  * @param {string} dir - Repository root
@@ -105,16 +113,29 @@ function buildReport(opts) {
   L.push('## Activity Summary');
   const gateEntries = audit.filter(e => e.gate_id);
   const passed = gateEntries.filter(e => e.passed).length;
-  const normal = gateEntries.filter(e => !e.duration_anomaly);
-  const anomalous = gateEntries.length - normal.length;
-  const avgMs = normal.length > 0
-    ? Math.round(normal.reduce((s, e) => s + (e.duration_ms || 0), 0) / normal.length)
+  // REQ-B: a duration is only usable when it is a finite non-negative number.
+  // `e.duration_ms || 0` used to fold null into ZERO, which both dragged the
+  // mean down and hid the fact that the sample was missing — the same class of
+  // lie as the epoch-sized values this sprint removed. The legacy
+  // duration_anomaly flag is no longer the only signal: a poisoned start now
+  // writes null outright, so anything null must be excluded and counted.
+  const measurable = gateEntries.filter(e => Number.isFinite(e.duration_ms) && e.duration_ms >= 0 && e.duration_ms <= MAX_SANE_DURATION_MS);
+  const excluded = gateEntries.length - measurable.length;
+  const nullDurations = gateEntries.filter(e => e.duration_ms === null).length;
+  const avgMs = measurable.length > 0
+    ? Math.round(measurable.reduce((s, e) => s + e.duration_ms, 0) / measurable.length)
     : 0;
   L.push(`- Total commits in window: ${commits.length}`);
   L.push(`- Sprint transitions recorded: ${sprints.length}`);
   L.push(`- Gate pass rate: ${gateEntries.length > 0 ? ((passed / gateEntries.length) * 100).toFixed(1) : '0.0'}% (${gateEntries.length} gates total, ${gateEntries.length - passed} failed)`);
-  if (gateEntries.length > 0) {
-    L.push(`- Avg gate duration: ${avgMs}ms (${anomalous} anomal${anomalous === 1 ? 'y' : 'ies'} excluded)`);
+  if (measurable.length > 0) {
+    // p50 alongside the mean: with a long tail the mean is the least useful
+    // statistic, and "avg gate duration: 2.2e12ms" was the visible symptom.
+    const sorted = measurable.map(e => e.duration_ms).sort((a, b) => a - b);
+    const p50 = sorted[Math.floor(sorted.length / 2)];
+    L.push(`- Avg gate duration: ${avgMs}ms, p50 ${p50}ms over ${measurable.length} measurable gate(s) (${excluded} excluded${nullDurations ? `, ${nullDurations} recorded null` : ''})`);
+  } else if (gateEntries.length > 0) {
+    L.push(`- Avg gate duration: no measurable samples (${excluded} of ${gateEntries.length} excluded as null or anomalous)`);
   }
   L.push('');
 

package/mock-policy/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MOCK-POLICY KNOWLEDGE BASE
 
-**Generated:** 2026-10-18
-**Commit:** 41792f89
+**Generated:** 2026-10-19
+**Commit:** 07d3036f
 **Branch:** main
-**Version:** 0.27.5.0
+**Version:** 0.28.0.0
 
 ## OVERVIEW
 Mock layering policy enforcement — Gate M3 of pre-push hook. Ensures integration tests use real implementations for internal dependencies, mock external dependencies, and annotate pending mocks with removal plans. Combines project scope scanning, mock decision engine, and per-file validation into a single pipeline.

package/mutation/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MUTATION KNOWLEDGE BASE
 
-**Generated:** 2026-10-18
-**Commit:** 41792f89
+**Generated:** 2026-10-19
+**Commit:** 07d3036f
 **Branch:** main
-**Version:** 0.27.5.0
+**Version:** 0.28.0.0
 
 ## OVERVIEW
 **Gate M** (incremental mutation testing) + **Gate M2** helpers (test-layer detection used by `src/mock-policy/`). Pre-push quality gate. TypeScript-only; uses Stryker.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/xp-gate",
-  "version": "0.27.5",
+  "version": "0.28.0",
   "description": "AI-driven development workflow: 6 quality gates + Delphi review + Sprint Flow",
   "bin": {
     "xp-gate": "./bin/xp-gate.js"

package/plugins/claude-code/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.27.5",
+  "version": "0.28.0",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Claude Code. Includes 12 pre-commit gates (Gate 0-11), 8 pre-push gates, Sprint Flow (6 phases), and Delphi multi-expert review (>=90% consensus).",
   "author": {

package/plugins/claude-code/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-10-18
-**Commit:** 41792f89
+**Generated:** 2026-10-19
+**Commit:** 07d3036f
 **Branch:** main
-**Version:** 0.27.5.0
+**Version:** 0.28.0.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/claude-code/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-18
-**Commit:** 41792f89
+**Generated:** 2026-10-19
+**Commit:** 07d3036f
 **Branch:** main
-**Version:** 0.27.5.0
+**Version:** 0.28.0.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/claude-code/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-18
-**Commit:** 41792f89
+**Generated:** 2026-10-19
+**Commit:** 07d3036f
 **Branch:** main
-**Version:** 0.27.5.0
+**Version:** 0.28.0.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.