@cometchat/skills 4.4.2 → 5.0.0

package/test-suite/scripts/verify-catalog.mjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+/**
+ * verify-catalog.mjs — Tier-1 existence oracle (dependency-free, no network).
+ *
+ * The anti-hallucination gate (RULES.md §8): every `CometChat*` symbol the skills
+ * put in a CODE FENCE must exist in the family catalog (the public export surface
+ * of the pinned kit). A symbol that isn't in the catalog is a phantom — it will
+ * fail compile in the user's project. This tier catches it for ~0 cost, offline.
+ *
+ * FAMILY-DRIVEN (multi-family pack): UIKIT_FAMILIES + SDK_SKILLS below are the only
+ * places a new family is added.
+ *
+ * What it checks (per UI-Kit family):
+ *   • HARD (exit 1): every `CometChat*` token inside a code fence in the family's
+ *     skill markdown exists in that family's catalog.
+ *   • SOFT (warn):   `CometChat*` tokens that appear only in prose (not in a fence)
+ *     and aren't in the catalog. Known-intentional mentions (migration removed-symbols,
+ *     phantom "never emit" warnings, non-kit names) are allowlisted per family
+ *     (EXPECTED_PROSE, AUDIT-032); only UNEXPECTED prose-only tokens are surfaced.
+ *   • DRIFT guard:   each shipped catalog (test-suite/catalogs/<key>.json) must match
+ *     the reviewer's G0 oracle (.claude/.../tools/catalog/<key>.json) symbol for
+ *     symbol — two copies that diverge is the AUDIT-008/012 failure mode.
+ *     WARN by default; --strict-drift makes it exit 1 (use in CI).
+ *
+ * Usage: node test-suite/scripts/verify-catalog.mjs [--json] [--strict-drift]
+ * Exit:  0 clean · 1 phantom(s) or strict-drift · 2 bad invocation.
+ */
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const SKILLS_DIR = join(ROOT, "skills");
+const JSON_OUT = process.argv.includes("--json");
+const STRICT_DRIFT = process.argv.includes("--strict-drift");
+
+const SYMBOL_RE = /\bCometChat[A-Za-z0-9_]*/g;
+// One fence regex across families — a web skill has no kotlin fences and vice versa,
+// so the union is harmless and keeps the scan single-pass.
+const FENCE_RE = /```(?:tsx?|jsx?|typescript|javascript|kotlin|java|groovy|xml)[^\n]*\n([\s\S]*?)```/g;
+
+// ── Derive family tables from families.json (RULES.md §22) ───────────────────
+// The reviewer oracle is DEV-ONLY and NOT in the npm tarball (package.json "files").
+// Running `cometchat verify catalog` from an installed pack must skip cleanly, not ENOENT.
+const _FAM_PATH = join(ROOT, ".claude/skills/cometchat-skill-reviewer/tools/families.json");
+if (!existsSync(_FAM_PATH)) {
+  console.log("catalog: reviewer oracle (families.json) not present — dev-only gate, skipping (installed pack).");
+  process.exit(0);
+}
+const { families: FAM_DATA } = JSON.parse(readFileSync(_FAM_PATH, "utf8"));
+
+// UI-Kit families: skill-name glob → {catalog key, extra catalogs to union in}.
+// Derived from families.json: non-parked, non-template, non-headless families.
+// Android Kotlin fences mix UI-kit + SDK symbols (SDK is a transitive dep of the kit),
+// so their existence oracle is the UNION of the kit catalog + the SDK catalog;
+// extraCatalogs in families.json carries those extra paths.
+const UIKIT_FAMILIES = Object.fromEntries(
+  Object.values(FAM_DATA)
+    .filter((f) => !f.parked && !/^template/i.test(f._status || "") && f.surface !== "headless" && f.surface !== "static")
+    .map((f) => {
+      const catBase = (f.catalog || "").replace(/^catalog\//, "").replace(/\.json$/, "");
+      if (!catBase) return null;
+      const prefix = (f.reviewsSkills || []).find((p) => p.endsWith("-"));
+      if (!prefix) return null;
+      const alsoCatalogs = (f.extraCatalogs || []).map((p) => p.replace(/^catalog\//, "").replace(/\.json$/, ""));
+      return [catBase, { glob: new RegExp("^" + prefix), alsoCatalogs }];
+    })
+    .filter(Boolean)
+);
+
+// SDK families (NAMESPACE shape): skill dir → catalog key.
+// Derived from families.json sdkSkill/sdkCatalog fields.
+const SDK_SKILLS = Object.fromEntries(
+  Object.values(FAM_DATA)
+    .filter((f) => f.sdkSkill && f.sdkCatalog)
+    // extraCatalogs unioned in too (like UIKIT_FAMILIES): an SDK skill legitimately
+    // names cross-package/native symbols (chat SDK under the calls SDK, a native
+    // service class) — real, not phantoms. Data-driven, not special-cased.
+    .map((f) => [f.sdkSkill, {
+      cat: f.sdkCatalog,
+      extra: (f.extraCatalogs || []).map((p) => p.replace(/^catalog\//, "").replace(/\.json$/, "")),
+    }])
+);
+
+// AUDIT-032: known-intentional prose mentions, per family, stored in families.json
+// as `expectedProseAllowlist` arrays. Fence usage is still HARD-blocked; this governs
+// only the SOFT prose warning.
+const EXPECTED_PROSE = Object.fromEntries(
+  Object.values(FAM_DATA)
+    .filter((f) => f.catalog && Array.isArray(f.expectedProseAllowlist))
+    .map((f) => [
+      (f.catalog || "").replace(/^catalog\//, "").replace(/\.json$/, ""),
+      new Set(f.expectedProseAllowlist),
+    ])
+);
+function loadSymbols(p) {
+  if (!existsSync(p)) return null;
+  const j = JSON.parse(readFileSync(p, "utf8"));
+  return new Set(j.symbols || []);
+}
+
+function walkMd(dir, out = []) {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) walkMd(p, out);
+    else if (e.name.endsWith(".md")) out.push(p);
+  }
+  return out;
+}
+
+function tokensIn(text) {
+  return new Set((text.match(SYMBOL_RE) || []).filter((t) => t !== "CometChat"));
+}
+
+function main() {
+  const out = { ok: true, families: {}, sdk: {}, drift: {} };
+  let hardFail = false;
+
+  // ── UI-Kit families: fence phantoms + prose warnings ──────────────────────
+  for (const [family, cfg] of Object.entries(UIKIT_FAMILIES)) {
+    const catalog = loadSymbols(join(ROOT, "test-suite", "catalogs", `${family}.json`));
+    if (!catalog) { console.error(`missing catalog: test-suite/catalogs/${family}.json (run npm run catalog:refresh)`); process.exit(2); }
+    for (const extra of cfg.alsoCatalogs || []) {
+      const s = loadSymbols(join(ROOT, "test-suite", "catalogs", `${extra}.json`));
+      if (s) for (const sym of s) catalog.add(sym);
+    }
+    const skillDirs = readdirSync(SKILLS_DIR, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && cfg.glob.test(d.name))
+      .map((d) => join(SKILLS_DIR, d.name));
+    const files = [];
+    for (const d of skillDirs) if (existsSync(d)) walkMd(d, files);
+
+    const fencePhantoms = new Map();
+    const proseOnly = new Map();
+    for (const f of files) {
+      const src = readFileSync(f, "utf8");
+      const fenceText = [...src.matchAll(FENCE_RE)].map((m) => m[1]).join("\n");
+      const fenceToks = tokensIn(fenceText);
+      const allToks = tokensIn(src);
+      for (const t of fenceToks) {
+        if (!catalog.has(t)) {
+          if (!fencePhantoms.has(t)) fencePhantoms.set(t, []);
+          fencePhantoms.get(t).push(f.replace(ROOT + "/", ""));
+        }
+      }
+      for (const t of allToks) {
+        if (!catalog.has(t) && !fenceToks.has(t)) {
+          if (!proseOnly.has(t)) proseOnly.set(t, []);
+          proseOnly.get(t).push(f.replace(ROOT + "/", ""));
+        }
+      }
+    }
+
+    const expected = EXPECTED_PROSE[family] || new Set();
+    const phantomList = [...fencePhantoms.entries()].map(([sym, fs]) => ({ symbol: sym, files: [...new Set(fs)] }));
+    const unexpectedProse = [...proseOnly.keys()].filter((t) => !expected.has(t));
+    if (phantomList.length) hardFail = true;
+    out.families[family] = {
+      catalogSymbols: catalog.size, filesScanned: files.length,
+      fencePhantoms: phantomList, proseOnlyUnexpected: unexpectedProse,
+      proseOnlyExpected: [...proseOnly.keys()].filter((t) => expected.has(t)),
+    };
+  }
+
+
+  // ── SDK families (NAMESPACE shape) — check headless SDK skill(s) against THEIR catalog ──
+  // SDK_SKILLS is derived from families.json at module level (RULES.md §22).
+  const NS_RE = /CometChat\.([A-Za-z_][A-Za-z0-9_]*)/g;
+  for (const [dir, { cat: catKey, extra }] of Object.entries(SDK_SKILLS)) {
+    const sdir = join(SKILLS_DIR, dir);
+    if (!existsSync(sdir)) continue;
+    const scat = loadSymbols(join(ROOT, "test-suite", "catalogs", catKey + ".json"));
+    if (!scat) { console.error(`missing SDK catalog: ${catKey}.json`); continue; }
+    for (const ex of extra || []) {
+      const s = loadSymbols(join(ROOT, "test-suite", "catalogs", ex + ".json"));
+      if (s) for (const sym of s) scat.add(sym);
+    }
+    const sdkPhantoms = new Map();
+    let sdkFiles = 0;
+    for (const f of walkMd(sdir, [])) {
+      sdkFiles++;
+      const fenceText = [...readFileSync(f, "utf8").matchAll(FENCE_RE)].map((m) => m[1]).join("\n");
+      const toks = new Set([...fenceText.matchAll(NS_RE)].map((m) => m[1]));
+      for (const t of tokensIn(fenceText)) if (t !== "CometChat") toks.add(t);
+      for (const t of toks) {
+        if (!scat.has(t)) { if (!sdkPhantoms.has(t)) sdkPhantoms.set(t, []); sdkPhantoms.get(t).push(f.replace(ROOT + "/", "")); }
+      }
+    }
+    const list = [...sdkPhantoms.entries()].map(([sym, fs]) => ({ symbol: sym, files: [...new Set(fs)] }));
+    if (list.length) hardFail = true;
+    out.sdk[dir] = { catalog: catKey, filesScanned: sdkFiles, fencePhantoms: list };
+  }
+
+  // ── Drift guard: every shipped catalog vs the reviewer's G0 oracle copy ───
+  for (const key of readdirSync(join(ROOT, "test-suite", "catalogs")).filter((f) => f.endsWith(".json")).map((f) => f.replace(/\.json$/, ""))) {
+    const shipped = loadSymbols(join(ROOT, "test-suite", "catalogs", `${key}.json`));
+    const reviewer = loadSymbols(join(ROOT, ".claude", "skills", "cometchat-skill-reviewer", "tools", "catalog", `${key}.json`));
+    if (!shipped || !reviewer) continue;
+    const onlyShipped = [...shipped].filter((s) => !reviewer.has(s));
+    const onlyReviewer = [...reviewer].filter((s) => !shipped.has(s));
+    if (onlyShipped.length || onlyReviewer.length) {
+      out.drift[key] = { onlyShipped, onlyReviewer };
+      if (STRICT_DRIFT) hardFail = true;
+    }
+  }
+
+  out.ok = !hardFail;
+  if (JSON_OUT) { console.log(JSON.stringify(out)); process.exit(hardFail ? 1 : 0); }
+
+  for (const [family, r] of Object.entries(out.families)) {
+    console.log(`verify-catalog [${family}]: ${r.catalogSymbols} catalog symbols · ${r.filesScanned} skill file(s) scanned`);
+    if (r.fencePhantoms.length) {
+      console.log(`❌ ${r.fencePhantoms.length} phantom symbol(s) in code fences (not in ${family}.json):`);
+      for (const p of r.fencePhantoms) console.log(`  - ${p.symbol}  (${p.files.join(", ")})`);
+    } else {
+      console.log(`✅ Tier-1 [${family}]: every CometChat* symbol in a code fence exists in the catalog.`);
+    }
+    if (r.proseOnlyUnexpected.length) {
+      console.log(`⚠️  ${r.proseOnlyUnexpected.length} UNEXPECTED prose-only CometChat* token(s) [${family}] (review): ${r.proseOnlyUnexpected.join(", ")}`);
+    } else if (r.proseOnlyExpected.length) {
+      console.log(`✅ Tier-1 (prose) [${family}]: only allowlisted intentional mentions (${r.proseOnlyExpected.length}).`);
+    }
+  }
+  for (const [dir, r] of Object.entries(out.sdk)) {
+    if (r.fencePhantoms.length) {
+      console.log(`❌ ${r.fencePhantoms.length} phantom SDK symbol(s) in ${dir} fences (not in ${r.catalog}.json):`);
+      for (const p of r.fencePhantoms) console.log(`  - ${p.symbol}  (${p.files.join(", ")})`);
+    } else {
+      console.log(`✅ Tier-1 (SDK) [${dir}]: every CometChat.<member> in a fence exists in ${r.catalog}.json (${r.filesScanned} file(s)).`);
+    }
+  }
+  for (const [key, d] of Object.entries(out.drift)) {
+    const tag = STRICT_DRIFT ? "❌ DRIFT" : "⚠️  DRIFT";
+    console.log(`${tag} [${key}]: shipped catalog != reviewer oracle.`);
+    if (d.onlyShipped.length) console.log(`    only in shipped: ${d.onlyShipped.join(", ")}`);
+    if (d.onlyReviewer.length) console.log(`    only in reviewer: ${d.onlyReviewer.join(", ")}`);
+    console.log(`    → resync both copies from the installed kit.`);
+  }
+  process.exit(hardFail ? 1 : 0);
+}
+
+main();

package/test-suite/scripts/verify-contract-fences.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * verify-contract-fences.mjs — the machine guard for RULES.md §23.
+ *
+ * An agent copies CODE FENCES, not prose and not tables. A skill can name a mandated component
+ * in a capability table, warn about it in prose, and still emit a surface without it — because
+ * the fence the agent actually copies never showed it. That is AUDIT-098: core's fence stopped
+ * at `onThreadRepliesPress` / `onSearchBarClicked` and never showed the screens those callbacks
+ * push, so every emit shipped 75% of core-chat-surface and G1 failed three times.
+ *
+ * SCOPE — contract-backed features ONLY. The pack is deliberately bake-the-hot-path /
+ * fetch-the-long-tail: most features' `ui_components` are legitimately fetched from docs and
+ * MUST NOT be baked. But a feature carrying a CONTRACT in contracts.<family>.json is the
+ * guaranteed minimum every emit must contain — so those components have to be shown, not
+ * merely named. It catches the class statically: no reviewer run, no credentials, no simulator.
+ */
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join, dirname, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "../..");
+const FAMILIES = join(ROOT, ".claude/skills/cometchat-skill-reviewer/tools/families.json");
+if (!existsSync(FAMILIES)) { console.log("❌ families.json missing"); process.exit(2); }
+const { families } = JSON.parse(readFileSync(FAMILIES, "utf8"));
+
+const walk = (d, acc = []) => {
+  for (const e of readdirSync(d)) {
+    const p = join(d, e);
+    if (statSync(p).isDirectory()) walk(p, acc);
+    else if (e.endsWith(".md")) acc.push(p);
+  }
+  return acc;
+};
+const fencesOf = (text) => {
+  const out = [];
+  let inFence = false;
+  for (const line of text.split("\n")) {
+    if (/^\s*```/.test(line)) { inFence = !inFence; continue; }
+    if (inFence) out.push(line);
+  }
+  return out.join("\n");
+};
+
+let checked = 0, failures = [], baselined = [];
+for (const [key, fam] of Object.entries(families)) {
+  if (/^template\b/i.test(fam._status || "")) continue;
+  const name = basename(fam.catalog || "", ".json");
+  const featPath = join(ROOT, fam.features || `features.${name}.json`);
+  const conPath = join(ROOT, fam.contracts || `contracts.${name}.json`);
+  if (!existsSync(featPath) || !existsSync(conPath)) continue;
+  const feats = JSON.parse(readFileSync(featPath, "utf8")).features || [];
+  // Only features that carry a `kind: "feature"` contract — the guaranteed minimum.
+  const contracted = new Set(
+    (JSON.parse(readFileSync(conPath, "utf8")).contracts || [])
+      .filter((c) => c.kind === "feature").map((c) => c.for));
+
+  // the skills belonging to this family
+  const prefixes = (fam.reviewsSkills || []).filter((p) => p.endsWith("-"));
+  const dir = join(ROOT, "skills");
+  const mine = readdirSync(dir).filter((s) => prefixes.some((p) => s.startsWith(p)));
+  if (!mine.length) continue;
+  const fenceText = mine.flatMap((s) => walk(join(dir, s))).map((f) => fencesOf(readFileSync(f, "utf8"))).join("\n");
+
+  for (const feat of feats) {
+    if (!contracted.has(feat.id)) continue;   // long tail is fetched from docs, by design
+    const comps = feat.ui_components || [];
+    if (!comps.length) continue;
+    if (feat.auto_rendered_ui) continue;       // kit renders it internally — no client code to show
+    checked++;
+    let missing = comps.filter((c) => !new RegExp(`\\b${c}\\b`).test(fenceText));
+    // A baselined entry is a RECORDED ARTIFACT CONFLICT, not an exemption: it still prints on
+    // every run so it cannot rot into silence. Never extend it to quiet a NEW failure.
+    const base = (fam.fenceBaseline || {})[feat.id] || [];
+    const waived = missing.filter((c) => base.includes(c));
+    missing = missing.filter((c) => !base.includes(c));
+    if (waived.length) baselined.push({ family: name, feature: feat.id, waived });
+    if (missing.length) failures.push({ family: name, feature: feat.id, missing, total: comps.length });
+  }
+}
+
+if (!checked) { console.log("❌ contract-fences: no features checked — discovery broke"); process.exit(2); }
+for (const b of baselined) {
+  console.log(`⚠️  contract-fences: ${b.family} · ${b.feature} — baselined artifact conflict: ${b.waived.join(", ")}`);
+  console.log(`    (contracts.json mandates it; the skill routes it to FETCH — one of the two is wrong. See families.json fenceBaseline._reason.)`);
+}
+if (!failures.length) { console.log(`✅ contract-fences: ${checked} feature(s) checked; every declared ui_component appears in a code fence${baselined.length ? ` (${baselined.length} baselined conflict(s) above)` : ""}.`); process.exit(0); }
+
+console.log(`❌ contract-fences: ${failures.length}/${checked} feature(s) declare a component no code fence shows — RULES.md §23.`);
+console.log("   Prose and capability tables do not survive into an emit; the agent copies fences.\n");
+for (const f of failures) {
+  console.log(`   ${f.family} · ${f.feature}  (${f.total - f.missing.length}/${f.total} shown)`);
+  console.log(`      never in a fence: ${f.missing.join(", ")}`);
+}
+process.exit(1);

package/test-suite/scripts/verify-detection.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+/**
+ * verify-detection.mjs — assert peers.yaml `detect_signals` route each fixture to
+ * the right platform.
+ *
+ *   node test-suite/scripts/verify-detection.mjs [--json]
+ *
+ * WHY THIS EXISTS
+ * Detection is the FIRST thing that happens in a real run: the router reads the
+ * repo, matches `detect_signals`, and dispatches. Get it wrong and every skill
+ * downstream is unreachable — the failure looks like "the pack doesn't support my
+ * framework", with nothing pointing at the cause.
+ *
+ * `test-suite/fixtures/` held realistic project skeletons for exactly this, but
+ * nothing had read them since the v5 pivot deleted the harness that did. So the
+ * signals were unverified, and adding a fixture without a consumer would just be
+ * a prop that makes coverage look real.
+ *
+ * Checks per fixture:
+ *   1. it matches its EXPECTED platform
+ *   2. it does NOT match any other platform (no ambiguous routing)
+ * A fixture with no expectation is a hard error, so a new one can't be added and
+ * silently ignored.
+ *
+ * `signal:` entries are conversational cues, not repo facts — skipped here. Parked peers are a
+ * routing spec only (nothing installable) and never route.
+ *
+ * Static checks on peers.yaml itself (fail even with no fixture for the peer):
+ *   3. every live peer's `detect_signals` parses to ≥1 entry — BOTH YAML list styles (inline
+ *      `[a, b]` and block `- a`). The old inline-only regex read 0 signals for react-native,
+ *      ios-calls and flutter-calls and still printed "no ambiguous matches".
+ *   4. no two live peers claim the SAME repo-fact signal (ios-calls once shared `*.xcodeproj`
+ *      with the ios UI Kit peer, so every Xcode project matched both).
+ *
+ * Signal forms: `<file>:<dep>` (a .json manifest dependency, else a substring of the file),
+ * `file:<path>` / `<path>` (presence), `*.ext` (any root entry with that suffix).
+ *
+ * Exit: 0 all fixtures route correctly · 1 a mismatch · 2 bad setup.
+ */
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const FIXTURES = join(ROOT, "test-suite", "fixtures");
+const JSON_OUT = process.argv.includes("--json");
+
+// Expected platform per fixture. Adding a fixture without an entry FAILS — that is
+// deliberate: an unclassified fixture is an untested one.
+const EXPECTED = {
+  "angular-cli": "angular",
+  "astro-react": "react",
+  "astro-with-pages": "react",
+  // RN / Expo route to the react-native peer (its detect_signals are a BLOCK-style YAML list,
+  // which the old inline-only parser read as empty — so these used to "pass" as null).
+  "bare-react-native": "react-native",
+  "expo-managed": "react-native",
+  "expo-router": "react-native",
+  "nextjs-app": "react",
+  "nextjs-with-nextauth": "react",
+  "react-router-v7": "react",
+  "react-router-with-routes": "react",
+  "react-vite": "react",
+  "react-with-auth": "react",
+};
+
+// ── parse peers.yaml: platform → detect_signals[] ────────────────────────────
+// A YAML list value in either style: inline `key: [a, "b"]` (may wrap lines) or block
+//   key:
+//     - "a"   # comment
+// Returns null when the key is absent, [] when present but empty.
+const unquote = (v) => { const q = /^(["'])(.*?)\1/.exec(v); return q ? q[2] : v.replace(/\s+#.*$/, "").trim(); };
+function yamlList(block, key) {
+  const inline = new RegExp(`^[ \\t]*${key}:[ \\t]*\\[([^\\]]*)\\]`, "m").exec(block);
+  if (inline) return inline[1].split(",").map((x) => unquote(x.trim())).filter(Boolean);
+  const head = new RegExp(`^[ \\t]*${key}:[ \\t]*(?:#.*)?$`, "m").exec(block);
+  if (!head) return null;
+  const items = [];
+  for (const line of block.slice(head.index + head[0].length).split("\n").slice(1)) {
+    if (/^\s*(#.*)?$/.test(line)) continue;             // blank / comment line inside the list
+    const it = /^\s*-\s+(.*)$/.exec(line);
+    if (!it) break;                                     // next key — list ended
+    items.push(unquote(it[1].trim()));
+  }
+  return items;
+}
+const y = readFileSync(join(ROOT, "peers.yaml"), "utf8");
+const peers = [];
+let badSetup = 0;
+for (const raw of y.split(/^\s*-\s*platform:/m).slice(1)) {
+  const block = "platform:" + raw;
+  const platform = (block.match(/platform:\s*(\S+)/) || [])[1];
+  if (!platform) continue;
+  if (/^\s*parked:\s*true\b/m.test(block)) continue; // routing spec only — never routes
+  const signals = yamlList(block, "detect_signals");
+  const exclude = yamlList(block, "exclude_signals") || [];
+  if (signals !== null && signals.length === 0) {
+    console.error(`❌ ${platform}: detect_signals parsed to 0 entries — peers.yaml format and this parser disagree`);
+    badSetup++;
+  }
+  peers.push({ platform, signals: signals || [], exclude });
+}
+if (!peers.length) { console.error("parsed 0 peers from peers.yaml — check the format"); process.exit(2); }
+if (badSetup) process.exit(2);
+
+// ── static: no two live peers may claim the same repo-fact signal ────────────
+const owners = new Map();
+for (const p of peers) for (const s of p.signals.filter((x) => !x.startsWith("signal:"))) {
+  owners.set(s, [...(owners.get(s) || []), p.platform]);
+}
+const collisions = [...owners].filter(([, ps]) => ps.length > 1);
+for (const [s, ps] of collisions) console.error(`❌ detect signal "${s}" is claimed by ${ps.join(" + ")} — every such project matches both`);
+
+// ── evaluate one signal against a fixture dir ────────────────────────────────
+function matches(signal, dir) {
+  if (signal.startsWith("signal:")) return false;            // conversational cue, not a repo fact
+  if (signal.startsWith("*.")) {                              // glob on a root entry, e.g. *.xcodeproj
+    const ext = signal.slice(1);
+    return readdirSync(dir).some((f) => f.endsWith(ext));
+  }
+  const i = signal.indexOf(":");
+  let file = i < 0 ? signal : signal.slice(0, i);
+  let dep = i < 0 ? "" : signal.slice(i + 1);
+  if (file === "file") { file = dep; dep = ""; }             // file:<path> — bare presence
+  const p = join(dir, file);
+  if (!existsSync(p)) return false;
+  if (!dep) return true;                                     // bare file presence, e.g. angular.json
+  let text;
+  try { text = readFileSync(p, "utf8"); } catch { return false; }
+  if (!file.endsWith(".json")) return text.includes(dep);    // Package.swift / Podfile / gradle / pubspec
+  let pkg;
+  try { pkg = JSON.parse(text); } catch { return false; }
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}), ...(pkg.peerDependencies || {}) };
+  return Object.prototype.hasOwnProperty.call(deps, dep);
+}
+
+const fixtures = readdirSync(FIXTURES, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
+const rows = [];
+let failed = 0;
+
+for (const name of fixtures) {
+  const fixtureDir = join(FIXTURES, name);
+  if (!existsSync(join(fixtureDir, "package.json")) && !existsSync(join(fixtureDir, "pubspec.yaml"))) {
+    continue;   // not an app fixture — belongs to another gate, not detection
+  }
+  if (!(name in EXPECTED)) {
+    console.error(`❌ ${name}: no entry in EXPECTED — add one (use null if no peer should match)`);
+    failed++;
+    continue;
+  }
+  const dir = join(FIXTURES, name);
+  // exclude_signals veto a match: e.g. `react` matches an RN project, but
+  // package.json:react-native rules the web peer out.
+  const hits = peers
+    .filter((p) => p.signals.some((s) => matches(s, dir)) && !p.exclude.some((s) => matches(s, dir)))
+    .map((p) => p.platform);
+  const want = EXPECTED[name];
+  const ok = want === null ? hits.length === 0 : hits.length === 1 && hits[0] === want;
+  rows.push({ fixture: name, expected: want, matched: hits, ok });
+  if (!ok) failed++;
+}
+
+failed += collisions.length;
+if (JSON_OUT) { console.log(JSON.stringify({ rows, collisions: collisions.map(([signal, ps]) => ({ signal, peers: ps })), failed }, null, 2)); process.exit(failed ? 1 : 0); }
+
+const sigCount = peers.reduce((n, p) => n + p.signals.length, 0);
+console.log(`verify-detection: ${fixtures.length} fixture(s) · ${peers.length} live peer(s) · ${sigCount} detect signal(s) in peers.yaml\n`);
+for (const r of rows) {
+  const mark = r.ok ? "✅" : "❌";
+  const got = r.matched.length ? r.matched.join(" + ") : "(none)";
+  console.log(`  ${mark} ${r.fixture.padEnd(26)} expected ${String(r.expected ?? "(none)").padEnd(12)} matched ${got}`);
+}
+if (failed === 0) {
+  console.log(`\n✅ every fixture routes to exactly its expected platform (no ambiguous matches; no shared detect signals).`);
+  process.exit(0);
+}
+console.log(`\n❌ ${failed} problem(s): ${failed - collisions.length} fixture(s) route incorrectly, ${collisions.length} shared detect signal(s) — fix detect_signals in peers.yaml, or EXPECTED if it is wrong.`);
+process.exit(1);

package/test-suite/scripts/verify-docs-base.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * verify-docs-base.mjs — block a preview docs host from ever being merged.
+ *
+ * A skill's fetch ladder is half its value: the hot path is baked, everything else is fetched
+ * from DOCS_BASE at runtime. Pointing that at a Mintlify PR preview is the right thing while
+ * the docs PR is open — you want to test against the fixed pages, not stale production ones.
+ *
+ * But a preview DIES when its PR closes. Merging a pack that points at one silently breaks
+ * every long-tail fetch for every customer: no error at build, no error at install, just a
+ * skill that can no longer answer anything it did not bake.
+ *
+ * A comment saying "revert before merge" is not a guard — it depends on someone remembering
+ * at exactly the wrong moment. This is the guard.
+ *
+ *   default   warn — the dev loop stays green so testing against a preview works
+ *   --strict  FAIL — wired into verify:ci, so a preview host cannot reach main
+ */
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join, dirname, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "../..");
+const STRICT = process.argv.includes("--strict");
+
+// Anything that is not the production docs origin is a staging/preview host.
+const PRODUCTION = "https://www.cometchat.com/docs";
+const SUSPECT = /https:\/\/[a-z0-9.-]*(mintlify\.site|vercel\.app|netlify\.app|ngrok[a-z.-]*|localhost(:\d+)?)/gi;
+
+const walk = (d, acc = []) => {
+  if (!existsSync(d)) return acc;
+  for (const e of readdirSync(d)) {
+    const p = join(d, e);
+    if (statSync(p).isDirectory()) walk(p, acc);
+    else if (/\.(md|json|ya?ml)$/i.test(e)) acc.push(p);
+  }
+  return acc;
+};
+
+const hits = [];
+for (const f of walk(join(ROOT, "skills"))) {
+  readFileSync(f, "utf8").split("\n").forEach((line, i) => {
+    for (const m of line.matchAll(SUSPECT)) {
+      // A prose mention of localhost (HTTPS requirements, service workers) is not a docs base.
+      if (/localhost/i.test(m[0]) && !/DOCS_BASE|SDK_DOCS_BASE/.test(line)) continue;
+      hits.push({ file: relative(ROOT, f), line: i + 1, host: m[0], isBase: /DOCS_BASE|SDK_DOCS_BASE/.test(line) });
+    }
+  });
+}
+
+// AUDIT-182 — the TEST-MODE:MCP-ONLY banner is the same class as a preview host: a temporary
+// test-run artifact whose "delete before go-live" comment is not a guard. A HARD-STOP wording
+// ("if the MCP is not connected, STOP") strands every real user without the MCP, so it is
+// flagged in the dev loop too; any banner at all fails --strict, exactly like a preview host.
+const BANNER = /TEST-MODE:MCP-ONLY/;
+const SOFT = /SOFT gate|authorize the fetch fallback/i;
+const banners = [];
+const bannerFiles = walk(join(ROOT, "skills")).filter((f) => /\.md$/i.test(f));
+if (existsSync(join(ROOT, "RULES.md"))) bannerFiles.push(join(ROOT, "RULES.md"));
+for (const f of bannerFiles) {
+  const txt = readFileSync(f, "utf8");
+  if (!BANNER.test(txt)) continue;
+  const i = txt.split("\n").findIndex((l) => BANNER.test(l));
+  const block = txt.slice(txt.indexOf("TEST-MODE:MCP-ONLY"), txt.indexOf("TEST-MODE:MCP-ONLY") + 1200);
+  banners.push({ file: relative(ROOT, f), line: i + 1, hard: !SOFT.test(block) });
+}
+if (banners.length) {
+  const hard = banners.filter((b) => b.hard);
+  console.log(`${STRICT ? "❌" : "⚠️ "} docs-base: ${banners.length} TEST-MODE:MCP-ONLY banner(s) still shipped${hard.length ? ` — ${hard.length} with HARD-STOP wording (a real user without the MCP gets no integration; AUDIT-182)` : ""}.`);
+  for (const b of banners) console.log(`   ${b.file}:${b.line}${b.hard ? "  [HARD STOP — make it the soft ask-to-authorize gate]" : "  [soft gate — delete before go-live]"}`);
+  console.log("   Fix: delete the banner (grep TEST-MODE:MCP-ONLY) to restore MCP-preferred + fetch-fallback; ADD-FRAMEWORK.md Phase F.\n");
+}
+
+if (!hits.length) {
+  if (banners.length && STRICT) { console.log("   (blocking: verify:ci)"); process.exit(1); }
+  console.log(`✅ docs-base: every skill fetches from production (${PRODUCTION}).`);
+  process.exit(0);
+}
+
+const bases = hits.filter((h) => h.isBase);
+const label = STRICT ? "❌" : "⚠️ ";
+console.log(`${label} docs-base: ${hits.length} non-production docs host(s) in skills/ — ${bases.length} of them a DOCS_BASE.`);
+console.log("   A preview dies when its PR closes; merging this breaks every long-tail fetch, silently.\n");
+for (const h of hits) {
+  console.log(`   ${h.file}:${h.line}${h.isBase ? "  [DOCS_BASE]" : ""}`);
+  console.log(`      ${h.host}`);
+}
+console.log(`\n   Fix: set DOCS_BASE and SDK_DOCS_BASE back to ${PRODUCTION}`);
+if (STRICT) { console.log("   (blocking: verify:ci)"); process.exit(1); }
+console.log("   (warning only — verify:ci will BLOCK this)");
+process.exit(0);