@boyingliu01/xp-gate 0.32.1 → 0.32.3

package/adapters/powershell.sh

@@ -268,6 +268,19 @@ run_static_analysis() {
         return 3
       fi
     fi
+    # Downstream hardening (ported): a scope file narrows the gate to product
+    # code, but it must be analysed under a DECLARED rule set. With no
+    # PSScriptAnalyzerSettings.psd1 the -Settings binding falls back to defaults,
+    # so a repo that declared its scope silently swapped rule sets. Refuse the
+    # run rather than grade against an unknown rule set.
+    #
+    # Mirrors the missing-module semantics (return 3 = fail closed upstream).
+    if [ "${#analysis_targets[@]}" -gt 0 ] && [ ! -f "PSScriptAnalyzerSettings.psd1" ]; then
+      echo "XP_G1_REASON: analysis-settings-missing:PSScriptAnalyzerSettings.psd1"
+      echo "  ⚠️  $scope_file is in use but PSScriptAnalyzerSettings.psd1 is absent - refusing to analyse with an unknown rule set"
+      return 3
+    fi
+
 
     if [ "${#analysis_targets[@]}" -gt 0 ]; then
       # Scoped per-path run. -Path binds ONE string only (an array argument
@@ -430,14 +443,27 @@ run_lint() {
 # A hanging Pester test (e.g. a test that dot-sources a script whose body performs
 # WMI/registry/scheduled-task scans) would otherwise block `git commit` forever.
 # Default 300s, override via XP_GATE_POWERSHELL_TEST_TIMEOUT_S.
+# #599: ONE helper, TWO budgets. The instrumented coverage run enables
+# CodeCoverage, so instrumentation alone costs more than a plain run: a shared
+# 300s budget is not the same headroom for both. The caller passes its default
+# explicitly and the timeout message names the variable that actually governs it,
+# otherwise a budget shortfall gets reported as "a test is hanging" and the
+# reader is sent to the wrong place.
 _pester_timeout() {
-  local default_s="${XP_GATE_POWERSHELL_TEST_TIMEOUT_S:-300}"
+  local budget_var="$1"
+  local default_s="${2:-300}"
+  local effective_s
+  if [ "$budget_var" = "XP_GATE_POWERSHELL_COVERAGE_TIMEOUT_S" ]; then
+    effective_s="${XP_GATE_POWERSHELL_COVERAGE_TIMEOUT_S:-$default_s}"
+  else
+    effective_s="${XP_GATE_POWERSHELL_TEST_TIMEOUT_S:-$default_s}"
+  fi
   # Prefer GNU timeout (Git Bash / Linux). On Windows where `timeout` resolves to
   # the native timeout.exe, fall back to running without a hard timeout.
   if command -v timeout >/dev/null 2>&1 && timeout --version 2>/dev/null | grep -qi "coreutils"; then
-    timeout "${default_s}s" "$@"
+    timeout "${effective_s}s" "${@:3}"
   else
-    "$@"
+    "${@:3}"
   fi
 }
 
@@ -465,7 +491,7 @@ run_tests() {
   if [ "${#test_files[@]}" -gt 0 ]; then
     test_paths=$(_powershell_path_array "${test_files[@]}")
     echo "Running Pester tests..."
-    _pester_timeout "$PWSH" "${POWERSHELL_ARGS[@]}" "
+_pester_timeout "XP_GATE_POWERSHELL_TEST_TIMEOUT_S" "${XP_GATE_POWERSHELL_TEST_TIMEOUT_S:-300}" "$PWSH" "${POWERSHELL_ARGS[@]}" "
       \$results = Invoke-Pester -Path $test_paths -PassThru
       if (\$results.FailedCount -gt 0) {
         Write-Host \"FAILED: \$(\$results.FailedCount) test(s)\"
@@ -476,7 +502,7 @@ run_tests() {
     "
     local run_exit=$?
     if [ "$run_exit" = "124" ]; then
-      echo "⚠️  Pester tests TIMED OUT after ${XP_GATE_POWERSHELL_TEST_TIMEOUT_S:-300}s (may be hanging)."
+  echo "⚠️  Pester tests TIMED OUT after ${XP_GATE_POWERSHELL_TEST_TIMEOUT_S:-300}s (XP_GATE_POWERSHELL_TEST_TIMEOUT_S; may be hanging)."
       echo "    A test may be blocking on a system call (WMI/registry/scheduled-task)."
       echo "    Fix the hanging test, or set XP_GATE_POWERSHELL_TEST_TIMEOUT_S to a higher value."
       return 1
@@ -572,7 +598,7 @@ run_coverage() {
     # is the deprecated Pester 4 parameter set and fails outright on Pester 5.x
     # ("cannot resolve parameter set"). Using it silently produced no coverage.xml,
     # which the pre-commit hook then reported as an unparseable/zero result.
-    _pester_timeout "$PWSH" "${POWERSHELL_ARGS[@]}" "
+_pester_timeout "XP_GATE_POWERSHELL_COVERAGE_TIMEOUT_S" "${XP_GATE_POWERSHELL_COVERAGE_TIMEOUT_S:-900}" "$PWSH" "${POWERSHELL_ARGS[@]}" "
       \$cfg = New-PesterConfiguration
       \$cfg.Run.Path = $test_paths
       \$cfg.CodeCoverage.Enabled = \$true
@@ -587,7 +613,7 @@ run_coverage() {
     " 2>&1
     local cov_exit=$?
     if [ "$cov_exit" = "124" ]; then
-      echo "⚠️  Pester coverage TIMED OUT after ${XP_GATE_POWERSHELL_TEST_TIMEOUT_S:-300}s (may be hanging)."
+  echo "⚠️  Pester coverage TIMED OUT after ${XP_GATE_POWERSHELL_COVERAGE_TIMEOUT_S:-900}s (XP_GATE_POWERSHELL_COVERAGE_TIMEOUT_S; instrumentation costs more than a plain run - raise this rather than suspecting a hang)."
       return 1
     fi
     return $cov_exit

package/bin/xp-gate.js

@@ -545,19 +545,59 @@ function handleAuditTail(args, auditPath) {
 
 function handleAuditStats(auditPath) {
   try {
-    const { computeStats } = require(auditPath);
+    const { computeStats, computeAnomalies } = require(auditPath);
     const stats = computeStats();
     if (stats.length === 0) {
       console.log('No audit data found.');
       return;
     }
     printStatsTable(stats);
+    printAnomalies(computeAnomalies());
   } catch (err) {
     console.error('Error computing stats:', err.message);
     process.exit(1);
   }
 }
 
+/**
+ * Print the audit-health summary. `total` is the ledger-integrity number CI
+ * gates on (xp-gate audit --check); the components explain where it comes from.
+ */
+function printAnomalies(a, since) {
+  console.log('');
+  console.log('Audit health (anomalies):');
+  if (since) console.log(`  scope                : entries since ${since}`);
+  console.log(`  entries scanned      : ${a.scanned}`);
+  console.log(`  implausible duration : ${a.implausible_duration}  (epoch/negative — the REQ-B bug)`);
+  console.log(`  missing commit       : ${a.missing_commit}  (blank/unknown attribution — the off-by-one bug)`);
+  console.log(`  duration_anomaly flag: ${a.flagged}`);
+  console.log(`  null + reason        : ${a.null_with_reason}  (honest unmeasurable, NOT counted as anomaly)`);
+  console.log(`  ── total anomalies   : ${a.total}`);
+}
+
+/**
+ * CI gate: exit 1 when the audit ledger carries anomalies (implausible
+ * durations or unattributed commits). This turns both telemetry bugs into a
+ * build failure instead of something a human has to notice in a chart.
+ */
+function handleAuditCheck(auditPath) {
+  try {
+    const { computeAnomalies, AUDIT_ANOMALY_SINCE } = require(auditPath);
+    // Scope to entries after the fix: historical anomalies are grandfathered
+    // (they cannot be re-measured). A future epoch/blank row fails the build.
+    const a = computeAnomalies(process.cwd(), AUDIT_ANOMALY_SINCE);
+    printAnomalies(a, AUDIT_ANOMALY_SINCE);
+    if (a.total > 0) {
+      console.error(`FAIL: ${a.total} audit anomal${a.total === 1 ? 'y' : 'ies'} found since ${AUDIT_ANOMALY_SINCE} (must be 0).`);
+      process.exit(1);
+    }
+    console.log('OK: no new audit anomalies.');
+  } catch (err) {
+    console.error('Error checking audit health:', err.message);
+    process.exit(1);
+  }
+}
+
 function handleAuditRecord(args, auditPath) {
   try {
     const { appendAuditEntry } = require(auditPath);
@@ -600,6 +640,11 @@ function handleAudit(args) {
     return;
   }
 
+  if (args.includes('--check')) {
+    handleAuditCheck(auditPath);
+    return;
+  }
+
   if (args[0] === 'record') {
     handleAuditRecord(args, auditPath);
     return;
@@ -609,7 +654,8 @@ function handleAudit(args) {
   console.error('Usage:');
   console.error('  xp-gate audit record --gate-id X --gate-name Y --passed true/false --issues-found N --duration-ms N --trigger commit');
   console.error('  xp-gate audit --tail [N]     (default: 20)');
-  console.error('  xp-gate audit --stats');
+  console.error('  xp-gate audit --stats        (per-gate stats + anomaly summary)');
+  console.error('  xp-gate audit --check        (exit 1 if the ledger has anomalies)');
   process.exit(1);
 }
 

package/gate-3.sh

@@ -176,7 +176,42 @@ elif [ "$PROJECT_LANG" = "powershell" ]; then
                       known.set(norm(e.file) + "::" + e.name, Number(e.ccn) || 0);
                     }
                   }
-                  function norm(p) { return String(p).replace(/\\\\/g, "/").replace(/^\.\//, ""); }
+                  // The measurement emits ABSOLUTE paths (pwsh resolved them), while
+                  // a baseline recorded by a repo-side generator holds paths relative
+                  // to the repo root. Normalising alone cannot bridge that, so a key
+                  // miss falls back to a suffix match on the file path: exactly one
+                  // known entry whose normalised path ends with "<sep>measured" is the
+                  // same file. Without this every existing function looked brand new,
+                  // and a real regression was reported as "new function" -- the right
+                  // verdict for the wrong reason.
+                  //
+                  // Backslashes are normalised with split/join, NOT -replace: this JS
+                  // is embedded in a double-quoted bash command, where a regex escape
+                  // loses a level and silently matches the wrong number of
+                  // backslashes. Measured: /\\\\/g arrived as /\\/g, matched only
+                  // doubled separators, and every Windows path kept its backslashes.
+                  function norm(p) {
+                    return String(p)
+                      .split("\\").join("/")
+                      .replace(/^[A-Za-z]:\//, "")
+                      .replace(/^\.\//, "")
+                      .replace(/^\//, "");
+                  }
+                  function lookup(path, name) {
+                    const key = norm(path) + "::" + name;
+                    if (known.has(key)) return known.get(key);
+                    const target = norm(path);
+                    let hit = null;
+                    for (const [k, v] of known) {
+                      const [kp, kn] = k.split("::");
+                      if (kn !== name) continue;
+                      if (target.endsWith("/" + kp) || kp.endsWith("/" + target) || kp === target) {
+                        if (hit !== null && hit !== v) return null;  // ambiguous: treat as new
+                        hit = v;
+                      }
+                    }
+                    return hit;
+                  }
                   const seen = new Set();
                   const regressions = [];
                   const improved = [];
@@ -186,7 +221,7 @@ elif [ "$PROJECT_LANG" = "powershell" ]; then
                     const key = norm(m[1]) + "::" + m[3];
                     const now = Number(m[4]);
                     seen.add(key);
-                    const was = known.has(key) ? known.get(key) : null;
+                    const was = lookup(m[1], m[3]);
                     if (was === null) {
                       if (now > threshold) {
                         regressions.push(m[1] + ":" + m[2] + "  " + m[3] + "  new function at ccn=" + now);

package/gate-4.sh

@@ -107,6 +107,14 @@ else
     if [ -n "$PRINCIPLES_DIR" ]; then
       echo "Checking Clean Code + SOLID principles..."
 
+      # #581/#582 class: run_tsx drives a NATIVE node/tsx binary. A POSIX
+      # path like $HOME/.config/... reaches it as the wrong drive prefix and
+      # the checker is "not found", which the exit>=2 branch then reported
+      # as SKIPPED. Convert once here so both invocations agree.
+      if declare -F to_native_path >/dev/null 2>&1; then
+        PRINCIPLES_DIR="$(to_native_path "$PRINCIPLES_DIR")"
+      fi
+
       # 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.

package/hooks/gate-3.sh

@@ -176,7 +176,42 @@ elif [ "$PROJECT_LANG" = "powershell" ]; then
                       known.set(norm(e.file) + "::" + e.name, Number(e.ccn) || 0);
                     }
                   }
-                  function norm(p) { return String(p).replace(/\\\\/g, "/").replace(/^\.\//, ""); }
+                  // The measurement emits ABSOLUTE paths (pwsh resolved them), while
+                  // a baseline recorded by a repo-side generator holds paths relative
+                  // to the repo root. Normalising alone cannot bridge that, so a key
+                  // miss falls back to a suffix match on the file path: exactly one
+                  // known entry whose normalised path ends with "<sep>measured" is the
+                  // same file. Without this every existing function looked brand new,
+                  // and a real regression was reported as "new function" -- the right
+                  // verdict for the wrong reason.
+                  //
+                  // Backslashes are normalised with split/join, NOT -replace: this JS
+                  // is embedded in a double-quoted bash command, where a regex escape
+                  // loses a level and silently matches the wrong number of
+                  // backslashes. Measured: /\\\\/g arrived as /\\/g, matched only
+                  // doubled separators, and every Windows path kept its backslashes.
+                  function norm(p) {
+                    return String(p)
+                      .split("\\").join("/")
+                      .replace(/^[A-Za-z]:\//, "")
+                      .replace(/^\.\//, "")
+                      .replace(/^\//, "");
+                  }
+                  function lookup(path, name) {
+                    const key = norm(path) + "::" + name;
+                    if (known.has(key)) return known.get(key);
+                    const target = norm(path);
+                    let hit = null;
+                    for (const [k, v] of known) {
+                      const [kp, kn] = k.split("::");
+                      if (kn !== name) continue;
+                      if (target.endsWith("/" + kp) || kp.endsWith("/" + target) || kp === target) {
+                        if (hit !== null && hit !== v) return null;  // ambiguous: treat as new
+                        hit = v;
+                      }
+                    }
+                    return hit;
+                  }
                   const seen = new Set();
                   const regressions = [];
                   const improved = [];
@@ -186,7 +221,7 @@ elif [ "$PROJECT_LANG" = "powershell" ]; then
                     const key = norm(m[1]) + "::" + m[3];
                     const now = Number(m[4]);
                     seen.add(key);
-                    const was = known.has(key) ? known.get(key) : null;
+                    const was = lookup(m[1], m[3]);
                     if (was === null) {
                       if (now > threshold) {
                         regressions.push(m[1] + ":" + m[2] + "  " + m[3] + "  new function at ccn=" + now);

package/hooks/gate-4.sh

@@ -107,6 +107,14 @@ else
     if [ -n "$PRINCIPLES_DIR" ]; then
       echo "Checking Clean Code + SOLID principles..."
 
+      # #581/#582 class: run_tsx drives a NATIVE node/tsx binary. A POSIX
+      # path like $HOME/.config/... reaches it as the wrong drive prefix and
+      # the checker is "not found", which the exit>=2 branch then reported
+      # as SKIPPED. Convert once here so both invocations agree.
+      if declare -F to_native_path >/dev/null 2>&1; then
+        PRINCIPLES_DIR="$(to_native_path "$PRINCIPLES_DIR")"
+      fi
+
       # 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.

package/hooks/post-commit

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# ============================================================================
+# XP-Gate Post-Commit Hook
+#
+# Two jobs, both only possible AFTER the commit object exists:
+#
+# 1. Audit flush (#audit-attribution). Pre-commit cannot know the commit it is
+#    about to create — `git rev-parse HEAD` there is the PARENT, so per-gate
+#    audit entries used to be filed under the previous commit (the newest
+#    commit looked like it "ran no gates", and per-commit battery stats mixed
+#    two commits' timings). Pre-commit now STAGES entries in
+#    .xp-gate/audit.pending.jsonl; this hook flushes them stamped with the real
+#    HEAD. Pre-commit also flushes leftovers at its own start as a safety net,
+#    so a missed post-commit never loses data.
+#
+# 2. Bypass detection (D8 Layer 2). Detects `git commit --no-verify`:
+#    - pre-commit writes .git/xp-gate-precommit-marker on a successful run
+#    - if the marker is absent here, pre-commit was bypassed (or crashed)
+#    - bypass events go to .xp-gate/bypass-audit.jsonl for later enforcement
+#
+# Git semantics: post-commit cannot block the commit (git limitation). It only
+# records. ============================================================================
+
+set -e
+
+git_dir="$(git rev-parse --git-dir 2>/dev/null)"
+if [ -z "$git_dir" ]; then
+  exit 0
+fi
+
+toplevel="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+head_commit="$(git rev-parse HEAD 2>/dev/null || true)"
+
+# ── 1. Flush staged audit entries with the real commit hash ──────────────────
+# Only when this repo actually carries the audit module (the xp-gate checkout).
+# A consumer repo has no src/npm-package; there pre-commit's record call is a
+# no-op, so nothing is ever staged and there is nothing to flush.
+if [ -n "$toplevel" ] && [ -n "$head_commit" ] \
+   && [ -f "$toplevel/src/npm-package/lib/gate-audit.ts" ]; then
+  _pending="$toplevel/.xp-gate/audit.pending.jsonl"
+  if [ -f "$toplevel/node_modules/tsx/dist/cli.mjs" ] && command -v node >/dev/null 2>&1; then
+    _flush() {
+      node "$toplevel/node_modules/tsx/dist/cli.mjs" \
+        "$toplevel/src/npm-package/lib/gate-audit.ts" flush-pending \
+        --commit-hash "$head_commit" --report true 2>/dev/null || echo 0
+    }
+  elif command -v npx >/dev/null 2>&1; then
+    _flush() {
+      ( cd "$toplevel" && npx --no-install tsx src/npm-package/lib/gate-audit.ts \
+          flush-pending --commit-hash "$head_commit" --report true 2>/dev/null ) || echo 0
+    }
+  fi
+  # Bounded drain: the last gate's recorder is fire-and-forget (`& disown` in
+  # pre-commit), so post-commit can start before it has written its line. Keep
+  # flushing until two consecutive passes find nothing, capped so a slow node
+  # start never stalls the commit. Usually the first pass suffices.
+  _passes=0
+  _empty=0
+  while [ "$_passes" -lt 6 ] && [ "$_empty" -lt 2 ]; do
+    _n="$(_flush)"
+    _passes=$((_passes + 1))
+    case "$_n" in ''|*[!0-9]*) _n=0 ;; esac
+    if [ "$_n" -gt 0 ]; then _empty=0; else _empty=$((_empty + 1)); fi
+    [ "$_empty" -lt 2 ] && sleep 0.05
+  done
+fi
+
+# ── 2. Bypass detection ─────────────────────────────────────────────────────
+marker="$git_dir/xp-gate-precommit-marker"
+
+if [ ! -f "$marker" ]; then
+  if [ -n "$head_commit" ]; then
+    mkdir -p .xp-gate
+    printf '{"commit":"%s","timestamp":"%s","type":"precommit_bypass","branch":"%s"}\n' \
+      "$head_commit" "$(date -Iseconds)" \
+      "$(git rev-parse --abbrev-ref HEAD 2>/dev/null)" >> .xp-gate/bypass-audit.jsonl
+  fi
+else
+  rm -f "$marker"
+fi
+
+exit 0

package/hooks/pre-commit

@@ -344,6 +344,25 @@ file_exists_in_subdir() {
 AUDIT_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT_FOR_AUDIT="$(git rev-parse --show-toplevel 2>/dev/null || echo "$AUDIT_SCRIPT_DIR/../..")"
 
+# Audit attribution safety net: if a previous commit's post-commit never fired
+# (hooks skipped, crash, or an earlier --no-verify), its staged entries are
+# still in .xp-gate/audit.pending.jsonl. Flush them now, stamped with the commit
+# they actually belong to (`git log -1`), so they land under a real commit
+# instead of accumulating or being stamped with THIS run's hash later. Runs
+# before any gate so the flush is never counted in this commit's timings.
+# Best-effort and silent: audit must never affect the commit's outcome.
+if [ -f "$PROJECT_ROOT_FOR_AUDIT/.xp-gate/audit.pending.jsonl" ] \
+   && [ -f "$PROJECT_ROOT_FOR_AUDIT/src/npm-package/lib/gate-audit.ts" ]; then
+  _audit_prev_hash="$(git log -1 --format=%H 2>/dev/null || true)"
+  if [ -n "$_audit_prev_hash" ] && [ -f "$PROJECT_ROOT_FOR_AUDIT/node_modules/tsx/dist/cli.mjs" ] \
+     && command -v node >/dev/null 2>&1; then
+    node "$PROJECT_ROOT_FOR_AUDIT/node_modules/tsx/dist/cli.mjs" \
+      "$PROJECT_ROOT_FOR_AUDIT/src/npm-package/lib/gate-audit.ts" flush-pending \
+      --commit-hash "$_audit_prev_hash" >/dev/null 2>&1 || true
+  fi
+  unset _audit_prev_hash
+fi
+
 # Issue #535: a failed `source` used to print one stderr line and keep going,
 # so a missing lib silently removed gate logic from the run while every gate
 # still reported PASS. Fail closed instead: abort with FATAL when the file is

package/hooks/pre-push

@@ -184,7 +184,20 @@ write_pre_push_report() {
     printf '%s\n' "Path('$report_file').write_text(json.dumps(report, indent=2) + '\n')"
   } > "$py_script"
 
-  "$py_bin" "$py_script"
+  # Native Python cannot open mktemp's POSIX path (/tmp/...) on Windows: it
+  # resolves the leading slash against the current drive and reports a file
+  # that "does not exist", which the caller then billed as "Gate M journal
+  # missing" on every push. Convert when a converter is available.
+  local py_script_native="$py_script"
+  if command -v cygpath >/dev/null 2>&1; then
+    # MSYS/Git-Bash: mktemp hands back /tmp/..., which is a MOUNT, not /<drive>/.
+    # Native python.exe resolves the leading slash against the current drive and
+    # reports "can't open file", which the caller then billed as "Gate M journal
+    # missing" on every push. cygpath knows the mount table; the helper library
+    # is not sourced yet at this point, so it cannot be used here.
+    py_script_native="$(cygpath -w "$py_script" 2>/dev/null || printf '%s' "$py_script")"
+  fi
+  "$py_bin" "$py_script_native"
   py_rc=$?
   rm -f "$py_script"
   if [ "$py_rc" -ne 0 ]; then
@@ -197,7 +210,13 @@ write_pre_push_report() {
   # rule can be exercised directly by tests instead of being asserted through a
   # copied-and-pasted implementation. It refuses to emit a number when the gates
   # that ran cannot summarise the report (none ran, or fewer than half did).
-  if ! "$py_bin" "$score_lib" --report "$report_file"; then
+  # Same MSYS/native-path boundary as the journal body above: $score_lib is a
+  # POSIX path ($HOME/.config/...) and native python.exe cannot open it.
+  local score_lib_native="$score_lib"
+  if command -v cygpath >/dev/null 2>&1; then
+    score_lib_native="$(cygpath -w "$score_lib" 2>/dev/null || printf '%s' "$score_lib")"
+  fi
+  if ! "$py_bin" "$score_lib_native" --report "$report_file"; then
     echo "⚠️  Gate M journal: could not score $report_file — score left unset." >&2
   fi
 }

package/lib/__tests__/doctor-audit-ledger.test.js

@@ -0,0 +1,61 @@
+/**
+ * @test REQ-AUDIT-ATTRIBUTION xp-gate doctor surfaces gate-telemetry anomalies
+ * @intent The two audit bugs (epoch-sized durations, commits attributed to their
+ *         parent) leave fingerprints in .xp-gate/audit.jsonl. CI cannot see a
+ *         gitignored ledger, so doctor must warn locally on NEW anomalies while
+ *         grandfathering the historical rows that cannot be re-measured.
+ * @covers AUDIT-001-11
+ */
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+// doctor.js is CommonJS; import the whole module namespace.
+const doctor = require('../doctor.js');
+
+function repoWithLedger(rows) {
+  const root = mkdtempSync(join(tmpdir(), 'xp-gate-ledger-'));
+  mkdirSync(join(root, '.xp-gate'), { recursive: true });
+  const nl = String.fromCharCode(10);
+  writeFileSync(join(root, '.xp-gate', 'audit.jsonl'), rows.map((r) => JSON.stringify(r)).join(nl) + nl);
+  return root;
+}
+
+describe('doctor audit-ledger health (P0 telemetry)', () => {
+  it('@covers AUDIT-001-11 a fresh clean ledger passes', () => {
+    const future = '2030-01-01T00:00:00.000Z';
+    const root = repoWithLedger([
+      { timestamp: future, gate_id: 'gate-1', duration_ms: 100, commit_hash: 'abc', passed: true, issues_found: 0 },
+    ]);
+    const { checks, issues } = doctor.diagnoseAuditLedger({ repoRoot: root });
+    expect(issues).toBe(0);
+    expect(checks[0].status).toBe('PASS');
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('@covers AUDIT-001-11 new epoch/blank-commit rows raise a WARN, grandfather old ones', () => {
+    const future = '2030-01-01T00:00:00.000Z';
+    const old = '2020-01-01T00:00:00.000Z';
+    const root = repoWithLedger([
+      // grandfathered — both anomalies, but before the fix date
+      { timestamp: old, gate_id: 'gate-1', duration_ms: 1750000000000, commit_hash: '', passed: true, issues_found: 0 },
+      // NEW anomalies — must be counted
+      { timestamp: future, gate_id: 'gate-2', duration_ms: 1750000000000, commit_hash: 'abc', passed: true, issues_found: 0 },
+      { timestamp: future, gate_id: 'gate-3', duration_ms: 100, commit_hash: '', passed: true, issues_found: 0 },
+    ]);
+    const { checks, issues } = doctor.diagnoseAuditLedger({ repoRoot: root });
+    expect(issues).toBe(0); // WARN, not a blocking issue count
+    expect(checks[0].status).toBe('WARN');
+    expect(checks[0].detail).toContain('2 anomalies');
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('@covers AUDIT-001-11 no ledger is a SKIP, not a failure', () => {
+    const root = mkdtempSync(join(tmpdir(), 'xp-gate-ledger-empty-'));
+    const { checks, issues } = doctor.diagnoseAuditLedger({ repoRoot: root });
+    expect(issues).toBe(0);
+    expect(checks[0].status).toBe('SKIP');
+    rmSync(root, { recursive: true, force: true });
+  });
+});