fix: annotate failing TDD tests in GitHub diff

.github/scripts/annotate-tdd-violations.sh

@@ -0,0 +1,37 @@
+#!/bin/sh
+# Emit GitHub diff annotations for added it()/test() calls in a unified diff.
+#
+# Usage: annotate-tdd-violations.sh <patch-file>
+#
+# For each added it(), test(), it.skip(), etc. line found in the patch, emits
+# a ::error annotation pointing to the correct line in the new file. These
+# annotations appear in the GitHub PR "Files changed" tab.
+
+PATCH_FILE="${1:-/tmp/test.patch}"
+
+if [ ! -f "$PATCH_FILE" ]; then
+  echo "Patch file not found: $PATCH_FILE"
+  exit 0
+fi
+
+awk '
+  /^diff --git/ { file = "" }
+  /^\+\+\+ b\// { file = substr($0, 7); next }
+  /^@@/ {
+    match($0, /\+([0-9]+)/, m)
+    new_line = m[1] + 0 - 1
+    next
+  }
+  /^\+\+\+/ { next }
+  /^---/ { next }
+  /^\+/ {
+    new_line++
+    line = substr($0, 2)
+    if (file != "" && (line ~ /^[[:space:]]*(it|test)[[:space:]]*\(/ || line ~ /^[[:space:]]*(it|test)\.(skip|only|todo)[[:space:]]*\(/)) {
+      print "::error file=" file ",line=" new_line "::TDD: This test passes on the base branch. New tests must fail on base to confirm they cover new behavior."
+    }
+    next
+  }
+  /^-/ { next }
+  { new_line++ }
+' "$PATCH_FILE"

.github/workflows/tdd.yml

@@ -270,6 +270,10 @@ jobs:
       - name: Fetch PR head
         run: git fetch origin ${{ github.event.pull_request.head.sha }}
 
+      - name: Restore GitHub scripts from PR HEAD
+        if: github.event_name == 'pull_request'
+        run: git checkout FETCH_HEAD -- .github/scripts/
+
       - name: Generate and apply test diff
         id: patch
         run: |
@@ -356,6 +360,11 @@ jobs:
             echo ""
             echo "❌ TDD concern: changed tests PASS on the base branch."
             echo "This may indicate the tests do not cover new functionality introduced by this PR."
+
+            # Emit GitHub diff annotations for each added it()/test() call so the
+            # TDD violation is highlighted directly in the PR file changes view.
+            sh .github/scripts/annotate-tdd-violations.sh /tmp/test.patch
+
             exit 1
           fi
 
@@ -387,7 +396,7 @@ jobs:
 
       - name: Restore GitHub Actions files from PR HEAD
         if: github.event_name == 'pull_request'
-        run: git checkout FETCH_HEAD -- .github/actions/
+        run: git checkout FETCH_HEAD -- .github/actions/ .github/scripts/
 
       - name: Generate and apply test diff
         id: patch
@@ -481,6 +490,11 @@ jobs:
             echo ""
             echo "❌ TDD concern: changed puppeteer tests PASS on the base branch."
             echo "This may indicate the tests do not cover new functionality introduced by this PR."
+
+            # Emit GitHub diff annotations for each added it()/test() call so the
+            # TDD violation is highlighted directly in the PR file changes view.
+            sh .github/scripts/annotate-tdd-violations.sh /tmp/test.patch
+
             exit 1
           fi