@blamejs/exceptd-skills 0.13.1 → 0.13.3

package/orchestrator/index.js

@@ -379,11 +379,18 @@ async function runReport(format) {
     // (GENERIC_FAILURE) not 2 (DETECTED_ESCALATE). Pre-v0.13 the
     // body went to stderr and exit was 2; both broke CI consumers
     // that expected the dispatch-error vs verb-finding distinction.
+    // v0.13.2: did-you-mean on the unknown format value (reuses
+    // lib/flag-suggest.js for Levenshtein-≤2 typo correction).
+    const { suggestFlag } = require('../lib/flag-suggest');
+    const dym = suggestFlag(String(format), VALID_REPORT_FORMATS);
+    const hint = dym ? ` Did you mean "${dym}"?` : '';
     process.stdout.write(JSON.stringify({
       ok: false,
       verb: 'report',
-      error: `report: format "${format}" not in accepted set ${JSON.stringify(VALID_REPORT_FORMATS)}.`,
+      error: `report: format "${format}" not in accepted set ${JSON.stringify(VALID_REPORT_FORMATS)}.${hint}`,
+      provided: format,
       accepted_formats: VALID_REPORT_FORMATS,
+      did_you_mean: dym ? [dym] : [],
     }) + '\n');
     safeExit(EXIT_CODES.GENERIC_FAILURE);
     return;
@@ -1086,6 +1093,7 @@ function runWatchlist(rawArgs = []) {
 
   const byskill = rawArgs.includes('--by-skill');
   const alertsMode = rawArgs.includes('--alerts');
+  const orgScanMode = rawArgs.includes('--org-scan');
   const manifestPath = path.join(__dirname, '..', 'manifest.json');
   const repoRoot = path.join(__dirname, '..');
 
@@ -1093,12 +1101,22 @@ function runWatchlist(rawArgs = []) {
   // "CVE-class alert patterns" — surfaces catalog entries matching
   // high-priority shape rules (kernel-LPE-with-PoC, supply-chain-family,
   // AI-discovered-KEV, recently-disclosed-with-active-exploitation).
-  // The two modes are mutually exclusive; --alerts short-circuits the
-  // forward-watch aggregation.
+  // The modes are mutually exclusive; the first matching flag wins.
   if (alertsMode) {
     return runWatchlistAlerts(rawArgs);
   }
 
+  // v0.13.3: --org-scan probes GitHub for repository naming patterns
+  // associated with known threat actors (per NEW-CTRL-052 from the
+  // MAL-2026-SHAI-HULUD-OSS zeroday-lessons entry). The Shai-Hulud
+  // worm uses GitHub itself as the exfil channel — repos named
+  // "A Gift From TeamPCP", "Shai-Hulud-*", or with future variants
+  // hold the stolen credentials. Operators can run this against
+  // their own GitHub org to surface exfil staging in their tenant.
+  if (orgScanMode) {
+    return runWatchlistOrgScan(rawArgs);
+  }
+
   let manifest;
   try {
     manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
@@ -1582,6 +1600,140 @@ Examples:
 `);
 }
 
+/**
+ * v0.13.3 — runWatchlistOrgScan: GitHub repo-pattern monitoring per
+ * NEW-CTRL-052 (MAL-2026-SHAI-HULUD-OSS zeroday-lessons). The Shai-Hulud
+ * worm uses GitHub itself as the exfil channel; the canonical naming
+ * pattern is "A Gift From TeamPCP", commit-timestamps falsified to
+ * 2099-01-01, and contributor accounts agwagwagwa / headdirt / tmechen.
+ *
+ * Operators run this against their GitHub org (--org <login> or
+ * GITHUB_ORG env var) to surface exfil staging within their tenant.
+ * Uses the GitHub Search API (unauthenticated for public-repo search;
+ * GITHUB_TOKEN env var lifts the rate limit + enables private-repo
+ * coverage). Report-only — never modifies repos.
+ *
+ * Flags / env:
+ *   --org <login>              GitHub org / user to scope the search to (required)
+ *   --pattern <s> (repeatable) additional naming-pattern strings (defaults below)
+ *   --json                     structured JSON output
+ *   GITHUB_TOKEN env var       lifts rate limit + private-repo search coverage
+ */
+async function runWatchlistOrgScan(rawArgs = []) {
+  const jsonOut = rawArgs.includes('--json');
+  // Extract --org <login>. Accept --org=foo too.
+  let org = null;
+  for (let i = 0; i < rawArgs.length; i++) {
+    if (rawArgs[i] === '--org' && rawArgs[i + 1]) { org = rawArgs[i + 1]; break; }
+    if (rawArgs[i].startsWith('--org=')) { org = rawArgs[i].slice('--org='.length); break; }
+  }
+  if (!org) org = process.env.GITHUB_ORG || null;
+  if (!org) {
+    process.stdout.write(JSON.stringify({
+      ok: false,
+      verb: 'watchlist',
+      mode: 'org-scan',
+      error: 'watchlist --org-scan requires --org <login> (or GITHUB_ORG env var). Example: exceptd watchlist --org-scan --org blamejs',
+    }) + '\n');
+    safeExit(EXIT_CODES.GENERIC_FAILURE);
+    return;
+  }
+  // Custom patterns via --pattern <s> (repeatable). Default set from
+  // the MAL-2026-SHAI-HULUD-OSS catalog entry + NEW-CTRL-052 evidence.
+  const customPatterns = [];
+  for (let i = 0; i < rawArgs.length; i++) {
+    if (rawArgs[i] === '--pattern' && rawArgs[i + 1]) customPatterns.push(rawArgs[i + 1]);
+    if (rawArgs[i].startsWith('--pattern=')) customPatterns.push(rawArgs[i].slice('--pattern='.length));
+  }
+  const DEFAULT_PATTERNS = [
+    { id: 'shai-hulud-classic', q: 'Shai-Hulud', severity: 'critical', source: 'MAL-2026-SHAI-HULUD-OSS (pre-source-release naming)' },
+    { id: 'teampcp-gift', q: 'A Gift From TeamPCP', severity: 'critical', source: 'MAL-2026-SHAI-HULUD-OSS (post-2026-05-12 release naming)' },
+    { id: 'teampcp-bare', q: 'TeamPCP', severity: 'high', source: 'MAL-2026-SHAI-HULUD-OSS threat actor reference' },
+  ];
+  const patterns = [
+    ...DEFAULT_PATTERNS,
+    ...customPatterns.map((q, i) => ({ id: `custom-${i + 1}`, q, severity: 'medium', source: 'operator --pattern' })),
+  ];
+
+  // GitHub Search API: GET /search/code?q=<query>+org:<login>
+  // and GET /search/repositories?q=<query>+org:<login>. Both return
+  // the same shape (items[] with name, html_url, owner, created_at).
+  const token = process.env.GITHUB_TOKEN || '';
+  const matches = [];
+  let rateLimited = false;
+  let unauth = !token;
+  if (typeof fetch !== 'function') {
+    process.stdout.write(JSON.stringify({
+      ok: false,
+      verb: 'watchlist',
+      mode: 'org-scan',
+      error: 'fetch() not available — Node 18+ required.',
+    }) + '\n');
+    safeExit(EXIT_CODES.GENERIC_FAILURE);
+    return;
+  }
+  for (const p of patterns) {
+    const url = `https://api.github.com/search/repositories?q=${encodeURIComponent(p.q + ' org:' + org)}&per_page=100`;
+    const headers = { 'User-Agent': 'exceptd-watchlist-org-scan/0.13.3 (+https://exceptd.com)', 'Accept': 'application/vnd.github+json' };
+    if (token) headers.Authorization = `Bearer ${token}`;
+    try {
+      const ac = new AbortController();
+      const timer = setTimeout(() => ac.abort(), 10000);
+      const r = await fetch(url, { headers, signal: ac.signal });
+      clearTimeout(timer);
+      if (r.status === 403 || r.status === 429) {
+        rateLimited = true;
+        continue;
+      }
+      if (!r.ok) continue;
+      const body = await r.json();
+      for (const item of body.items || []) {
+        matches.push({
+          pattern_id: p.id,
+          severity: p.severity,
+          source: p.source,
+          repo: item.full_name,
+          url: item.html_url,
+          private: item.private,
+          created_at: item.created_at,
+          updated_at: item.updated_at,
+          stars: item.stargazers_count || 0,
+        });
+      }
+    } catch { /* network failure — best effort */ }
+  }
+  const generated_at = new Date().toISOString();
+  if (jsonOut) {
+    process.stdout.write(JSON.stringify({
+      ok: !rateLimited,
+      verb: 'watchlist',
+      mode: 'org-scan',
+      generated_at,
+      org,
+      patterns_evaluated: patterns.length,
+      match_count: matches.length,
+      matches,
+      rate_limited: rateLimited,
+      unauthenticated: unauth,
+      control_reference: 'NEW-CTRL-052 (MAL-2026-SHAI-HULUD-OSS lesson)',
+    }) + '\n');
+    return;
+  }
+  console.log(`\nGitHub Org-Scan — ${generated_at}`);
+  console.log(`Org: ${org}  patterns: ${patterns.length}  matches: ${matches.length}`);
+  if (unauth) console.log('(unauthenticated — set GITHUB_TOKEN for private-repo coverage + higher rate limit)');
+  if (rateLimited) console.log('WARNING: GitHub rate limit hit on at least one query. Re-run with GITHUB_TOKEN set.');
+  if (matches.length === 0) {
+    console.log('No threat-actor-pattern repos found.');
+    return;
+  }
+  for (const m of matches) {
+    console.log(`[${m.severity}] ${m.repo}  ${m.private ? '(private)' : ''} created ${m.created_at}`);
+    console.log(`    pattern: ${m.pattern_id} (${m.source})`);
+    console.log(`    ${m.url}`);
+  }
+}
+
 // Only run the CLI when this file is executed directly. Earlier versions
 // invoked main() at import time too, which meant `require('./orchestrator')`
 // would trigger a full CLI dispatch (and printHelp) inside the importing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/exceptd-skills",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "description": "AI security skills grounded in mid-2026 threat reality, not stale framework documentation. 42 skills, 10 catalogs, 34 jurisdictions, pre-computed indexes, Ed25519-signed.",
   "keywords": [
     "ai-security",

package/sbom.cdx.json

@@ -1,22 +1,22 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.6",
-  "serialNumber": "urn:uuid:c9932465-eaaf-45d0-850b-1ac483acd405",
+  "serialNumber": "urn:uuid:215c1846-8948-4275-8e79-ad2f8593225c",
   "version": 1,
   "metadata": {
-    "timestamp": "2133-03-02T22:32:05.000Z",
+    "timestamp": "2043-09-26T19:40:54.000Z",
     "tools": [
       {
         "vendor": "blamejs",
         "name": "scripts/refresh-sbom.js",
-        "version": "0.13.1"
+        "version": "0.13.3"
       }
     ],
     "component": {
-      "bom-ref": "pkg:npm/@blamejs/exceptd-skills@0.13.1",
+      "bom-ref": "pkg:npm/@blamejs/exceptd-skills@0.13.3",
       "type": "application",
       "name": "@blamejs/exceptd-skills",
-      "version": "0.13.1",
+      "version": "0.13.3",
       "description": "AI security skills grounded in mid-2026 threat reality, not stale framework documentation. 42 skills, 10 catalogs, 34 jurisdictions, pre-computed indexes, Ed25519-signed.",
       "licenses": [
         {
@@ -25,17 +25,17 @@
           }
         }
       ],
-      "purl": "pkg:npm/%40blamejs/exceptd-skills@0.13.1",
+      "purl": "pkg:npm/%40blamejs/exceptd-skills@0.13.3",
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "4b9469db507f7f20a000a34c40f90adbbc98c328f2fc7ddee22843732a024c09"
+          "content": "5f31c2d0207da9b36fe526a2913e975e27ae2442561e03b079695af7f5a8926b"
         }
       ],
       "externalReferences": [
         {
           "type": "distribution",
-          "url": "https://www.npmjs.com/package/@blamejs/exceptd-skills/v/0.13.1"
+          "url": "https://www.npmjs.com/package/@blamejs/exceptd-skills/v/0.13.3"
         },
         {
           "type": "vcs",
@@ -108,7 +108,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "27fbbfa0da04040c626789c887d0ea570d865bcb9e99ea6ef3fd670c73a39b5b"
+          "content": "1932f52ef4f3d1ba7963310436df82f5ef6269a3c77851e993e31885ebade1b2"
         }
       ]
     },
@@ -229,7 +229,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "e4eda996f3de0a8ffc727717065165b66c690452a576b0605036db2d5caef429"
+          "content": "b3540a3296e5e901004d428351d40d3ac40b154da082071da2c00222c40b7b6e"
         }
       ]
     },
@@ -240,7 +240,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "0ec427652a9e613f04675beb26dc4c08934ba291e47427972b2a008c151cca78"
+          "content": "2b021f47355365d1ba59078dfa582397c7a64c2b4ebea4657ea260a66b76daf6"
         }
       ]
     },
@@ -251,7 +251,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "0ca33f8b0cf55a43de1290e310096020c4e0d16305bd01bcbe6cb46e0278caa8"
+          "content": "76461dbec048c5e072435d57e3a04b780e3992dab9f316b1b52608e0a997e355"
         }
       ]
     },
@@ -262,7 +262,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7fae34cf0abbd09abbbbd6a61ea06e487ddbd57060d3af6a58528c684156cf60"
+          "content": "b499cb431c1b71aab505db577a1e3b2fdcb5190afbcc6aaee0f6a237cfc16ca8"
         }
       ]
     },
@@ -273,7 +273,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "832d096bd52081fe43c082fd6958f9054d6b6e136df5b3d4cef7efd0ea49a843"
+          "content": "4a0036f9ec17af29e0df111ac77b94f8be6a52742bfd89ff3583096d23b75e35"
         }
       ]
     },
@@ -317,7 +317,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "5e2baf1e435c5b61b183e3f603636eae4fab34ee800488919c679665882c4f62"
+          "content": "ce1535f13d29ab90fac99b983f38a23dd685702b3f12ac9f2371294cb9859ecf"
         }
       ]
     },
@@ -570,7 +570,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "40d666d0932da24b425b01ced0f9c9e5f2e6cfd2082f53861d982919dde56a4a"
+          "content": "1438620d2c8b0606eac4f63e620906b9ba079c57bfa7f737ceb6a50370cdc9a5"
         }
       ]
     },
@@ -691,7 +691,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "17c6fda9bffce0c0bcf782fca3961e6a77b1caba9054ce12121adb541028bc53"
+          "content": "48aa70089fe9fc3bee80e19042d28d91ceb996ed018b6131db970dba7cadb90e"
         }
       ]
     },
@@ -812,7 +812,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "678cce9841ee92128e777cc0f355e020bd69c37cbd637be91479858e6a4958fd"
+          "content": "63702da0ef17b9dd32cff349473d5e1c32aae763cd769936a07570e34cb6b824"
         }
       ]
     },
@@ -988,7 +988,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "4535de4e48530ccb3c5d97402ae9dcf45f0336b838bddb8ab081c6df9632014a"
+          "content": "fbc30b15d294d3bdfccfb3880781dae9e9a9624e3b6d6a64723cdc75b6b47d3b"
         }
       ]
     },
@@ -1032,7 +1032,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7c7378f69024b1abb11d2f17978f9023b262ac6a67a82c2eb31d4996c2caee28"
+          "content": "b827fb5d2a43409ba2c390b000e175c9357b86137d25d6647ff238b94922275b"
         }
       ]
     },
@@ -1289,6 +1289,17 @@
         }
       ]
     },
+    {
+      "bom-ref": "file:scripts/check-test-count.js",
+      "type": "file",
+      "name": "scripts/check-test-count.js",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "e8c7473d7a1f87d27aeab39cefa54c10c773831c3c3b0a786c81f9ac9a50d6e3"
+        }
+      ]
+    },
     {
       "bom-ref": "file:scripts/check-test-coverage.README.md",
       "type": "file",
@@ -1329,7 +1340,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "83c795a05c0a1abcbb358eb47de22f04dfc3ecec602b35fbb686093dbe27c182"
+          "content": "6a7766b986988fd14105d92f3488052333afff8b72eda17460e193ca58b2d60a"
         }
       ]
     },
@@ -1406,7 +1417,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "66e7773d29c179ab62f409007c05e05993e04a19273225a1e520f2481fd9a90d"
+          "content": "51295c849bcced965b6448eb6b4bbd5caef5ba0b0cea7ce48abbacf47d331621"
         }
       ]
     },
@@ -1439,7 +1450,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "67e62791f60231f2ff53408922fa7137a9060de72097769c630f838a1c227c45"
+          "content": "2b611eb8fa4841fdfc3f1dd1ffd504a46c6ecdc654213a955efbabefb6b1db87"
         }
       ]
     },
@@ -1450,7 +1461,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "2bdfa3dbe534efa3df245e0da37998ad7ab2da4a3171d5000d3346513c10bceb"
+          "content": "9fc2252cbcf6162591e70d0bf5499a430b0584495ad584ce49fb7daf070d335f"
         }
       ]
     },
@@ -1472,7 +1483,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "6494ee3856edeb212e65fe5cdb208357c1a832eb8ac374b26055586bfc71f629"
+          "content": "5ec3800a0049b2123aff67bfab4ff28491a86d2daeb712283e5e88b10c3d5d7b"
         }
       ]
     },
@@ -1527,7 +1538,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "e62c71ba3be2b4d0f7dfa529fec007cba6bee3013f76b93756e3e6310f2d22ab"
+          "content": "3d0c7ca85f32ee1fe74598889361ef2be16d099fe6e9e8d8c8184b7004306b30"
         }
       ]
     },
@@ -1549,7 +1560,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "e4e9e5a820c0ed3fde9483282e7a0ecaf79284cd2e9923ce66f2b0fb1fc44626"
+          "content": "250f266908f51f99a4cb3aec0d5dacfcf91fac9f3d95e5a117429a40ed2ff45a"
         }
       ]
     },
@@ -1582,7 +1593,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "51acb746cd63366ca62567588c700a9eb3f37c43250bd9ae4e1477ccb71c5b6d"
+          "content": "fb8c261def9e3344b44fd219c209027029e1eddf0e6bee1ecffb2d2176e1585e"
         }
       ]
     },
@@ -1659,7 +1670,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "ca3fd922b43fc57aeb5e65c2d5a2823e6bc438167d6afa3a767cee83e4af1f96"
+          "content": "72429f05010accbcb191cb1544f1b88493c2f5249362846e5713ec3226b83dc2"
         }
       ]
     },
@@ -1670,7 +1681,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "9ece7b1fb7f24e37dbdd8618b94b2a4434e182e3426e15f17e26464c0a1fdfd1"
+          "content": "7423cca19aab1026c07de63279137441018345731d3ee895c474316d432adaa2"
         }
       ]
     },
@@ -1725,7 +1736,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "b47daaa26fdac07aa23e7becaa18487c5302e65c654f99fecab3689f23ec1bd2"
+          "content": "fd441131484dc5af4cd785ded0bac039123e6205483543752cb16fa508460c00"
         }
       ]
     },
@@ -1736,7 +1747,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "643fd951359c2602d9b029a244fe66c1e23f726e711141a06c09cc760a479534"
+          "content": "91f00e7a9be2608393ec8cb6d5f0c9828f81b954a12a7c9fd04bd642b9091e09"
         }
       ]
     },
@@ -1747,7 +1758,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "c63cf1c7c98e920f968cfe60f14e718ea71b120c1b01616af22f64a796963bbe"
+          "content": "a73c3f36f23c12750d369931b7e3f884edae4a8aef35fc8690d15ef4500c4dd0"
         }
       ]
     },
@@ -1780,7 +1791,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "862f9482af88e5409e011a6981a5d719863deeb646e41cd4df63e5d6597c50b1"
+          "content": "59193e39c2fd73fdd7fede38a956bc730bbe4b712d7d6020788bb4d85f001ad8"
         }
       ]
     },
@@ -1802,7 +1813,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "cf2b996cb18a5146614c06e3a50f4734a07d02b5be36bbdf492583f9cdcfed4d"
+          "content": "b6f3bee321833dc18f5624a9be4d28673d22e22018254b0bd1f3690b945073af"
         }
       ]
     },
@@ -1824,7 +1835,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "ecc6441cb47ef2bc24547e47be018098228c956a41d61ddb50de7e7b37114a37"
+          "content": "cf1cc27ae5ae68d336c56d9f3afd950641e1d8d5b9f90b64c2daf00abe92bab0"
         }
       ]
     },
@@ -1835,7 +1846,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "ac623f61585de66c9ef5ed63e9c6059faef77e525abc672ac6d435c616a7268f"
+          "content": "cebeba3940320ebc5b44ad2bb7b4cdcda412257c1a6319a1b7379c875ebe8d6a"
         }
       ]
     },
@@ -1846,7 +1857,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "fdb07324b69a3a724e3eaba17bf687d72d4bd9d5c4f440be816bc9b08b8aef04"
+          "content": "f2063eaea3f5ddf0f3d37b41985bf522b682a41f104796b3f0dff611cefd043c"
         }
       ]
     },
@@ -1857,7 +1868,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "59a0d7cd85b923b3f5633bdc15c1a88eef7dea6332480d93b0bb0ae93a4cd0fe"
+          "content": "e26f194880cd6acf46abe31e9348d445e9222c7691e9b9b953662c4a472462f5"
         }
       ]
     },

package/scripts/check-test-count.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * scripts/check-test-count.js — v0.13.2 canonical-test-count predeploy gate.
+ *
+ * Why this exists. The v0.12 audit flagged that nothing in the suite asserts
+ * "we expect N tests today." A test file accidentally deleted, a skip-all
+ * mistakenly committed, or a misnamed file glob-excluded would all silently
+ * drop tests without anyone noticing. The lint + diff-coverage gates catch
+ * source changes; this gate catches test-set shrinkage.
+ *
+ * Mechanism: count `test(`, `test.only(`, and `test.skip(` declarations
+ * across `tests/*.test.js` via static analysis (faster than running). Compare
+ * to a baseline pinned in `tests/.test-count-baseline.json`. Fail if the
+ * observed count drops MORE than the configured tolerance (default 1) below
+ * the baseline. Growth above baseline is fine; if the count grows by more
+ * than `update_baseline_when_growth_exceeds`, surface a notice that the
+ * baseline file should be refreshed (operator commits the refresh as part
+ * of the release that added the tests).
+ *
+ * Output:
+ *   stdout: structured JSON when --json, else a one-line summary
+ *   exit 0: observed count is at or above baseline minus tolerance
+ *   exit 1: observed count dropped beyond tolerance — fail predeploy
+ *   exit 2: baseline file missing or malformed
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+const TESTS_DIR = path.join(ROOT, 'tests');
+const BASELINE_PATH = path.join(TESTS_DIR, '.test-count-baseline.json');
+
+function listTestFiles(dir) {
+  const out = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (e.name === '_helpers' || e.name === 'fixtures' || e.name === 'e2e-scenarios') continue;
+      out.push(...listTestFiles(p));
+    } else if (e.isFile() && e.name.endsWith('.test.js')) {
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+function countTests(filePath) {
+  const text = fs.readFileSync(filePath, 'utf8');
+  const lines = text.split('\n');
+  let count = 0;
+  for (const line of lines) {
+    const stripped = line.replace(/^\s*\/\/.*$/, '').trim();
+    if (!stripped) continue;
+    if (/(?<![A-Za-z0-9_$.])test(?:\.only|\.skip)?\s*\(/.test(stripped)) count++;
+  }
+  return count;
+}
+
+function main() {
+  const wantJson = process.argv.includes('--json');
+  const wantUpdate = process.argv.includes('--update-baseline');
+
+  if (!fs.existsSync(BASELINE_PATH)) {
+    if (wantUpdate) {
+      const files = listTestFiles(TESTS_DIR);
+      const observed = files.reduce((n, f) => n + countTests(f), 0);
+      fs.writeFileSync(BASELINE_PATH, JSON.stringify({
+        baseline: observed,
+        tolerance: 1,
+        update_baseline_when_growth_exceeds: 20,
+        notes: 'Operator-pinned canonical test count. Bump when new test files land in a release. See scripts/check-test-count.js for the contract.',
+        recorded_at: new Date().toISOString().slice(0, 10),
+      }, null, 2) + '\n', 'utf8');
+      console.error(`[check-test-count] wrote initial baseline: ${observed}`);
+      process.exit(0);
+    }
+    console.error(`[check-test-count] baseline missing at ${path.relative(ROOT, BASELINE_PATH)}. Run with --update-baseline to create it.`);
+    process.exit(2);
+  }
+
+  let baselineFile;
+  try { baselineFile = JSON.parse(fs.readFileSync(BASELINE_PATH, 'utf8')); }
+  catch (e) {
+    console.error(`[check-test-count] cannot parse baseline: ${e.message}`);
+    process.exit(2);
+  }
+  const baseline = baselineFile.baseline;
+  const tolerance = baselineFile.tolerance || 1;
+  const updateThreshold = baselineFile.update_baseline_when_growth_exceeds || 20;
+  if (typeof baseline !== 'number' || baseline <= 0) {
+    console.error(`[check-test-count] baseline value invalid: ${baseline}`);
+    process.exit(2);
+  }
+
+  const files = listTestFiles(TESTS_DIR);
+  const observed = files.reduce((n, f) => n + countTests(f), 0);
+
+  if (wantUpdate) {
+    fs.writeFileSync(BASELINE_PATH, JSON.stringify({
+      ...baselineFile,
+      baseline: observed,
+      recorded_at: new Date().toISOString().slice(0, 10),
+    }, null, 2) + '\n', 'utf8');
+    console.error(`[check-test-count] baseline updated: ${baseline} -> ${observed}`);
+    process.exit(0);
+  }
+
+  const delta = observed - baseline;
+  const status = delta < -tolerance
+    ? 'shrunk_beyond_tolerance'
+    : delta > updateThreshold
+      ? 'grew_beyond_threshold_consider_bump'
+      : 'ok';
+
+  if (wantJson) {
+    process.stdout.write(JSON.stringify({
+      ok: status === 'ok' || status === 'grew_beyond_threshold_consider_bump',
+      verb: 'check-test-count',
+      observed,
+      baseline,
+      tolerance,
+      delta,
+      status,
+      files_scanned: files.length,
+    }) + '\n');
+  } else {
+    console.log(`[check-test-count] observed=${observed} baseline=${baseline} delta=${delta >= 0 ? '+' : ''}${delta} tolerance=${tolerance} files=${files.length} status=${status}`);
+  }
+
+  if (status === 'shrunk_beyond_tolerance') {
+    console.error(`[check-test-count] FAIL - test count dropped from ${baseline} to ${observed} (delta ${delta}, tolerance -${tolerance}).`);
+    console.error('[check-test-count] Either a test file was accidentally removed, a test() invocation was deleted, OR the baseline is stale.');
+    console.error('[check-test-count] If the drop is intentional, run: node scripts/check-test-count.js --update-baseline');
+    process.exit(1);
+  }
+  if (status === 'grew_beyond_threshold_consider_bump') {
+    console.error(`[check-test-count] NOTICE - test count grew by ${delta} (above the ${updateThreshold} notice threshold). Consider refreshing the baseline: node scripts/check-test-count.js --update-baseline`);
+  }
+  process.exit(0);
+}
+
+main();