@boyingliu01/xp-gate 0.33.2 → 0.34.0

package/hooks/lib/assertion-quality.sh

@@ -0,0 +1,232 @@
+#!/bin/bash
+# Test-suite hygiene detectors for Gate 5, shared by every branch that needs them.
+# Sourced by githooks/pre-commit and by the #602/#601 test batteries; kept in its
+# own file so the contract is unit-testable without executing the hook.
+#
+# Why this exists at all: 指南 §9.5/§12 says a failing build must never be "fixed"
+# by deleting assertions, widening mocks, or skipping tests. XP-Gate had no
+# detector for the two quietest ways to do exactly that -- a committed `.only`
+# (CI then runs one case and reports green) and a deleted test file with no
+# replacement (the safety net vanishes with no signal). Gate 5a guarded the
+# ADD side ("a new source file must have a test"); these functions guard the
+# FOCUS/SKIP/DELETE side so the constraint is symmetric.
+#
+# The patterns live here, once, because Gate 5d (#601, assertion quality) needs
+# the same vocabulary. Two copies of "what counts as a skip" drift apart, and the
+# drift is invisible: each copy looks locally correct.
+
+# JS/TS focus markers. In vitest and jest, the presence of `.only` in a file makes
+# the whole file run ONLY that case; every other case is silently not executed and
+# the run still reports success. `fit`/`fdescribe` are the jasmine aliases that
+# vitest still accepts.
+#
+# Only the dotted/camel spellings are matched, not a bare `fit(`: `fit(` is also a
+# common local helper name (curve fitting, layout fitting) and a false BLOCK on
+# ordinary source would make the gate unusable. The anchored `\b(fit|fdescribe)\(`
+# alternative below covers the alias form at a statement boundary only.
+#
+# Prints `line:text` for each hit. Empty output means "no focus markers".
+classify_test_focus() {
+  grep -nE '(\.only[[:space:]]*\()|(\b(fit|fdescribe)[[:space:]]*\()' || true
+}
+
+# Skip/todo markers across the five languages this repo gates. These are WARNINGS,
+# not blocks: a skipped test is sometimes legitimate and always visible in the test
+# runner, unlike `.only`. The warning is what makes the XP-Gate report say it
+# counted fewer cases than the file contains.
+#
+# `@skip-justified: <reason >= 10 chars>` exempts one occurrence; see
+# is_skip_justified() -- a bare annotation with no reason is not an exemption, so
+# the escape hatch cannot become the default path.
+classify_test_skip() {
+  grep -nE '(\.(skip|todo)[[:space:]]*\()|(\b(xit|xdescribe|xtest)[[:space:]]*\()|(@pytest\.mark\.skip)|(\bt\.Skip[f]?\()|(@Disabled\b)|(@Ignore\b)' || true
+}
+
+# A skip marker is exempt when the surrounding file carries
+# `@skip-justified: <reason>` with a reason of at least 10 non-space characters.
+# Splitting marker-detection from justification keeps each rule single-purpose and
+# makes "the annotation exists but has no reason" a testable state rather than a
+# silent pass.
+#
+# $1 = the source text to inspect (usually the staged file content).
+is_skip_justified() {
+  printf '%s\n' "$1" \
+    | grep -oE '@skip-justified:[[:space:]]*[^[:space:]*].*' \
+    | sed 's/^@skip-justified:[[:space:]]*//' \
+    | tr -d '\r' \
+    | awk 'length($0) >= 10 { found = 1; exit } END { exit(found ? 0 : 1) }'
+}
+
+# Files whose basename marks them as a test. Shared with classify_deleted_tests so
+# "is this a test file" has one definition. Covers the naming conventions of the
+# gated languages: *.test.ts / *.spec.js / *_test.py / test_*.py / *_test.go /
+# *Test.java / *Tests.kt / *.Tests.ps1.
+is_test_file_path() {
+  printf '%s' "$1" \
+    | grep -qE '(^|/)(__tests__/)?(test_[^/]+\.py|[^/]+_test\.(py|go)|[^/]+\.(test|spec)\.[a-z]+|[^/]*(Test|Tests|TestSuite)\.(java|kt|cs|scala)|[^/]+\.Tests\.ps1)$'
+}
+
+# Deleted test files that have NO same-named replacement.
+#
+# A pure deletion and a rename look identical in `--name-only --diff-filter=D`;
+# git reports the old path as deleted either way. Comparing against the added list
+# is what separates "the safety net was removed" from "the file moved", and
+# reporting a rename would train developers to ignore the warning.
+#
+# $1 = file with deleted paths (one per line), $2 = file with added paths.
+# Prints the offending paths; empty output means every deletion was a rename.
+classify_deleted_tests() {
+  local deleted_list added_list
+  deleted_list="$1"
+  added_list="$2"
+  [ -f "$deleted_list" ] || return 0
+  local path
+  while IFS= read -r path; do
+    [ -n "$path" ] || continue
+    is_test_file_path "$path" || continue
+    # The same basename anywhere in the added list counts as a replacement: a
+    # rename is usually same-directory, but moving a test module into
+    # `__tests__/` is the common case here and must not be flagged.
+    local base
+    base=$(printf '%s' "$path" | sed 's#.*/##')
+    if [ -f "$added_list" ] && grep -qF "$base" "$added_list" 2>/dev/null; then
+      continue
+    fi
+    printf '%s\n' "$path"
+  done < "$deleted_list"
+}
+
+# ---------------------------------------------------------------------------
+# Gate 5d (#601): assertion quality. 指南 §9.2 forbids six assertion
+# anti-patterns; before this, nothing in XP-Gate looked at assertions at all --
+# Gate M2/M3 examine how test doubles are built, never whether the test actually
+# asserts anything. `expect(true).toBe(true)` and an empty `catch {}` pass every
+# other gate while verifying nothing.
+#
+# Every function below maps to one anti-pattern in
+# skills/test-driven-development/testing-anti-patterns.md, and says so, so a
+# reviewer reading a block message knows which section to consult.
+# ---------------------------------------------------------------------------
+
+# Anti-pattern 1: tautological assertion -- the assertion cannot fail. Two shapes,
+# both BLOCK, because neither is a weak test: each is the absence of one wearing an
+# assertion's syntax.
+#
+#   (a) literal vs identical literal: `expect(true).toBe(true)`, `expect(1).toBe(1)`
+#   (b) a literal tested for the truthiness it already has:
+#       `expect(true).toBeTruthy()`, `expect(false).toBeFalsy()`,
+#       `expect("x").toBeTruthy()`, `expect(0).toBeFalsy()`, `expect(null).toBeFalsy()`
+#
+# (b) cannot be caught by (a)'s backreference, and the pairs are not equivalents to
+# compare: `toBeTruthy`/`toBeFalsy` ask a different question than `toBe`. Matching
+# the literal's CLASS against the matcher is what distinguishes them, so the two
+# are separate alternatives rather than one clever expression.
+#
+# Deliberately NOT matched: `expect(x).toBe(x)` (same variable both sides). It is
+# common in referential-identity checks (`expect(await load(a)).toBe(await load(a))`
+# for memoisation) and a false block there is worse than the miss. Likewise
+# `expect(someVar).toBeTruthy()` -- a variable's truthiness is a real question.
+classify_tautological_assertions() {
+  # Implemented in awk rather than grep because POSIX grep -E has no portable
+  # backreference support: the Windows Git Bash grep used here matched nothing with
+  # `\1`, so a literal-vs-identical-literal check cannot be expressed there.
+  #
+  # The literal is extracted with a plain ERE-substitution loop instead of gawk's
+  # 3-argument match(), which mawk/BSD awk do not provide.
+  #
+  # Accepts stdin OR $1: the hook pipes the staged content in, while the test
+  # battery passes a string. Supporting only one of the two silently makes the
+  # other read nothing and report "no violations" -- the fail-open shape this
+  # whole release is about.
+  local _aq_src
+  if [ -n "${1:-}" ]; then _aq_src="$1"; else _aq_src=$(cat); fi
+  printf '%s\n' "$_aq_src" | awk '
+    BEGIN { TOL = "[[:space:]]*" }
+    function trim(s) { gsub(/^[[:space:]]+/, "", s); gsub(/[[:space:]]+$/, "", s); return s }
+    # (a) identical literal on both sides of toBe/toEqual/toStrictEqual.
+    /expect[^;]*\.to(Be|Equal|StrictEqual)[[:space:]]*\(/ {
+      line = $0
+      # Peel "expect(" ... ")" first, then the matcher argument.
+      if (match(line, /expect[[:space:]]*\([^()]*\)/)) {
+        left = substr(line, RSTART, RLENGTH)
+        sub(/^expect[[:space:]]*\(/, "", left); sub(/\)$/, "", left)
+        left = trim(left)
+        rest = substr(line, RSTART + RLENGTH)
+        if (match(rest, /\.to(Be|Equal|StrictEqual)[[:space:]]*\([^()]*\)/)) {
+          right = substr(rest, RSTART, RLENGTH)
+          sub(/^\.to(Be|Equal|StrictEqual)[[:space:]]*\(/, "", right); sub(/\)$/, "", right)
+          right = trim(right)
+          if (left != "" && left == right && left ~ /^(true|false|null|undefined|-?[0-9]+|".*"|\047.*\047)$/) {
+            print NR ":" line; next
+          }
+        }
+      }
+    }
+    # (b) a literal tested against the truthiness it already has.
+    /expect[[:space:]]*\([[:space:]]*(true|1|-1|"[^"]+"|\047[^\047]+\047)[[:space:]]*\)[[:space:]]*\.[[:space:]]*toBeTruthy[[:space:]]*\(/ { print NR ":" $0; next }
+    /expect[[:space:]]*\([[:space:]]*(false|0|null|undefined|""|\047\047)[[:space:]]*\)[[:space:]]*\.[[:space:]]*toBeFalsy[[:space:]]*\(/ { print NR ":" $0; next }
+  '
+}
+
+# Anti-pattern 2: swallowed error -- a `catch` that neither asserts nor rethrows.
+# The test cannot fail on the very path it was written to guard. BLOCK.
+#
+# Three spellings: `catch {}`, `catch (e) {}` (empty body), and `catch (e) { }`
+# with only whitespace. A catch containing `expect`/`assert`/`throw`/`fail` is
+# doing its job and is not matched.
+classify_swallowed_errors() {
+  grep -nE 'catch([[:space:]]*\([^)]*\))?[[:space:]]*\{[[:space:]]*\}' || true
+}
+
+# Anti-patterns 3-5 (WARNING tier): weak-only assertions, mock-echo assertions, and
+# call-order over-verification. These can be legitimate, so each is reported but
+# never blocks.
+#
+# Implemented as a per-`it`/`test` block judgement rather than a per-line grep:
+# "only weak assertions" is a property of the whole test body, and a line-wise
+# check cannot tell `expect(x).toBeDefined()` alone from the same line followed by
+# `expect(x).toBe(42)`.
+#
+# $1 = source text. Prints `line:reason` for each offending test block.
+classify_weak_assertions() {
+  # Stdin or $1, for the same reason classify_tautological_assertions accepts both.
+  local _aq_src
+  if [ -n "${1:-}" ]; then _aq_src="$1"; else _aq_src=$(cat); fi
+  printf '%s\n' "$_aq_src" | awk '
+    # A block opens on it( / test( and closes on the matching "});" at column 0-2.
+    function flush() {
+      if (open && nassert > 0 && nstrong == 0) {
+        printf "%d:weak_assertion_only\n", startline
+      }
+      open = 0; nassert = 0; nstrong = 0
+    }
+    /(^|[^.[:alnum:]_])(it|test)(\.(only|skip|todo))?[[:space:]]*\(/ {
+      flush(); open = 1; startline = NR; next
+    }
+    open && /expect[[:space:]]*\(/ {
+      nassert++
+      # A "strong" assertion inspects a concrete value: not toBeDefined/toBeTruthy/
+      # toBeFalsy/toBeNull/toBeUndefined, and not a bare toHaveBeenCalled().
+      if ($0 !~ /\.(toBeDefined|toBeTruthy|toBeFalsy|toBeNull|toBeUndefined|toBeInstanceOf)[[:space:]]*\(/ \
+          && $0 !~ /\.toHaveBeenCalled[[:space:]]*\([[:space:]]*\)/) {
+        nstrong++
+      }
+    }
+    open && /^\s*\}\);?\s*$/ { flush() }
+    END { flush() }
+  '
+}
+
+# Anti-pattern 6 exemption: `@assertion-justified: <reason>`, mirroring
+# `@mock-justified`. The reason must be at least 10 non-space characters -- an
+# annotation without a reason is not an exemption, which is what stops the escape
+# hatch from becoming the default.
+#
+# $1 = the source text to inspect.
+is_assertion_justified() {
+  printf '%s\n' "$1" \
+    | grep -oE '@assertion-justified:[[:space:]]*[^[:space:]*].*' \
+    | sed 's/^@assertion-justified:[[:space:]]*//' \
+    | tr -d '\r' \
+    | awk 'length($0) >= 10 { found = 1; exit } END { exit(found ? 0 : 1) }'
+}

package/hooks/lib/diff-coverage.sh

@@ -0,0 +1,223 @@
+#!/bin/bash
+# Changed-line coverage for Gate 5 (#600).
+#
+# Gate 5 compares GLOBAL coverage against a floor (default 80, hard floor 60).
+# A commit that changes five lines and tests none of them passes as long as the
+# global number has not dipped below that floor -- so the only thing the gate ever
+# measured about a change was the average of everything else in the repo. 指南
+# §10.1/§10.3 asks for three measures the repo never computed: changed-line
+# coverage (>=90%), changed-branch coverage (>=85%), and module coverage that does
+# not go DOWN.
+#
+# This library reads vitest's v8 `coverage/coverage-final.json` (already produced;
+# the json reporter is on) plus the staged diff, and answers exactly one question
+# per changed file: of the lines this commit touched, how many did the tests
+# execute? Staged-only is deliberate -- the question is about the commit, and
+# scanning the working tree would report on code that is not being committed.
+#
+# Fail-closed on unmeasurable inputs (#570): no coverage file, unparseable JSON, or
+# a changed file absent from the coverage report all mean "not measured", and "not
+# measured" must never render as "passed". The one legitimate absence is a file
+# the coverage provider deliberately omits for being non-executable (type-only
+# `.d.ts`, or a source with no statements at all) -- that is reported as `n/a`,
+# not as 0%, because scoring it 0% would block every constants module.
+#
+# The whole computation lives in one node program rather than shell+awk because
+# coverage-final.json is a nested object keyed by absolute path; parsing it in
+# shell means three places to get the path normalisation wrong, and this repo has
+# already paid for that mistake twice (#632, #633).
+
+# Report one line per changed file: `<file> <covered> <total> <pct> <verdict>`.
+#
+# $1 = coverage-final.json path
+# $2 = file with changed line ranges, one per line: `<path> <start> <end>`
+# $3 = line-coverage threshold (default 90)
+# $4 = branch-coverage threshold (default 85)
+#
+# Prints:
+#   RESULT <covered> <total> <pct>          aggregate over all changed lines
+#   MISSING <file>                          changed file with no coverage entry
+#   UNCOVERED <file> <line> [<line>...]     individual uncovered changed lines
+#   BRANCH <covered> <total> <pct>          aggregate over changed branches
+#   NA <file>                               nothing executable changed
+# and exits 0 when the aggregate meets both thresholds, 1 otherwise, 2 when the
+# input could not be read at all (fail-closed).
+compute_diff_coverage() {
+  local coverage_file="$1" changes_file="$2"
+  local line_threshold="${3:-90}" branch_threshold="${4:-85}"
+
+  if [ ! -f "$coverage_file" ]; then
+    echo "ERROR no_coverage_data"
+    return 2
+  fi
+  if [ ! -f "$changes_file" ]; then
+    echo "ERROR no_changes"
+    return 2
+  fi
+
+  node -e '
+    const fs = require("fs");
+    const [covPath, chgPath, lineT, branchT] = process.argv.slice(1);
+    const lineThreshold = Number(lineT);
+    const branchThreshold = Number(branchT);
+
+    let cov;
+    try {
+      cov = JSON.parse(fs.readFileSync(covPath, "utf8"));
+    } catch (e) {
+      console.log("ERROR unparsable_coverage");
+      process.exit(2);
+    }
+
+    // Coverage keys are absolute paths emitted by the reporter; the diff paths are
+    // repo-relative with forward slashes. Reduce both to a comparable suffix so a
+    // Windows drive letter or a leading "./" cannot make every file "missing".
+    const norm = (p) => String(p).replace(/\\/g, "/").replace(/^\.\//, "").toLowerCase();
+    const bySuffix = new Map();
+    for (const [absPath, entry] of Object.entries(cov)) {
+      const n = norm(absPath);
+      bySuffix.set(n, entry);
+      // Also index by the trailing two segments so a repo-relative "src/x.ts"
+      // can find "/abs/root/src/x.ts" without guessing the root.
+      const segs = n.split("/");
+      if (segs.length >= 2) bySuffix.set(segs.slice(-2).join("/"), entry);
+    }
+    const find = (p) => bySuffix.get(norm(p)) || bySuffix.get(norm(p).split("/").slice(-2).join("/"));
+
+    // Changed line ranges, keyed by file.
+    const wanted = new Map();
+    for (const raw of fs.readFileSync(chgPath, "utf8").split(/\r?\n/)) {
+      const line = raw.trim();
+      if (!line) continue;
+      const parts = line.split(/\s+/);
+      if (parts.length !== 3) continue;
+      const [file, s, e] = parts;
+      const start = Number(s);
+      const end = Number(e);
+      if (!Number.isFinite(start) || !Number.isFinite(end)) continue;
+      if (!wanted.has(file)) wanted.set(file, []);
+      wanted.get(file).push([start, end]);
+    }
+
+    let covLines = 0, totLines = 0, covBranches = 0, totBranches = 0;
+    for (const [file, ranges] of wanted) {
+      const entry = find(file);
+      if (!entry) { console.log("MISSING " + file); continue; }
+
+      // statementMap/s and branchMap/b are OBJECTS keyed by numeric string in the
+      // v8 provider this repo uses (they are arrays under the babel provider).
+      // Iterate whichever shape is present rather than assuming one.
+      const stmts = Array.isArray(entry.statementMap)
+        ? entry.statementMap.map((v, i) => [String(i), v])
+        : Object.entries(entry.statementMap || {});
+      const stmtHits = entry.s || {};
+      const brs = Array.isArray(entry.branchMap)
+        ? entry.branchMap.map((v, i) => [String(i), v])
+        : Object.entries(entry.branchMap || {});
+      const brHits = entry.b || {};
+
+      const inRange = (ln) => ranges.some(([s, e]) => ln >= s && ln <= e);
+      let fileTotal = 0, fileCov = 0;
+      const uncovered = [];
+      for (const [id, meta] of stmts) {
+        const ln = meta && meta.start ? meta.start.line : (meta && meta.line);
+        if (!ln || !inRange(ln)) continue;
+        fileTotal++;
+        if (Number(stmtHits[id] || 0) > 0) fileCov++;
+        else uncovered.push(ln);
+      }
+
+      let fileBTotal = 0, fileBCov = 0;
+      for (const [id, meta] of brs) {
+        const ln = meta && meta.line ? meta.line : (meta && meta.loc && meta.loc.start ? meta.loc.start.line : 0);
+        if (!ln || !inRange(ln)) continue;
+        const counts = brHits[id];
+        const arr = Array.isArray(counts) ? counts : [counts || 0];
+        for (const c of arr) {
+          fileBTotal++;
+          if (Number(c) > 0) fileBCov++;
+        }
+      }
+
+      covLines += fileCov; totLines += fileTotal;
+      covBranches += fileBCov; totBranches += fileBTotal;
+
+      if (fileTotal === 0 && fileBTotal === 0) { console.log("NA " + file); continue; }
+      if (uncovered.length) {
+        console.log("UNCOVERED " + file + " " + uncovered.join(" "));
+      }
+    }
+
+    const pct = (c, t) => (t === 0 ? 100 : Math.round((c / t) * 1000) / 10);
+    console.log("RESULT " + covLines + " " + totLines + " " + pct(covLines, totLines));
+    console.log("BRANCH " + covBranches + " " + totBranches + " " + pct(covBranches, totBranches));
+
+    // Nothing executable changed at all: not a failure, and not a pass either --
+    // the caller decides (docs-only commits SKIP upstream).
+    if (totLines === 0 && totBranches === 0) process.exit(0);
+    const lineOk = totLines === 0 || pct(covLines, totLines) >= lineThreshold;
+    const branchOk = totBranches === 0 || pct(covBranches, totBranches) >= branchThreshold;
+    process.exit(lineOk && branchOk ? 0 : 1);
+  ' "$coverage_file" "$changes_file" "$line_threshold" "$branch_threshold"
+}
+
+# Emit `<path> <start> <end>` triples for every added line range in the STAGED diff.
+#
+# Only files the coverage provider can measure are worth listing: a docs-only or
+# config-only diff yields no rows, which makes the caller's "nothing executable
+# changed" branch reachable instead of comparing 0/0.
+#
+# $1 = optional output file (defaults to stdout).
+staged_added_line_ranges() {
+  # Prints `<path> <start> <end>` to STDOUT; the caller redirects. Deliberately not
+  # "print to $1": awk's `> file` redirect is not portable across the awk builds on
+  # this project's target platforms (the Windows Git Bash awk silently wrote
+  # nothing), and a range extractor that yields an empty list makes every diff
+  # coverage result vacuously 100%.
+  #
+  # --unified=0 gives one `@@ -a,b +c,d @@` header per contiguous change, so the
+  # added range is exactly +c,d and no context lines need filtering. A header with
+  # no ",d" means a single-line change.
+  git diff --cached --unified=0 --no-color --diff-filter=ACM 2>/dev/null \
+    | awk '
+        /^\+\+\+ / {
+          path = $2
+          sub(/^b\//, "", path)
+          next
+        }
+        /^@@ / {
+          if (path == "" || path == "/dev/null") next
+          if (path !~ /\.(ts|tsx|js|jsx|mjs|cjs|py|go|java|kt|cs|scala|sh|bats|ps1)$/) next
+          line = $0
+          sub(/^@@ [^+]*\+/, "", line)
+          sub(/[^0-9,].*$/, "", line)
+          n = split(line, parts, ",")
+          start = parts[1] + 0
+          len = (n > 1 ? parts[2] + 0 : 1)
+          print path " " start " " (start + len - 1)
+          next
+        }
+      '
+  return 0
+}
+
+# Read a numeric threshold from .xp-gate/test-profile.yaml, falling back to the
+# documented default (指南 §10.1: 90% lines, 85% branches) when the file or key is
+# absent. Kept here, next to its only consumer, so the two can never drift.
+#
+# $1 = key name (diff_coverage_lines | diff_coverage_branches)
+# $2 = default
+diff_coverage_threshold() {
+  local key="$1" fallback="$2" profile=".xp-gate/test-profile.yaml"
+  if [ ! -f "$profile" ]; then
+    printf '%s' "$fallback"
+    return 0
+  fi
+  local value
+  value=$(grep -E "^[[:space:]]*${key}[[:space:]]*:" "$profile" 2>/dev/null \
+    | head -1 | sed 's/^[^:]*:[[:space:]]*//' | tr -d '"'"'"' \r')
+  case "$value" in
+    ''|*[!0-9.]*) printf '%s' "$fallback" ;;
+    *) printf '%s' "$value" ;;
+  esac
+}

package/hooks/pre-commit

@@ -402,6 +402,15 @@ source_gate_lib "${AUDIT_SCRIPT_DIR}/lib/docs-only.sh"
 # so the fail-closed contract is unit-testable without executing this hook.
 source_gate_lib "${AUDIT_SCRIPT_DIR}/lib/test-failure.sh"
 
+# Issue #602: test-suite hygiene detectors (.only / .skip / deleted test files),
+# sourced so the same vocabulary is unit-testable and reusable by Gate 5d (#601).
+source_gate_lib "${AUDIT_SCRIPT_DIR}/lib/assertion-quality.sh"
+
+# Issue #600: changed-line coverage (指南 §10.1/§10.3), sourced for the same reason --
+# a shell-only parse of coverage-final.json would be a third place to get Windows
+# path normalisation wrong, and this repo has paid for that twice (#632, #633).
+source_gate_lib "${AUDIT_SCRIPT_DIR}/lib/diff-coverage.sh"
+
 # Issue #477: Gate 2's jscpd config probe and outcome classification, same reason.
 source_gate_lib "${AUDIT_SCRIPT_DIR}/lib/jscpd-run.sh"
 
@@ -2228,6 +2237,121 @@ if [ "$PROJECT_LANG" = "documentation-only" ] || [ "$DOCS_ONLY_COMMIT" = true ];
   GATE_5_DETAIL="docs_only_change"
 
 else
+  # ========================================================================
+  # Gate 5-FOCUS / Gate 5-DELETE (#602): the two quietest ways to "fix" a red
+  # build are to commit a `.only` (CI then runs one case and reports green) and
+  # to delete a test file with no replacement (the safety net vanishes with no
+  # signal). 指南 §9.5/§12 forbid both. Gate 5a guards the ADD side -- "a new
+  # source file must have a test" -- so guarding only that side left the
+  # constraint asymmetric: tests could be silently removed but never silently
+  # added, which is backwards from what protects the codebase.
+  #
+  # Runs before the expensive Gate 5a machinery so a `.only` commit fails in
+  # milliseconds instead of after a full test run.
+  # ========================================================================
+  GATE_5_FOCUS_BLOCKED=0
+  GATE_5_SKIP_COUNT=0
+  GATE_5_DELETED_TESTS=""
+  if declare -f classify_test_focus >/dev/null 2>&1; then
+    STAGED_TEST_FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null \
+      | grep -E '\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs|py|go|java|kt|cs|scala|ps1)$|(^|/)(test_[^/]*\.py|[^/]*_test\.(py|go))$' || true)
+    if [ -n "$STAGED_TEST_FILES" ]; then
+      while IFS= read -r _tf; do
+        [ -n "$_tf" ] || continue
+        _tf_content=$(git show ":$tf" 2>/dev/null) || _tf_content=$(cat "$_tf" 2>/dev/null || true)
+        [ -n "$_tf_content" ] || continue
+
+        # --- focus markers: BLOCK ---
+        _focus_hits=$(printf '%s\n' "$_tf_content" | classify_test_focus || true)
+        if [ -n "$_focus_hits" ]; then
+          # XP_GATE_ALLOW_ONLY=1 is an explicit, audited override for the one
+          # legitimate case (debugging an unrelated failure mid-bisect). It is
+          # opt-in per run and printed, never silent.
+          if [ "${XP_GATE_ALLOW_ONLY:-0}" = "1" ]; then
+            echo "⚠️  WARN - focus marker in $_tf (allowed by XP_GATE_ALLOW_ONLY=1)"
+            record_gate_audit "gate-5-focus-override" "focus-override" "WARN" 1 "$GATE_5_START" "file=$_tf"
+          else
+            echo "❌ BLOCKED - focus marker(s) in $_tf:"
+            printf '%s\n' "$_focus_hits" | sed 's/^/     /'
+            GATE_5_FOCUS_BLOCKED=$((GATE_5_FOCUS_BLOCKED + 1))
+          fi
+        fi
+
+        # --- skip markers: WARN unless justified ---
+        _skip_hits=$(printf '%s\n' "$_tf_content" | classify_test_skip || true)
+        if [ -n "$_skip_hits" ]; then
+          if is_skip_justified "$_tf_content"; then
+            echo "ℹ️  Skipped case(s) in $_tf are justified via @skip-justified."
+          else
+            _skip_n=$(printf '%s\n' "$_skip_hits" | wc -l | tr -d ' ')
+            GATE_5_SKIP_COUNT=$((GATE_5_SKIP_COUNT + _skip_n))
+            echo "⚠️  WARN - $_skip_n skipped case(s) in $_tf without @skip-justified: <reason>"
+          fi
+        fi
+        # --- Gate 5d (#601): assertion quality ---
+        # 指南 §9.2 forbids six assertion anti-patterns, and until now nothing in
+        # XP-Gate looked at assertions at all: Gate M2/M3 examine how test doubles
+        # are built, never whether the test asserts anything. Tautologies and
+        # empty catches are BLOCK (certainly vacuous); weak-only / mock-echo /
+        # call-order shapes WARN, because each can be legitimate and blocking a
+        # legal style trains people to add justification annotations until the
+        # annotation stops meaning anything.
+        if declare -f classify_tautological_assertions >/dev/null 2>&1; then
+          if is_assertion_justified "$_tf_content"; then
+            echo "ℹ️  Assertion style in $_tf is justified via @assertion-justified."
+          else
+            _tauto=$(printf '%s\n' "$_tf_content" | classify_tautological_assertions || true)
+            _swallow=$(printf '%s\n' "$_tf_content" | classify_swallowed_errors || true)
+            _weak=$(printf '%s\n' "$_tf_content" | classify_weak_assertions || true)
+            if [ -n "$_tauto" ]; then
+              echo "❌ BLOCKED - tautological assertion(s) in $_tf (cannot fail):"
+              printf '%s\n' "$_tauto" | sed 's/^/     /'
+              echo "     See skills/test-driven-development/testing-anti-patterns.md"
+              GATE_5_FOCUS_BLOCKED=$((GATE_5_FOCUS_BLOCKED + 1))
+            fi
+            if [ -n "$_swallow" ]; then
+              echo "❌ BLOCKED - empty catch in $_tf swallows the failure it guards:"
+              printf '%s\n' "$_swallow" | sed 's/^/     /'
+              echo "     See skills/test-driven-development/testing-anti-patterns.md"
+              GATE_5_FOCUS_BLOCKED=$((GATE_5_FOCUS_BLOCKED + 1))
+            fi
+            if [ -n "$_weak" ]; then
+              echo "⚠️  WARN - test block(s) in $_tf assert only weak properties:"
+              printf '%s\n' "$_weak" | sed 's/^/     /'
+              echo "     toBeDefined/toBeTruthy alone cannot detect a wrong value."
+              GATE_5_SKIP_COUNT=$((GATE_5_SKIP_COUNT + $(printf '%s\n' "$_weak" | wc -l | tr -d ' ')))
+            fi
+          fi
+        fi
+      done <<< "$STAGED_TEST_FILES"
+
+      # --- deleted test files: WARN ---
+      DELETED_LIST=$(mktemp 2>/dev/null || echo "${TMPDIR:-/tmp}/xp-deleted-$$")
+      ADDED_LIST=$(mktemp 2>/dev/null || echo "${TMPDIR:-/tmp}/xp-added-$$")
+      git diff --cached --name-only --diff-filter=D > "$DELETED_LIST" 2>/dev/null || true
+      git diff --cached --name-only --diff-filter=A > "$ADDED_LIST" 2>/dev/null || true
+      GATE_5_DELETED_TESTS=$(classify_deleted_tests "$DELETED_LIST" "$ADDED_LIST" || true)
+      rm -f "$DELETED_LIST" "$ADDED_LIST"
+      if [ -n "$GATE_5_DELETED_TESTS" ]; then
+        echo "⚠️  WARN - test file(s) deleted with no same-named replacement:"
+        printf '%s\n' "$GATE_5_DELETED_TESTS" | sed 's/^/     /'
+        echo "     Deleting a test removes the safety net (指南 §9.5). If the code is"
+        echo "     genuinely gone, say so in the commit body; otherwise restore it."
+      fi
+    fi
+  fi
+
+  if [ "$GATE_5_FOCUS_BLOCKED" -gt 0 ]; then
+    echo ""
+    echo "❌ BLOCKED - Gate 5: $GATE_5_FOCUS_BLOCKED test-hygiene violation(s) (see above)."
+    echo "   Focus markers (.only/fit/fdescribe) make CI run one case and report green;"
+    echo "   tautological assertions and empty catches verify nothing at all."
+    echo "   See skills/test-driven-development/testing-anti-patterns.md"
+    echo "   Remove them, or add '@assertion-justified: <reason>' for a reviewed exception."
+    record_gate_audit "gate-5-focus" "test-focus" "FAIL" "$GATE_5_FOCUS_BLOCKED" "$GATE_5_START" "blocked=1"
+    exit 1
+  fi
+
   # ========================================================================
   # Gate 5a: Test-Source File Pairing Check
   # New .ts/.tsx files: BLOCK (no corresponding test → commit rejected)
@@ -3086,6 +3210,57 @@ else
           else
             echo "TypeScript coverage: ${COVERAGE_PERCENT}% ✅ (≥ ${COVERAGE_THRESHOLD:-80}%)"
           fi
+
+          # ---- Diff coverage (#600): 指南 §10.1/§10.3 ----
+          # The block above measures the WHOLE repo. A commit that changes five
+          # lines and tests none of them passes as long as the global average has
+          # not dipped -- so the only thing that gate ever knew about THIS change
+          # was the average of everything else. This block asks the narrower and
+          # more useful question: of the lines this commit touches, how many did
+          # the tests execute?
+          #
+          # Skipped on a subset run, like the global check above: a partial run
+          # legitimately leaves most changed lines unexecuted because the tests
+          # covering them were deselected, and reporting that as low coverage
+          # would punish the smart-selection feature for working.
+          if declare -f compute_diff_coverage >/dev/null 2>&1 \
+             && [ "${PARTIAL_TEST_RUN:-false}" != "true" ] \
+             && [ -f "coverage/coverage-final.json" ]; then
+            DIFF_COV_RANGES=$(mktemp 2>/dev/null || echo "${TMPDIR:-/tmp}/diffcov-$$")
+            DIFF_COV_LINE_T=$(diff_coverage_threshold diff_coverage_lines 90)
+            DIFF_COV_BRANCH_T=$(diff_coverage_threshold diff_coverage_branches 85)
+            staged_added_line_ranges > "$DIFF_COV_RANGES" 2>/dev/null || true
+            if [ -s "$DIFF_COV_RANGES" ]; then
+              DIFF_COV_OUT=$(compute_diff_coverage coverage/coverage-final.json \
+                "$DIFF_COV_RANGES" "$DIFF_COV_LINE_T" "$DIFF_COV_BRANCH_T" 2>&1)
+              DIFF_COV_RC=$?
+              DIFF_COV_RESULT=$(printf '%s\n' "$DIFF_COV_OUT" | grep '^RESULT ' | head -1)
+              DIFF_COV_BRANCH=$(printf '%s\n' "$DIFF_COV_OUT" | grep '^BRANCH ' | head -1)
+              if [ "$DIFF_COV_RC" -eq 0 ]; then
+                echo "Changed-line coverage: ${DIFF_COV_RESULT#RESULT }% ✅ (lines, ≥ ${DIFF_COV_LINE_T}%)"
+                if printf '%s\n' "$DIFF_COV_OUT" | grep -q '^NA '; then
+                  printf '%s\n' "$DIFF_COV_OUT" | grep '^NA ' | sed 's/^NA /     n\/a (no executable statements): /'
+                fi
+              elif [ "$DIFF_COV_RC" -eq 1 ]; then
+                echo "❌ BLOCKED - Changed-line coverage below threshold (指南 §10.1)."
+                echo "   Lines: ${DIFF_COV_RESULT#RESULT } (need ≥ ${DIFF_COV_LINE_T}%)"
+                echo "   Branches: ${DIFF_COV_BRANCH#BRANCH } (need ≥ ${DIFF_COV_BRANCH_T}%)"
+                printf '%s\n' "$DIFF_COV_OUT" | grep '^UNCOVERED ' | sed 's/^UNCOVERED /   untested changed lines: /'
+                printf '%s\n' "$DIFF_COV_OUT" | grep '^MISSING ' | sed 's/^MISSING /   no coverage data for: /'
+                echo "   Add tests for the lines listed above, or set diff_coverage_lines in"
+                echo "   .xp-gate/test-profile.yaml if this file genuinely cannot be unit-tested."
+                rm -f "$DIFF_COV_RANGES"
+                exit 1
+              else
+                # #570: not measurable is not a pass. (The global check above already
+                # blocked on a missing/corrupt report; this arm covers the narrower
+                # case where coverage-final.json itself is unreadable.)
+                echo "⚠️  Changed-line coverage could not be measured (coverage-final.json unreadable)."
+                echo "   See: $(printf '%s\n' "$DIFF_COV_OUT" | grep '^ERROR ' | head -1)"
+              fi
+            fi
+            rm -f "$DIFF_COV_RANGES"
+          fi
         else
           # #570: an unparseable report is not a pass. Silently continuing here
           # meant a corrupt or unexpected-shape coverage-summary.json disabled the

package/lib/mattpocock-license-verdict.json

@@ -2,6 +2,6 @@
   "verdict": "PASS",
   "license_type": "MIT",
   "sha256": "0e7ac423bf2c6e223b7c5b156f8cf72da49d748e56a1641402c31f22ad07dbb5",
-  "checked_at": "2026-10-30T13:23:44.380Z",
+  "checked_at": "2026-10-30T14:08:10.171Z",
   "source": "network"
 }