@boyingliu01/xp-gate 0.30.3 → 0.30.5

package/gate-10.sh

@@ -91,11 +91,27 @@ else
       [ -n "$_semgrep_file" ] || continue
       SEMGREP_FILE_COUNT=$((SEMGREP_FILE_COUNT + 1))
       SEMGREP_ARGS+=("--include=${_semgrep_file##*/}")
-      _semgrep_dir="./${_semgrep_file%/*}"
-      # A repo-root file has no directory component ("./x.ts" strips to "./").
-      [ "$_semgrep_dir" = "./" ] && _semgrep_dir="."
+      # A repo-root file has no slash at all, so "%/*" returns it unchanged and
+      # the old comment's assumption (`"./x.ts" strips to "./"`) never held:
+      # the target became the FILE path dressed as a directory ("./x.ts").
+      # Strip only when a slash is present; otherwise the target is the repo
+      # root, spelled ".". Scanning "." widens the scan to the whole tree, which
+      # is the safe side (see the note above) and is what a root-level staged
+      # file requires in order to be analysed at all.
+      case "$_semgrep_file" in
+        */*) _semgrep_dir="./${_semgrep_file%/*}" ;;
+        *)   _semgrep_dir="." ;;
+      esac
+      # #558: dedup must match WHOLE lines. The previous `case "$SEEN" in
+      # *"$_semgrep_dir"*)` was an unanchored substring test: once
+      # ./fastdl/tests was recorded, the parent ./fastdl matched it and was
+      # never added as a target, so a staged fastdl/a.py contributed an
+      # --include= with no directory to scan it in. Nothing errored and nothing
+      # was reported -- the file was simply not analysed, which for a security
+      # gate is the worst outcome: a silent net loss that looks like a pass.
+      # Sibling prefixes (src/api vs src/app) collapsed the same way.
       case "$SEMGREP_DIRS_SEEN" in
-        *"$_semgrep_dir"*) : ;;
+        *$'\n'"$_semgrep_dir"$'\n'*) : ;;
         *) SEMGREP_ARGS+=("$_semgrep_dir"); SEMGREP_DIRS_SEEN="$SEMGREP_DIRS_SEEN$_semgrep_dir"$'\n' ;;
       esac
     done <<EOF
@@ -131,9 +147,41 @@ EOF
     # code is demoted to "did the tool itself run". --error stays OFF: it would
     # add nothing the JSON does not already provide, and keeping it off leaves
     # failure exit codes unambiguous for the #475 diagnostics path.
-    SEMGREP_STDOUT_FILE=$(mktemp)
-    SEMGREP_OUTPUT=$("$SEMGREP_CMD" scan --config=p/security-audit --json --disable-version-check "${SEMGREP_ARGS[@]}" 2>&1 >"$SEMGREP_STDOUT_FILE")
-    SEMGREP_EXIT=$?
+    # #559: bound the run. Without a timeout, a wedged semgrep blocks the
+    # invocation for as long as its process lives; the fail-closed verdict logic
+    # below is correct but unreachable, so the hook hangs instead of judging.
+    # A gate that can wedge an interactive `git commit` gets bypassed with
+    # --no-verify, which is worse than any verdict it could have produced.
+    # `-k` after the primary signal: pysemgrep spinning in a syscall ignores
+    # SIGTERM, and the shipped 0.29 code used the same `-k 10` shape.
+    SEMGREP_TIMEOUT_S="${XP_GATE_SEMGREP_TIMEOUT:-180}"
+    SEMGREP_TIMED_OUT=false
+    if command -v timeout >/dev/null 2>&1; then
+      SEMGREP_STDOUT_FILE=$(mktemp)
+      SEMGREP_OUTPUT=$(timeout -k 10 "$SEMGREP_TIMEOUT_S" \
+        "$SEMGREP_CMD" scan --config=p/security-audit --json --disable-version-check \
+        "${SEMGREP_ARGS[@]}" 2>&1 >"$SEMGREP_STDOUT_FILE")
+      SEMGREP_EXIT=$?
+      # 124 = timeout's own "I gave up" code. 137 = 128+SIGKILL, which is what
+      # `timeout -k` returns when the child ignored SIGTERM and had to be
+      # killed -- measured with a semgrep stand-in that traps TERM. Both mean
+      # "bounded, no verdict", so both must be reported as a timeout; checking
+      # only 124 told the user their semgrep was unparseable when in fact the
+      # scan had been cut off.
+      case "$SEMGREP_EXIT" in
+        124|137) SEMGREP_TIMED_OUT=true ;;
+      esac
+    else
+      # No `timeout` on this platform (stock macOS). Say so: an unbounded run
+      # nobody mentioned is exactly how #559 stayed invisible for a whole
+      # release. The scan still runs -- refusing to scan would be a worse
+      # trade -- but the unbounded window is now stated.
+      echo "     ⚠️  'timeout' command not available — semgrep runs UNBOUNDED (install coreutils or set up gtimeout)"
+      SEMGREP_STDOUT_FILE=$(mktemp)
+      SEMGREP_OUTPUT=$("$SEMGREP_CMD" scan --config=p/security-audit --json --disable-version-check \
+        "${SEMGREP_ARGS[@]}" 2>&1 >"$SEMGREP_STDOUT_FILE")
+      SEMGREP_EXIT=$?
+    fi
 
     # One node pass over the JSON: first line = verdict counts, remaining lines =
     # finding details. The severity vocabulary is the UNION of the two scales
@@ -175,7 +223,18 @@ console.log("");});
     if [ "$V_PARSE" != "OK" ] || [ -z "$V_RESULTS" ] || [ -z "$V_ERRORS" ] || [ -z "$V_BLOCKING" ] || [ -z "$V_WARNINGS" ]; then
       # Unparseable output: nothing the exit code claims can be trusted (#518).
       # Fail closed — SKIP with diagnostics, never a PASS.
-      echo "     ⚠️  semgrep output unparseable or verdict fields missing (exit code ${SEMGREP_EXIT}) — cannot determine verdict"
+      #
+      # #559: name a timeout as a timeout. The generic "unparseable" message
+      # would be true but useless here -- it points at the JSON parser when the
+      # real problem is that the scan was cut off. Same verdict (SKIP), but a
+      # diagnosis the reader can act on.
+      if [ "$SEMGREP_TIMED_OUT" = true ]; then
+        echo "     ⏱️  semgrep exceeded ${SEMGREP_TIMEOUT_S}s and was killed — no verdict is possible"
+        echo "     This is NOT a finding and NOT a clean scan. Raise XP_GATE_SEMGREP_TIMEOUT"
+        echo "     if the repo legitimately takes longer; investigate if semgrep itself is wedged."
+      else
+        echo "     ⚠️  semgrep output unparseable or verdict fields missing (exit code ${SEMGREP_EXIT}) — cannot determine verdict"
+      fi
       if [ -n "$SEMGREP_OUTPUT" ]; then
         echo "     ── what semgrep reported on stderr ──"
         printf '%s\n' "$SEMGREP_OUTPUT" | tail -10 | sed 's/^/     /'
@@ -184,11 +243,19 @@ console.log("");});
         echo "     ── what semgrep wrote to stdout (tail) ──"
         printf '%s\n' "$SEMGREP_STDOUT_TAIL" | sed 's/^/     /'
       fi
-      echo "     ⏭️  SKIPPED - SAST (semgrep output unparseable)"
-      GATE_10_STATUS="SKIP"
-      # Consumed by the sourcing parent (pre-commit report JSON), not here.
-      # shellcheck disable=SC2034
-      GATE_10_REASON="output_unparseable"
+      if [ "$SEMGREP_TIMED_OUT" = true ]; then
+        echo "     ⏭️  SKIPPED - SAST (semgrep timed out after ${SEMGREP_TIMEOUT_S}s)"
+        GATE_10_STATUS="SKIP"
+        # Consumed by the sourcing parent (pre-commit report JSON), not here.
+        # shellcheck disable=SC2034
+        GATE_10_REASON="semgrep_timeout"
+      else
+        echo "     ⏭️  SKIPPED - SAST (semgrep output unparseable)"
+        GATE_10_STATUS="SKIP"
+        # Consumed by the sourcing parent (pre-commit report JSON), not here.
+        # shellcheck disable=SC2034
+        GATE_10_REASON="output_unparseable"
+      fi
     elif [ "$V_RESULTS" -eq 0 ] && { [ "$V_ERRORS" -gt 0 ] || [ "$SEMGREP_EXIT" -ne 0 ]; }; then
       # Nothing was scanned to a verdict: semgrep either failed outright
       # (nonzero exit) or completed but reported scan errors for every input

package/hooks/gate-10.sh

@@ -91,11 +91,27 @@ else
       [ -n "$_semgrep_file" ] || continue
       SEMGREP_FILE_COUNT=$((SEMGREP_FILE_COUNT + 1))
       SEMGREP_ARGS+=("--include=${_semgrep_file##*/}")
-      _semgrep_dir="./${_semgrep_file%/*}"
-      # A repo-root file has no directory component ("./x.ts" strips to "./").
-      [ "$_semgrep_dir" = "./" ] && _semgrep_dir="."
+      # A repo-root file has no slash at all, so "%/*" returns it unchanged and
+      # the old comment's assumption (`"./x.ts" strips to "./"`) never held:
+      # the target became the FILE path dressed as a directory ("./x.ts").
+      # Strip only when a slash is present; otherwise the target is the repo
+      # root, spelled ".". Scanning "." widens the scan to the whole tree, which
+      # is the safe side (see the note above) and is what a root-level staged
+      # file requires in order to be analysed at all.
+      case "$_semgrep_file" in
+        */*) _semgrep_dir="./${_semgrep_file%/*}" ;;
+        *)   _semgrep_dir="." ;;
+      esac
+      # #558: dedup must match WHOLE lines. The previous `case "$SEEN" in
+      # *"$_semgrep_dir"*)` was an unanchored substring test: once
+      # ./fastdl/tests was recorded, the parent ./fastdl matched it and was
+      # never added as a target, so a staged fastdl/a.py contributed an
+      # --include= with no directory to scan it in. Nothing errored and nothing
+      # was reported -- the file was simply not analysed, which for a security
+      # gate is the worst outcome: a silent net loss that looks like a pass.
+      # Sibling prefixes (src/api vs src/app) collapsed the same way.
       case "$SEMGREP_DIRS_SEEN" in
-        *"$_semgrep_dir"*) : ;;
+        *$'\n'"$_semgrep_dir"$'\n'*) : ;;
         *) SEMGREP_ARGS+=("$_semgrep_dir"); SEMGREP_DIRS_SEEN="$SEMGREP_DIRS_SEEN$_semgrep_dir"$'\n' ;;
       esac
     done <<EOF
@@ -131,9 +147,41 @@ EOF
     # code is demoted to "did the tool itself run". --error stays OFF: it would
     # add nothing the JSON does not already provide, and keeping it off leaves
     # failure exit codes unambiguous for the #475 diagnostics path.
-    SEMGREP_STDOUT_FILE=$(mktemp)
-    SEMGREP_OUTPUT=$("$SEMGREP_CMD" scan --config=p/security-audit --json --disable-version-check "${SEMGREP_ARGS[@]}" 2>&1 >"$SEMGREP_STDOUT_FILE")
-    SEMGREP_EXIT=$?
+    # #559: bound the run. Without a timeout, a wedged semgrep blocks the
+    # invocation for as long as its process lives; the fail-closed verdict logic
+    # below is correct but unreachable, so the hook hangs instead of judging.
+    # A gate that can wedge an interactive `git commit` gets bypassed with
+    # --no-verify, which is worse than any verdict it could have produced.
+    # `-k` after the primary signal: pysemgrep spinning in a syscall ignores
+    # SIGTERM, and the shipped 0.29 code used the same `-k 10` shape.
+    SEMGREP_TIMEOUT_S="${XP_GATE_SEMGREP_TIMEOUT:-180}"
+    SEMGREP_TIMED_OUT=false
+    if command -v timeout >/dev/null 2>&1; then
+      SEMGREP_STDOUT_FILE=$(mktemp)
+      SEMGREP_OUTPUT=$(timeout -k 10 "$SEMGREP_TIMEOUT_S" \
+        "$SEMGREP_CMD" scan --config=p/security-audit --json --disable-version-check \
+        "${SEMGREP_ARGS[@]}" 2>&1 >"$SEMGREP_STDOUT_FILE")
+      SEMGREP_EXIT=$?
+      # 124 = timeout's own "I gave up" code. 137 = 128+SIGKILL, which is what
+      # `timeout -k` returns when the child ignored SIGTERM and had to be
+      # killed -- measured with a semgrep stand-in that traps TERM. Both mean
+      # "bounded, no verdict", so both must be reported as a timeout; checking
+      # only 124 told the user their semgrep was unparseable when in fact the
+      # scan had been cut off.
+      case "$SEMGREP_EXIT" in
+        124|137) SEMGREP_TIMED_OUT=true ;;
+      esac
+    else
+      # No `timeout` on this platform (stock macOS). Say so: an unbounded run
+      # nobody mentioned is exactly how #559 stayed invisible for a whole
+      # release. The scan still runs -- refusing to scan would be a worse
+      # trade -- but the unbounded window is now stated.
+      echo "     ⚠️  'timeout' command not available — semgrep runs UNBOUNDED (install coreutils or set up gtimeout)"
+      SEMGREP_STDOUT_FILE=$(mktemp)
+      SEMGREP_OUTPUT=$("$SEMGREP_CMD" scan --config=p/security-audit --json --disable-version-check \
+        "${SEMGREP_ARGS[@]}" 2>&1 >"$SEMGREP_STDOUT_FILE")
+      SEMGREP_EXIT=$?
+    fi
 
     # One node pass over the JSON: first line = verdict counts, remaining lines =
     # finding details. The severity vocabulary is the UNION of the two scales
@@ -175,7 +223,18 @@ console.log("");});
     if [ "$V_PARSE" != "OK" ] || [ -z "$V_RESULTS" ] || [ -z "$V_ERRORS" ] || [ -z "$V_BLOCKING" ] || [ -z "$V_WARNINGS" ]; then
       # Unparseable output: nothing the exit code claims can be trusted (#518).
       # Fail closed — SKIP with diagnostics, never a PASS.
-      echo "     ⚠️  semgrep output unparseable or verdict fields missing (exit code ${SEMGREP_EXIT}) — cannot determine verdict"
+      #
+      # #559: name a timeout as a timeout. The generic "unparseable" message
+      # would be true but useless here -- it points at the JSON parser when the
+      # real problem is that the scan was cut off. Same verdict (SKIP), but a
+      # diagnosis the reader can act on.
+      if [ "$SEMGREP_TIMED_OUT" = true ]; then
+        echo "     ⏱️  semgrep exceeded ${SEMGREP_TIMEOUT_S}s and was killed — no verdict is possible"
+        echo "     This is NOT a finding and NOT a clean scan. Raise XP_GATE_SEMGREP_TIMEOUT"
+        echo "     if the repo legitimately takes longer; investigate if semgrep itself is wedged."
+      else
+        echo "     ⚠️  semgrep output unparseable or verdict fields missing (exit code ${SEMGREP_EXIT}) — cannot determine verdict"
+      fi
       if [ -n "$SEMGREP_OUTPUT" ]; then
         echo "     ── what semgrep reported on stderr ──"
         printf '%s\n' "$SEMGREP_OUTPUT" | tail -10 | sed 's/^/     /'
@@ -184,11 +243,19 @@ console.log("");});
         echo "     ── what semgrep wrote to stdout (tail) ──"
         printf '%s\n' "$SEMGREP_STDOUT_TAIL" | sed 's/^/     /'
       fi
-      echo "     ⏭️  SKIPPED - SAST (semgrep output unparseable)"
-      GATE_10_STATUS="SKIP"
-      # Consumed by the sourcing parent (pre-commit report JSON), not here.
-      # shellcheck disable=SC2034
-      GATE_10_REASON="output_unparseable"
+      if [ "$SEMGREP_TIMED_OUT" = true ]; then
+        echo "     ⏭️  SKIPPED - SAST (semgrep timed out after ${SEMGREP_TIMEOUT_S}s)"
+        GATE_10_STATUS="SKIP"
+        # Consumed by the sourcing parent (pre-commit report JSON), not here.
+        # shellcheck disable=SC2034
+        GATE_10_REASON="semgrep_timeout"
+      else
+        echo "     ⏭️  SKIPPED - SAST (semgrep output unparseable)"
+        GATE_10_STATUS="SKIP"
+        # Consumed by the sourcing parent (pre-commit report JSON), not here.
+        # shellcheck disable=SC2034
+        GATE_10_REASON="output_unparseable"
+      fi
     elif [ "$V_RESULTS" -eq 0 ] && { [ "$V_ERRORS" -gt 0 ] || [ "$SEMGREP_EXIT" -ne 0 ]; }; then
       # Nothing was scanned to a verdict: semgrep either failed outright
       # (nonzero exit) or completed but reported scan errors for every input

package/hooks/pre-push

@@ -47,11 +47,28 @@ write_pre_push_report() {
   commit_hash=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
   verdict=$([ "$exit_code" -eq 0 ] && echo "PASS" || echo "BLOCKED")
   mkdir -p "$reports_dir"
+  # #544: the survivor detail is a JSON document, so it cannot be interpolated
+  # into this heredoc — a single quote in a path would break the Python source.
+  # Hand it to the child through the environment and let Python parse it, then
+  # store it serialised back into the `details` string domain (every value there
+  # is a string; the journal has broken before over mixed types).
+  export XP_GATE_M_SURVIVORS_JSON="${M_SURVIVORS_JSON:-}"
   python3 - <<PY 2>/dev/null || true
 import json
+import os
 from pathlib import Path
 pushed_files = '''${PUSHED_FILES:-}'''.splitlines()
 passed = 1 if '$verdict' == 'PASS' else 0
+# Absent stays absent: no key at all when nothing was measured, so a reader can
+# tell "not measured" from "measured: zero survivors" (#544).
+try:
+    _survivors_raw = os.environ.get('XP_GATE_M_SURVIVORS_JSON', '').strip()
+    survivors_detail = json.loads(_survivors_raw) if _survivors_raw else None
+except (ValueError, TypeError):
+    survivors_detail = None
+_m_details = {'skip_reason': '${GATE_M_SKIP_REASON:-}', 'duration_ms': '${M_DURATION_MS:-0}', 'mutation_score': '${M_SCORE:-}'}
+if survivors_detail is not None:
+    _m_details['survivors'] = json.dumps(survivors_detail, sort_keys=True)
 report = {
   'timestamp': '$timestamp',
   'trigger': 'pre-push',
@@ -67,15 +84,20 @@ report = {
   'gates': [
     {'id': 'MP', 'name': 'Gate-Script Mirror Parity', 'status': '${GATE_MP_STATUS:-SKIP}', 'details': {'duration_ms': '${MP_DURATION_MS:-0}'}},
     {'id': '10', 'name': 'Build Integrity', 'status': '${GATE_10_STATUS:-SKIP}', 'details': {}},
-    {'id': 'M', 'name': 'Mutation Testing', 'status': '${GATE_M_STATUS:-SKIP}', 'details': {'skip_reason': '${GATE_M_SKIP_REASON:-}', 'duration_ms': '${M_DURATION_MS:-0}', 'mutation_score': '${M_SCORE:-}'}},
-    {'id': 'M-Python', 'name': 'Mutation Testing (Python)', 'status': '${GATE_M_PYTHON_STATUS:-SKIP}', 'details': {}},
+    {'id': 'M', 'name': 'Mutation Testing', 'status': '${GATE_M_STATUS:-SKIP}', 'details': _m_details},
+    # #557 follow-up: this line read GATE_M_PYTHON_STATUS while the code assigns
+    # GATE_M_PY_STATUS, so the field always fell back to its SKIP default -- the
+    # "never write the real state" bug #557 set out to fix, still present for
+    # this one gate. The skip reason now travels with it, so a retro reader can
+    # tell "no Python here" from "timed out" from "mutmut missing".
+    {'id': 'M-Python', 'name': 'Mutation Testing (Python)', 'status': '${GATE_M_PY_STATUS:-SKIP}', 'details': {'skip_reason': '${GATE_M_PY_SKIP_REASON:-}'}},
     {'id': 'M-Go', 'name': 'Mutation Testing (Go)', 'status': '${GATE_M_GO_STATUS:-SKIP}', 'details': {}},
     {'id': 'M-Java', 'name': 'Mutation Testing (Java)', 'status': '${GATE_M_JAVA_STATUS:-SKIP}', 'details': {}},
     {'id': 'M-Kotlin', 'name': 'Mutation Testing (Kotlin)', 'status': '${GATE_M_KOTLIN_STATUS:-SKIP}', 'details': {}},
     {'id': 'M2', 'name': 'Mock Density (WARNING only)', 'status': '${GATE_M2_STATUS:-SKIP}', 'details': {}},
     {'id': 'ML', 'name': 'Mock Layering', 'status': '${GATE_M3_STATUS:-SKIP}', 'details': {}},
     {'id': 'UI', 'name': 'UI Sprint Gates', 'status': '${GATE_UI_STATUS:-SKIP}', 'details': {}},
-    {'id': 'MW', 'name': 'Code Walkthrough', 'status': '${GATE_DELPHI_STATUS:-SKIP}', 'details': {'remote': '$REMOTE', 'url': '$URL'}},
+    {'id': 'MW', 'name': 'Code Walkthrough', 'status': '${GATE_DELPHI_STATUS:-SKIP}', 'details': {'remote': '$REMOTE', 'url': '$URL', 'skip_reason': '${GATE_DELPHI_SKIP_REASON:-}'}},
     {'id': 'S', 'name': 'Sprint Flow Enforcement', 'status': '${GATE_S_STATUS:-SKIP}', 'details': {}}
   ],
   'warnings': [],
@@ -453,6 +475,15 @@ else
         # It is printed by gate-m.ts; take the last percentage it reported.
         M_SCORE=$(sed -n 's/.*[Mm]utation score[: ]*\([0-9][0-9]*\(\.[0-9][0-9]*\)\?\)%.*/\1/p' "$MUTATION_OUTPUT" 2>/dev/null | tail -1)
 
+        # #544: per-file survivor detail, so retro can answer "which module has
+        # the most surviving mutants". gate-m.ts emits one
+        # GATE_M_SURVIVORS_JSON= line; it is ABSENT when no report was produced,
+        # and absent must stay absent. An empty value means "not measured"; a
+        # written zero would mean "measured, no survivors". Only the former is
+        # ever true when the line is missing -- conflating the two is the whole
+        # of #544.
+        M_SURVIVORS_JSON=$(printf '%s\n' "$MUTATION_OUTPUT" | sed -n 's/^GATE_M_SURVIVORS_JSON=//p' | tail -1)
+
         case $MUTATION_EXIT in
           0)
             echo "✅ Gate M: PASS"
@@ -1066,6 +1097,15 @@ else
 # ============================================================================
 RESULT_FILE=".code-walkthrough-result.json"
 MW_SKIPPED=0
+# Journal status (#557 follow-up). The journal already read GATE_DELPHI_STATUS
+# but nothing ever assigned it, so Gate MW reported its SKIP default in every
+# report -- including pushes where the walkthrough was in fact verified. The
+# closing banner told the truth while the machine-readable journal did not, which
+# is the half-fix #557 was about.
+GATE_DELPHI_STATUS="SKIP"
+# Consumed by the journal heredoc (sourced/inherited boundary).
+# shellcheck disable=SC2034
+GATE_DELPHI_SKIP_REASON="not_run"
 
 # 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
@@ -1075,6 +1115,9 @@ MW_SKIPPED=0
 # documented this skip; the code did not implement it (drift fixed here).
 if [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "master" ]; then
   MW_SKIPPED=1
+  # Consumed by the journal heredoc (sourced/inherited boundary).
+  # shellcheck disable=SC2034
+  GATE_DELPHI_SKIP_REASON="main_branch_push"
   echo ""
   echo "   ℹ️  Gate MW skipped (pushing to ${CURRENT_BRANCH} — pre-reviewed via branch walkthrough)"
   echo ""
@@ -1144,6 +1187,13 @@ if ! VALIDATION_ERROR=$(node "$MW_VALIDATOR" "$RESULT_FILE" "$EXPECTED_COMMIT" "
   echo ""
   exit 1
 fi
+
+# The validator passed: record that the walkthrough was actually verified.
+# Consumed by the journal heredoc (sourced/inherited boundary).
+# shellcheck disable=SC2034
+GATE_DELPHI_STATUS="PASS"
+# shellcheck disable=SC2034
+GATE_DELPHI_SKIP_REASON=""
 fi
 
 # ============================================================================

package/lib/mattpocock-license-verdict.json

@@ -2,6 +2,6 @@
   "verdict": "PASS",
   "license_type": "MIT",
   "sha256": "0e7ac423bf2c6e223b7c5b156f8cf72da49d748e56a1641402c31f22ad07dbb5",
-  "checked_at": "2026-10-20T19:22:03.640Z",
+  "checked_at": "2026-10-21T05:03:41.149Z",
   "source": "network"
 }

package/mock-policy/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MOCK-POLICY KNOWLEDGE BASE
 
-**Generated:** 2026-10-20
-**Commit:** 03f6d10a
+**Generated:** 2026-10-21
+**Commit:** 4e1f8be0
 **Branch:** main
-**Version:** 0.30.3.0
+**Version:** 0.30.5.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-20
-**Commit:** 03f6d10a
+**Generated:** 2026-10-21
+**Commit:** 4e1f8be0
 **Branch:** main
-**Version:** 0.30.3.0
+**Version:** 0.30.5.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/mutation/__tests__/gate-m-survivors.test.ts

@@ -0,0 +1,167 @@
+/**
+ * @test #544 - Gate M survivor detail for retro
+ * @intent Verify Gate M reports per-file mutant outcome counts, not just a
+ *         score. #544: the pre-push journal carried
+ *         {skip_reason, duration_ms, mutation_score} and nothing else, so
+ *         `xp-gate retro` could not answer "which module has the most surviving
+ *         mutants". The data was never missing at the source: Stryker's JSON
+ *         reporter emits files[].nrOfSurvivedMutants, and stryker-types.ts
+ *         already declares it. The counts were dropped on the way through, then
+ *         buildMutationScores hardcoded {mutants: 0, killed: 0, survived: 0}.
+ *         Three zeros written next to a real score read as "measured: no
+ *         survivors" -- the same class of false success this project keeps
+ *         fixing, so unknown must stay absent, never zero.
+ * @covers REQ-MUT-001 AC-001
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  summarizeSurvivors,
+  buildMutationScores,
+  type StrykerReportLike,
+  type SurvivorSummary,
+} from '../gate-m';
+
+/** A report shaped like Stryker's JSON output. */
+function report(files: Record<string, [number, number, number]>): StrykerReportLike {
+  const entries = Object.entries(files);
+  const totalMutants = entries.reduce((a, [, v]) => a + v[0], 0);
+  const totalKilled = entries.reduce((a, [, v]) => a + v[1], 0);
+  const totalSurvived = entries.reduce((a, [, v]) => a + v[2], 0);
+  return {
+    mutationScore: totalMutants > 0 ? parseFloat(((totalKilled / totalMutants) * 100).toFixed(1)) : 100,
+    nrOfMutants: totalMutants,
+    nrOfKilledMutants: totalKilled,
+    nrOfSurvivedMutants: totalSurvived,
+    files: Object.fromEntries(
+      entries.map(([k, [m, kd, sv]]) => [k, {
+        mutationScore: m > 0 ? parseFloat(((kd / m) * 100).toFixed(1)) : 100,
+        nrOfMutants: m,
+        nrOfKilledMutants: kd,
+        nrOfSurvivedMutants: sv,
+      }])
+    ),
+  };
+}
+
+/** Narrow to a non-null summary, failing the test with a clear message. */
+function expectSummary(s: SurvivorSummary | null): SurvivorSummary {
+  expect(s).not.toBeNull();
+  if (s === null) throw new Error('expected a survivor summary, got null');
+  return s;
+}
+
+describe('AC-544: Gate M survivor detail', () => {
+  it('reports per-file survived counts from the Stryker report', () => {
+    const summary = expectSummary(summarizeSurvivors(report({
+      'src/mutation/gate-m.ts': [20, 8, 12],
+      'src/principles/analyzer.ts': [10, 3, 7],
+    })));
+
+    expect(summary.survivedByFile).toEqual({
+      'src/mutation/gate-m.ts': 12,
+      'src/principles/analyzer.ts': 7,
+    });
+  });
+
+  it('totals killed, survived and mutants', () => {
+    const summary = expectSummary(summarizeSurvivors(report({
+      'a.ts': [20, 8, 12],
+      'b.ts': [10, 3, 7],
+    })));
+
+    expect(summary.mutants).toBe(30);
+    expect(summary.killed).toBe(11);
+    expect(summary.survived).toBe(19);
+  });
+
+  it('orders survivedByFile worst-first so retro can take the top N', () => {
+    const summary = expectSummary(summarizeSurvivors(report({
+      'small.ts': [10, 9, 1],
+      'worst.ts': [10, 0, 10],
+      'middle.ts': [10, 5, 5],
+    })));
+
+    expect(Object.keys(summary.survivedByFile)).toEqual(['worst.ts', 'middle.ts', 'small.ts']);
+  });
+
+  it('caps the per-file map so one huge repo cannot bloat the journal', () => {
+    const many: Record<string, [number, number, number]> = {};
+    // Every file must have at least one survivor, otherwise this asserts on a
+    // smaller population than intended and the count below drifts.
+    for (let i = 0; i < 50; i++) {
+      const survived = (i % 9) + 1; // 1..9, never 0
+      many[`f${i}.ts`] = [10, 10 - survived, survived];
+    }
+
+    const summary = expectSummary(summarizeSurvivors(report(many), { limit: 20 }));
+
+    expect(Object.keys(summary.survivedByFile)).toHaveLength(20);
+    // Truncation must be visible, not silent: a capped list that looks complete
+    // is how "top 20" gets mistaken for "all files".
+    expect(summary.truncated).toBe(true);
+    expect(summary.filesWithSurvivors).toBe(50);
+  });
+
+  it('does not claim truncation when everything fits', () => {
+    const summary = expectSummary(summarizeSurvivors(report({ 'a.ts': [10, 5, 5] }), { limit: 20 }));
+    expect(summary.truncated).toBe(false);
+  });
+
+  it('omits files with zero survivors', () => {
+    const summary = expectSummary(summarizeSurvivors(report({
+      'clean.ts': [10, 10, 0],
+      'dirty.ts': [10, 4, 6],
+    })));
+
+    expect(summary.survivedByFile).toEqual({ 'dirty.ts': 6 });
+  });
+
+  it('degrades to null instead of inventing zeros when no report is available', () => {
+    // A missing/timed-out report must not be reported as "0 survivors" -- that
+    // is the #544 failure repeated. null means unknown.
+    expect(summarizeSurvivors(null)).toBeNull();
+  });
+
+  it('degrades to null when the report has no per-file section', () => {
+    expect(summarizeSurvivors({
+      mutationScore: 80,
+      nrOfMutants: 10,
+      nrOfKilledMutants: 8,
+      nrOfSurvivedMutants: 2,
+    })).toBeNull();
+  });
+});
+
+describe('buildMutationScores carries the real counts (#544)', () => {
+  it('reports measured mutant counts instead of hardcoded zeros', () => {
+    // The original defect: the score was real and the three counts beside it
+    // were literal zeros, which reads as "measured, no survivors". A consumer
+    // that trusts `survived: 0` concludes the module is adequately tested.
+    const scores = buildMutationScores({ 'a.ts': 78.4 }, {
+      'a.ts': { mutants: 30, killed: 25, survived: 5 },
+    });
+
+    expect(scores['a.ts']).toEqual({ score: 78.4, mutants: 30, killed: 25, survived: 5 });
+  });
+
+  it('leaves counts absent when they were never measured', () => {
+    // Absent must stay absent -- not fabricated as zero.
+    const scores = buildMutationScores({ 'a.ts': 50 }, {});
+
+    expect(scores['a.ts'].score).toBe(50);
+    expect(scores['a.ts'].mutants).toBeUndefined();
+    expect(scores['a.ts'].survived).toBeUndefined();
+  });
+
+  it('keeps a genuinely zero-survivor file at zero', () => {
+    // The distinction this whole change is about: measured zero is a real,
+    // meaningful value and must survive the trip.
+    const scores = buildMutationScores({ 'clean.ts': 100 }, {
+      'clean.ts': { mutants: 12, killed: 12, survived: 0 },
+    });
+
+    expect(scores['clean.ts'].survived).toBe(0);
+    expect(scores['clean.ts'].mutants).toBe(12);
+  });
+});

package/mutation/__tests__/mutation-mirror.test.ts

@@ -0,0 +1,49 @@
+/**
+ * @test #544 - the shipped mutation module stays a mirror of the source module
+ * @intent src/npm-package/mutation/ is published to npm ("mutation/" is in the
+ *         package `files` list) but has no automated mirror check, unlike the
+ *         hooks and adapters which check-hook-mirror.sh diffs. It IS maintained
+ *         as a byte-identical copy today, so a fix applied only to src/mutation/
+ *         would ship stale code to every consumer -- exactly the v0.27.3 failure
+ *         (#542) where a mirror-only fix was rolled back at publish. This guard
+ *         makes that class of drift red instead of silent, and it is what caught
+ *         the hardcoded zero counts still living in the package copy.
+ * @covers REQ-MUT-001 AC-001
+ */
+
+import { describe, it, expect } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+
+// This file lives at src/mutation/__tests__/, so the repo root is three levels
+// up (unlike scripts/__tests__/, which is two).
+const ROOT = path.resolve(__dirname, '..', '..', '..');
+const SRC = path.join(ROOT, 'src', 'mutation');
+const PKG = path.join(ROOT, 'src', 'npm-package', 'mutation');
+
+/** Files that must be identical in both trees. */
+const MIRRORED = ['gate-m.ts', 'update-baseline.ts', 'types.ts', 'detect-ai-test.ts', 'init-baseline.ts', 'stryker-types.ts'];
+
+describe('src/npm-package/mutation mirrors src/mutation', () => {
+  it.each(MIRRORED)('%s is byte-identical in both trees', (file) => {
+    const a = fs.readFileSync(path.join(SRC, file), 'utf8');
+    const b = fs.readFileSync(path.join(PKG, file), 'utf8');
+    expect(b, `${file} has drifted: edit src/mutation/${file} and copy it over`).toBe(a);
+  });
+
+  it('the mirror list is non-empty and every entry exists (anti-vacuity)', () => {
+    expect(MIRRORED.length).toBeGreaterThan(3);
+    for (const f of MIRRORED) {
+      expect(fs.existsSync(path.join(SRC, f)), `missing source ${f}`).toBe(true);
+      expect(fs.existsSync(path.join(PKG, f)), `missing mirror ${f}`).toBe(true);
+    }
+  });
+
+  it('the package copy carries the #544 fix, not the zero-filling original', () => {
+    // Anchor on the defect itself so this cannot pass with a stale-but-identical
+    // pair of pre-fix files.
+    const shipped = fs.readFileSync(path.join(PKG, 'gate-m.ts'), 'utf8');
+    expect(shipped).not.toContain('mutants: 0, killed: 0, survived: 0');
+    expect(shipped).toContain('MutantCounts');
+  });
+});

package/mutation/__tests__/update-baseline.test.ts

@@ -225,12 +225,16 @@ describe('update-baseline.ts - Mutation Baseline Update CLI', () => {
       const written = JSON.parse(
         (mockFs.default.writeFile as ReturnType<typeof vi.fn>).mock.calls[0][1] as string
       );
+      // #544: a new entry built from a score alone must NOT be seeded with
+      // mutants/killed/survived = 0. This assertion previously pinned those
+      // zeros as the expected behaviour, which made "nobody measured this file"
+      // indistinguishable from "measured, zero survivors" in every baseline
+      // written from the CLI. The fields are omitted instead.
       expect(written.scores['src/new.ts']).toEqual({
         score: 72.0,
-        mutants: 0,
-        killed: 0,
-        survived: 0
       });
+      expect(written.scores['src/new.ts'].mutants).toBeUndefined();
+      expect(written.scores['src/new.ts'].survived).toBeUndefined();
       // Old entry should still be present
       expect(written.scores['src/old.ts'].score).toBe(60.0);
     });

package/mutation/gate-m.ts

@@ -438,8 +438,9 @@ async function runAllRunners(
   groups: Map<string, string[]>,
   timeoutMs: number,
   cwd: string
-): Promise<Record<string, number | null>> {
+): Promise<{ scores: Record<string, number | null>; counts: Record<string, MutantCounts> }> {
   const fileScores: Record<string, number | null> = {};
+  const counts: Record<string, MutantCounts> = {};
 
   for (const [, files] of Array.from(groups.entries())) {
     const ext = path.extname(files[0]);
@@ -455,10 +456,10 @@ async function runAllRunners(
     }
 
     const result = await runner.run({ files, timeoutMs, cwd });
-    applyMutationResult(result, files, fileScores);
+    applyMutationResult(result, files, fileScores, counts);
   }
 
-  return fileScores;
+  return { scores: fileScores, counts };
 }
 
 /**
@@ -481,6 +482,7 @@ function applyMutationResult(
   outcome: MutationRunOutcome,
   files: string[],
   scores: Record<string, number | null>,
+  counts: Record<string, MutantCounts>,
 ): void {
   if (outcome.timedOut || outcome.error || !outcome.report) {
     for (const f of files) scores[f] = null;
@@ -490,11 +492,26 @@ function applyMutationResult(
   if (outcome.report.files) {
     for (const [fileKey, fileReport] of Object.entries(outcome.report.files)) {
       scores[fileKey] = fileReport.mutationScore;
+      // #544: keep the outcome counts the reporter already gave us. Dropping
+      // them here is what forced buildMutationScores to invent zeros later.
+      counts[fileKey] = {
+        mutants: fileReport.nrOfMutants,
+        killed: fileReport.nrOfKilledMutants,
+        survived: fileReport.nrOfSurvivedMutants,
+      };
     }
     return;
   }
 
-  for (const f of files) scores[f] = outcome.report.mutationScore;
+  const totals: MutantCounts = {
+    mutants: outcome.report.nrOfMutants,
+    killed: outcome.report.nrOfKilledMutants,
+    survived: outcome.report.nrOfSurvivedMutants,
+  };
+  for (const f of files) {
+    scores[f] = outcome.report.mutationScore;
+    counts[f] = totals;
+  }
 }
 
 // ── Main gateway ──
@@ -514,14 +531,117 @@ function logThresholdDetails(thresholds: FileThreshold[], baseline: MutationBase
   }
 }
 
-function buildMutationScores(fileScores: Record<string, number>): Record<string, MutationScore> {
+/**
+ * Per-file mutant outcome counts, as reported by the runner. Absent fields mean
+ * "the runner did not say", which is different from a measured zero -- the whole
+ * point of #544 is that those two must not collapse into each other.
+ */
+export interface MutantCounts {
+  mutants?: number;
+  killed?: number;
+  survived?: number;
+}
+
+export function buildMutationScores(
+  fileScores: Record<string, number>,
+  counts: Record<string, MutantCounts> = {},
+): Record<string, MutationScore> {
   const scores: Record<string, MutationScore> = {};
   for (const [file, score] of Object.entries(fileScores)) {
-    scores[file] = { score, mutants: 0, killed: 0, survived: 0 };
+    const c = counts[file];
+    const entry: MutationScore = { score } as MutationScore;
+    // Only attach what the runner actually reported. Writing `survived: 0` for
+    // an unmeasured file is what made a skipped run look like a clean one.
+    if (c) {
+      if (c.mutants !== undefined) entry.mutants = c.mutants;
+      if (c.killed !== undefined) entry.killed = c.killed;
+      if (c.survived !== undefined) entry.survived = c.survived;
+    }
+    scores[file] = entry;
   }
   return scores;
 }
 
+/**
+ * The subset of a runner report that survivor summarisation needs. Declared
+ * structurally rather than as a concrete Stryker type because every runner
+ * (Stryker, mutmut, gremlins, go-mutant) normalises to `MutationRunResult`,
+ * which carries the same field names -- the summary must work for all of them,
+ * not just the TS one.
+ */
+export interface StrykerReportLike {
+  mutationScore: number;
+  nrOfMutants: number;
+  nrOfKilledMutants: number;
+  nrOfSurvivedMutants: number;
+  files?: Record<string, {
+    mutationScore: number;
+    nrOfMutants: number;
+    nrOfKilledMutants: number;
+    nrOfSurvivedMutants: number;
+  }>;
+}
+
+/** Per-file mutant outcome detail for the pre-push journal (#544). */
+export interface SurvivorSummary {
+  /** Files with at least one surviving mutant, worst first, capped by `limit`. */
+  survivedByFile: Record<string, number>;
+  /**
+   * How many files actually had survivors. Present so a capped map can be told
+   * apart from a complete one -- a truncated list that looks exhaustive is how
+   * "top 20" gets read as "all files".
+   */
+  filesWithSurvivors: number;
+  /** True when `survivedByFile` dropped entries to stay under `limit`. */
+  truncated: boolean;
+  mutants: number;
+  killed: number;
+  survived: number;
+}
+
+/**
+ * Condense a Stryker report into survivor detail (#544).
+ *
+ * Returns `null` -- never a summary of zeros -- when the report is missing or
+ * carries no per-file section. A timed-out or failed run has no measurements,
+ * and writing `survived: 0` next to a real-looking score would report
+ * "measured: no survivors" for a run that measured nothing. That is the exact
+ * shape of false success this project keeps finding, so unknown stays `null`.
+ */
+export function summarizeSurvivors(
+  report: StrykerReportLike | null | undefined,
+  options: { limit?: number } = {},
+): SurvivorSummary | null {
+  if (!report || !report.files) return null;
+
+  const limit = options.limit ?? 20;
+  const survivors: Array<[string, number]> = [];
+  let mutants = 0;
+  let killed = 0;
+  let survived = 0;
+
+  for (const [file, entry] of Object.entries(report.files)) {
+    const fileSurvived = entry.nrOfSurvivedMutants ?? 0;
+    mutants += entry.nrOfMutants ?? 0;
+    killed += entry.nrOfKilledMutants ?? 0;
+    survived += fileSurvived;
+    if (fileSurvived > 0) survivors.push([file, fileSurvived]);
+  }
+
+  // Worst first, then by path so equal counts order deterministically.
+  survivors.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  const kept = survivors.slice(0, limit);
+
+  return {
+    survivedByFile: Object.fromEntries(kept),
+    filesWithSurvivors: survivors.length,
+    truncated: survivors.length > kept.length,
+    mutants,
+    killed,
+    survived,
+  };
+}
+
 export async function runGateM(options: GateMOptions): Promise<GateMResult> {
   const warnings: string[] = [];
   const errors: string[] = [];
@@ -539,7 +659,8 @@ export async function runGateM(options: GateMOptions): Promise<GateMResult> {
   logThresholdDetails(thresholds, baseline);
 
   const groups = groupByRunner(sourceFiles);
-  const fileScoresNullable = await runAllRunners(groups, options.timeoutMs, process.cwd());
+  const { scores: fileScoresNullable, counts: mutantCounts } =
+    await runAllRunners(groups, options.timeoutMs, process.cwd());
 
   const { fileScores, timeoutFiles } = partitionScores(fileScoresNullable);
   if (timeoutFiles.length > 0) {
@@ -557,12 +678,12 @@ export async function runGateM(options: GateMOptions): Promise<GateMResult> {
   }
 
   if (evalResult.blocked) {
-    return buildResult('block', evaluableThresholds.length, buildMutationScores(fileScores), warnings, errors);
+    return buildResult('block', evaluableThresholds.length, buildMutationScores(fileScores, mutantCounts), warnings, errors);
   }
   if (evaluableThresholds.length === 0) {
     return buildResult('skip', 0, {}, warnings, errors);
   }
-  return buildResult('pass', evaluableThresholds.length, buildMutationScores(fileScores), warnings, errors);
+  return buildResult('pass', evaluableThresholds.length, buildMutationScores(fileScores, mutantCounts), warnings, errors);
 }
 
 interface PartitionedScores {
@@ -595,6 +716,22 @@ async function collectTestIntentWarnings(sourceFiles: string[], warnings: string
   }
 }
 
+/**
+ * Read the mutation report the runner left on disk and summarise it (#544).
+ * Returns null when there is no readable report -- the caller then prints
+ * nothing, and the journal field stays absent. Every failure here is silent by
+ * design: #544 explicitly requires that missing detail must not turn Gate M
+ * itself into a failure.
+ */
+async function readSurvivorSummary(): Promise<SurvivorSummary | null> {
+  try {
+    const raw = await fs.readFile('.stryker-report.json', 'utf-8');
+    return summarizeSurvivors(JSON.parse(raw) as StrykerReportLike);
+  } catch {
+    return null;
+  }
+}
+
 export async function main(args: string[]): Promise<number> {
   const options = parseArgs(args);
 
@@ -611,19 +748,14 @@ export async function main(args: string[]): Promise<number> {
 
   const result = await runGateM(options);
 
-  if (result.warnings.length > 0) {
-    console.log('\nWarnings:');
-    for (const warning of result.warnings) {
-      console.log(`  ⚠ ${warning}`);
-    }
+  // #544: survivor detail on a machine-readable line. Printed only when a report
+  // exists -- absent means "not measured", never "measured: zero survivors".
+  const survivors = await readSurvivorSummary();
+  if (survivors) {
+    console.log(`GATE_M_SURVIVORS_JSON=${JSON.stringify(survivors)}`);
   }
 
-  if (result.errors.length > 0) {
-    console.log('\nErrors:');
-    for (const error of result.errors) {
-      console.error(`  ✗ ${error}`);
-    }
-  }
+  logDiagnostics(result.warnings, result.errors);
 
   const statusIcon = result.status === 'pass' ? '✓' :
     result.status === 'skip' ? '⊘' :
@@ -634,6 +766,18 @@ export async function main(args: string[]): Promise<number> {
   return result.exitCode;
 }
 
+/** Print Gate M's warnings and errors. Errors go to stderr. */
+function logDiagnostics(warnings: string[], errors: string[]): void {
+  if (warnings.length > 0) {
+    console.log('\nWarnings:');
+    for (const warning of warnings) console.log(`  ⚠ ${warning}`);
+  }
+  if (errors.length > 0) {
+    console.log('\nErrors:');
+    for (const error of errors) console.error(`  ✗ ${error}`);
+  }
+}
+
 const cliArgs = process.argv.slice(2);
 if (typeof require !== 'undefined' && require.main === module) {
   main(cliArgs)

package/mutation/types.ts

@@ -1,8 +1,14 @@
 export interface MutationScore {
   score: number;
-  mutants: number;
-  killed: number;
-  survived: number;
+  /**
+   * Mutant outcome counts. Optional on purpose (#544): a runner that did not
+   * report them must leave them absent, so a consumer can tell "not measured"
+   * from "measured zero". They used to be hardcoded to 0, which made every
+   * unmeasured file read as a clean one.
+   */
+  mutants?: number;
+  killed?: number;
+  survived?: number;
 }
 
 export interface MutationBaseline {

package/mutation/update-baseline.ts

@@ -3,9 +3,14 @@ import path from 'path';
 
 interface MutationScoreEntry {
   score: number;
-  mutants: number;
-  killed: number;
-  survived: number;
+  /**
+   * Optional (#544): a baseline entry built from a score alone has no mutant
+   * counts, and inventing zeros would record a clean file that was never
+   * measured.
+   */
+  mutants?: number;
+  killed?: number;
+  survived?: number;
 }
 
 interface MutationBaseline {
@@ -92,11 +97,13 @@ function updateBaseline(
           score: parseFloat(score.toFixed(1))
         };
       } else {
+        // #544: do not seed the baseline with zeros. This path only has a score
+        // from the hand-edited/CLI score list and no mutant counts at all, so
+        // writing mutants/killed/survived = 0 would record "measured, no
+        // survivors" for a file nobody measured. Absent means unknown, and the
+        // fields are optional on MutationScoreEntry for exactly this reason.
         updatedScores[filePath] = {
           score: parseFloat(score.toFixed(1)),
-          mutants: 0,
-          killed: 0,
-          survived: 0
         };
       }
     }
@@ -127,7 +134,17 @@ async function removeDeletedFiles(baseline: MutationBaseline): Promise<MutationB
 }
 
 async function saveBaseline(baseline: MutationBaseline, baselinePath: string): Promise<void> {
-  await fs.writeFile(baselinePath, JSON.stringify(baseline, null, 2));
+  // A failed write used to propagate as a bare rejection from deep inside the
+  // CLI's top-level await, producing an unhandled-rejection stack with no
+  // indication of WHICH file could not be written -- and on a permission or
+  // disk-full error the baseline silently stayed stale while the run looked
+  // complete. Report the path and the reason, then fail loudly.
+  try {
+    await fs.writeFile(baselinePath, JSON.stringify(baseline, null, 2));
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to write mutation baseline to ${baselinePath}: ${reason}`);
+  }
 }
 
 async function main(): Promise<void> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/xp-gate",
-  "version": "0.30.3",
+  "version": "0.30.5",
   "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.30.3",
+  "version": "0.30.5",
   "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-20
-**Commit:** 03f6d10a
+**Generated:** 2026-10-21
+**Commit:** 4e1f8be0
 **Branch:** main
-**Version:** 0.30.3.0
+**Version:** 0.30.5.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-20
-**Commit:** 03f6d10a
+**Generated:** 2026-10-21
+**Commit:** 4e1f8be0
 **Branch:** main
-**Version:** 0.30.3.0
+**Version:** 0.30.5.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-20
-**Commit:** 03f6d10a
+**Generated:** 2026-10-21
+**Commit:** 4e1f8be0
 **Branch:** main
-**Version:** 0.30.3.0
+**Version:** 0.30.5.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/dsh/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/dsh-plugin-xp-gate",
-  "version": "0.30.3",
+  "version": "0.30.5",
   "description": "XP-Gate deterministic quality gates + AI workflow skills as a DeepSeek Harness (DSH) native plugin: gate-check / gate-principles / gate-arch tools + 12 SKILL.md skills",
   "type": "module",
   "main": "./lib/index.js",

package/plugins/dsh/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-10-20
-**Commit:** 03f6d10a
+**Generated:** 2026-10-21
+**Commit:** 4e1f8be0
 **Branch:** main
-**Version:** 0.30.3.0
+**Version:** 0.30.5.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/dsh/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-20
-**Commit:** 03f6d10a
+**Generated:** 2026-10-21
+**Commit:** 4e1f8be0
 **Branch:** main
-**Version:** 0.30.3.0
+**Version:** 0.30.5.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/dsh/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-20
-**Commit:** 03f6d10a
+**Generated:** 2026-10-21
+**Commit:** 4e1f8be0
 **Branch:** main
-**Version:** 0.30.3.0
+**Version:** 0.30.5.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/opencode/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/opencode-plugin",
-  "version": "0.30.3",
+  "version": "0.30.5",
   "type": "module",
   "main": "index.ts",
   "description": "XP-Gate quality gates + AI workflow skills + Sprint Flow TUI sidebar for OpenCode",

package/plugins/opencode/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-10-20
-**Commit:** 03f6d10a
+**Generated:** 2026-10-21
+**Commit:** 4e1f8be0
 **Branch:** main
-**Version:** 0.30.3.0
+**Version:** 0.30.5.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/opencode/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-20
-**Commit:** 03f6d10a
+**Generated:** 2026-10-21
+**Commit:** 4e1f8be0
 **Branch:** main
-**Version:** 0.30.3.0
+**Version:** 0.30.5.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/opencode/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-20
-**Commit:** 03f6d10a
+**Generated:** 2026-10-21
+**Commit:** 4e1f8be0
 **Branch:** main
-**Version:** 0.30.3.0
+**Version:** 0.30.5.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/qoder/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.30.3",
+  "version": "0.30.5",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Qoder. 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/qoder/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-10-20
-**Commit:** 03f6d10a
+**Generated:** 2026-10-21
+**Commit:** 4e1f8be0
 **Branch:** main
-**Version:** 0.30.3.0
+**Version:** 0.30.5.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/qoder/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-20
-**Commit:** 03f6d10a
+**Generated:** 2026-10-21
+**Commit:** 4e1f8be0
 **Branch:** main
-**Version:** 0.30.3.0
+**Version:** 0.30.5.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/qoder/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-20
-**Commit:** 03f6d10a
+**Generated:** 2026-10-21
+**Commit:** 4e1f8be0
 **Branch:** main
-**Version:** 0.30.3.0
+**Version:** 0.30.5.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/principles/AGENTS.md

@@ -1,9 +1,9 @@
 # PRINCIPLES CHECKER MODULE
 
-**Generated:** 2026-10-20
-**Commit:** 03f6d10a
+**Generated:** 2026-10-21
+**Commit:** 4e1f8be0
 **Branch:** main
-**Version:** 0.30.3.0
+**Version:** 0.30.5.0
 
 ## OVERVIEW
 Clean Code & SOLID principles checker — **Gate 4** of pre-commit. 14 rules × 9 language adapters, SARIF 2.1.0 output. Houses the **Boy Scout Rule** enforcement engine (Gate 6) and warning-baseline storage.

package/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-10-20
-**Commit:** 03f6d10a
+**Generated:** 2026-10-21
+**Commit:** 4e1f8be0
 **Branch:** main
-**Version:** 0.30.3.0
+**Version:** 0.30.5.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/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-20
-**Commit:** 03f6d10a
+**Generated:** 2026-10-21
+**Commit:** 4e1f8be0
 **Branch:** main
-**Version:** 0.30.3.0
+**Version:** 0.30.5.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/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-20
-**Commit:** 03f6d10a
+**Generated:** 2026-10-21
+**Commit:** 4e1f8be0
 **Branch:** main
-**Version:** 0.30.3.0
+**Version:** 0.30.5.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.