efaimo 0.1.2 → 0.3.0

package/dist/reporters/pretty.js

@@ -1,6 +1,7 @@
 import pc from "picocolors";
 import { formatWindowShare } from "../weigh/window.js";
 import { sortFindings } from "../core/grade.js";
+import { minimumDetectableDelta } from "../testing/stats.js";
 import { VERSION } from "../version.js";
 import { safeText } from "../util/safeText.js";
 const DOCS_RULES = "https://github.com/efaimo-ai/efaimo/blob/main/docs/RULES.md";
@@ -32,8 +33,23 @@ function gradeColor(letter, text) {
 function n(x) {
     return x.toLocaleString("en-US");
 }
+/**
+ * A value that has to stay inside one line of a table or one line of a
+ * finding.
+ *
+ * `safeText` strips control characters but deliberately keeps newlines,
+ * because a detail block is meant to be multi-line. That is the wrong default
+ * for a single cell: a tool named
+ * `nl_tool\n      9  forged_row      weather, forecast` renders as a SECOND
+ * row byte-identical in shape to a real one, and under `--no-color`, which is
+ * how CI logs read, there is no tell at all. The audited thing must not be
+ * able to write rows in the auditor's table.
+ */
+function cell(s) {
+    return safeText(s).replace(/[\r\n]+/g, " ");
+}
 function renderFinding(lines, f) {
-    lines.push(`  ${sevGlyph(f)} ${paint(pc.bold, f.ruleId)}  ${safeText(f.message)}`);
+    lines.push(`  ${sevGlyph(f)} ${paint(pc.bold, f.ruleId)}  ${cell(f.message)}`);
     if (f.detail) {
         for (const d of safeText(f.detail).split("\n"))
             lines.push(paint(pc.dim, `          ${d}`));
@@ -80,13 +96,23 @@ export function renderCheckPretty(report) {
 export function renderScenarioPlan(s) {
     const calls = s.trials * 2 * 2;
     const firstLine = s.task.split("\n")[0].slice(0, 60);
+    const mde = minimumDetectableDelta(s.trials);
     return [
         paint(pc.dim, `efaimo v${VERSION}`),
         `test (dry run)  ${paint(pc.bold, s.name)}`,
         "",
         `  skill   ${s.skillName}`,
         `  model   ${s.model}`,
+        `  judge   ${s.judgeModel}${s.judgeModel === s.model
+            ? paint(pc.yellow, "   (same model grades its own answers; set judge_model or --judge-model to separate them)")
+            : ""}`,
         `  plan    ${s.trials} trials x 2 arms x (task + judge) = ${paint(pc.bold, String(calls))} API calls`,
+        // What this plan cannot detect, before any tokens are spent. A run that
+        // cannot reach significance produces a green that means nothing, and the
+        // only useful moment to learn that is now.
+        `  power   ${Number.isFinite(mde)
+            ? `the smallest gap this size can call significant is ${paint(mde > 40 ? pc.yellow : pc.dim, `${mde.toFixed(0)} points`)}${mde > 40 ? paint(pc.yellow, "   (raise trials)") : ""}`
+            : paint(pc.red, "no outcome at this size can reach p < 0.05; raise trials")}`,
         `  task    ${paint(pc.dim, firstLine + (s.task.length > 60 ? "..." : ""))}`,
         "",
         paint(pc.yellow, "dry run: no API calls made. add --live to run it (Claude models need ANTHROPIC_API_KEY, GPT models need OPENAI_API_KEY)."),
@@ -98,7 +124,7 @@ export function renderTestReportPretty(r) {
     const lines = [
         paint(pc.dim, `efaimo v${VERSION}`),
         `test  ${paint(pc.bold, r.scenario)}`,
-        `skill ${r.skill}   model ${r.model}`,
+        `skill ${r.skill}   model ${r.model}   judge ${r.judgeModel}${r.judgeModel === r.model ? paint(pc.dim, " (same model)") : ""}`,
         "",
         `  with skill     ${r.withSkill.passes}/${r.withSkill.scored} pass  (${r.withSkill.passRate.toFixed(0)}%)`,
         `  without skill  ${r.withoutSkill.passes}/${r.withoutSkill.scored} pass  (${r.withoutSkill.passRate.toFixed(0)}%)`,
@@ -130,21 +156,21 @@ export function renderSkillSetPretty(res) {
     for (const s of [...res.perSkill].sort((a, b) => a.report.grade.score - b.report.grade.score)) {
         const g = s.report.grade;
         const c = s.report.counts;
-        lines.push(`  ${gradeColor(g.letter, `${g.letter} (${String(g.score).padStart(3)})`)}  ${safeText(s.name).padEnd(nameW)}  ` +
+        lines.push(`  ${gradeColor(g.letter, `${g.letter} (${String(g.score).padStart(3)})`)}  ${cell(s.name).padEnd(nameW)}  ` +
             `${paint(pc.red, String(c.error))}e ${paint(pc.yellow, String(c.warn))}w ${paint(pc.cyan, String(c.info))}i`);
     }
     if (res.setFindings.length) {
         lines.push("");
         lines.push(paint(pc.bold, "across the set"));
         for (const f of sortFindings(res.setFindings)) {
-            lines.push(`  ${sevGlyph(f)} ${paint(pc.bold, f.ruleId)}  ${safeText(f.message)}`);
+            lines.push(`  ${sevGlyph(f)} ${paint(pc.bold, f.ruleId)}  ${cell(f.message)}`);
         }
     }
     const flagged = res.perSkill.filter((s) => s.report.findings.length);
     if (flagged.length) {
         lines.push("");
         for (const s of flagged) {
-            lines.push(paint(pc.bold, `${safeText(s.name)}  ${gradeColor(s.report.grade.letter, s.report.grade.letter)}`));
+            lines.push(paint(pc.bold, `${cell(s.name)}  ${gradeColor(s.report.grade.letter, s.report.grade.letter)}`));
             for (const f of s.report.findings) {
                 lines.push(`  ${sevGlyph(f)} ${paint(pc.bold, f.ruleId)}  ${safeText(f.message)}`);
                 if (f.fixHint)
@@ -170,7 +196,7 @@ export function renderServerWeighPretty(w) {
     if (w.instructionsTokens > 0)
         lines.push(`  server instructions ${n(w.instructionsTokens).padStart(4)}`);
     if (w.anthropicExactTotal !== undefined) {
-        lines.push(`  ${paint(pc.green, "anthropic exact")} ${n(w.anthropicExactTotal).padStart(8)}   (count_tokens API)`);
+        lines.push(`  ${paint(pc.green, "anthropic exact")} ${n(w.anthropicExactTotal).padStart(8)}   (count_tokens, ${safeText(w.anthropicExactModel ?? "model not recorded")})`);
     }
     if (w.perTool.length) {
         lines.push("");
@@ -183,9 +209,9 @@ export function renderServerWeighPretty(w) {
         // column in its own flagship demo. Capped so one pathological name cannot
         // push the numbers off a terminal.
         const shown = w.perTool.slice(0, 8);
-        const toolW = Math.min(38, Math.max(20, ...shown.map((t) => safeText(t.name).length)));
+        const toolW = Math.min(38, Math.max(20, ...shown.map((t) => cell(t.name).length)));
         for (const [i, t] of shown.entries()) {
-            lines.push(`  ${String(i + 1).padStart(2)}. ${safeText(t.name).padEnd(toolW)} ${n(t.tokens.claudeStyle).padStart(7)}   desc ${n(t.descriptionTokens)} | schema ${n(t.schemaTokens)}`);
+            lines.push(`  ${String(i + 1).padStart(2)}. ${cell(t.name).padEnd(toolW)} ${n(t.tokens.claudeStyle).padStart(7)}   desc ${n(t.descriptionTokens)} | schema ${n(t.schemaTokens)}`);
         }
         if (w.perTool.length > 8)
             lines.push(paint(pc.dim, `      (+${w.perTool.length - 8} more)`));
@@ -205,7 +231,7 @@ export function renderSkillWeighPretty(w) {
     lines.push("");
     lines.push(`  ${"skill".padEnd(28)} ${"metadata".padStart(8)} ${"body".padStart(9)} ${"lines".padStart(6)}  refs`);
     for (const s of w.perSkill) {
-        lines.push(`  ${safeText(s.name).padEnd(28)} ${n(s.metadataTokens).padStart(8)} ${n(s.bodyTokens).padStart(9)} ${String(s.bodyLines).padStart(6)}  ${s.refFileCount ? `${s.refFileCount} files ${n(s.refFileTokens)}` : "-"}`);
+        lines.push(`  ${cell(s.name).padEnd(28)} ${n(s.metadataTokens).padStart(8)} ${n(s.bodyTokens).padStart(9)} ${String(s.bodyLines).padStart(6)}  ${s.refFileCount ? `${s.refFileCount} files ${n(s.refFileTokens)}` : "-"}`);
     }
     lines.push("");
     lines.push(`totals: metadata ${paint(pc.bold, n(w.totals.metadata))} (always loaded) | body ${n(w.totals.body)} (on trigger) | referenced ${n(w.totals.refFiles)} (on demand)`);
@@ -214,6 +240,151 @@ export function renderSkillWeighPretty(w) {
         lines.push(paint(pc.dim, `note: ${safeText(note)}`));
     return lines.join("\n");
 }
+/**
+ * `efaimo find`.
+ *
+ * Two numbers, both as fractions with their denominators printed, neither a
+ * letter. The first is a property of the catalog; the second is a simulation
+ * and is labelled as one on the line itself, because a saturated 100% next to
+ * a real measurement reads like a good score unless the page says otherwise.
+ */
+export function renderFindPretty(f) {
+    const lines = [];
+    lines.push(paint(pc.dim, `efaimo v${VERSION}`));
+    lines.push(`find mcp  ${paint(pc.bold, safeText(f.label))}`);
+    lines.push(paint(pc.dim, `tools ${f.toolCount}   result window ${f.method.topK}   BM25 k1=${f.method.bm25.k1} b=${f.method.bm25.b}, ${f.method.queryTerms} query terms`));
+    lines.push("");
+    // Coloured on the rule condition, not on invented cutoffs. An earlier
+    // version banded this at 95 and 80 percent, two numbers that appear in no
+    // rule, no doc and no ADR, inside the one command whose whole design note
+    // says it does not grade. Red means E141 fired; that is a threshold the
+    // ruleset already owns.
+    const dpct = f.distinct.pct;
+    const anyOwnsNothing = f.distinct.count < f.distinct.total;
+    const dcolor = f.distinctVacuous ? pc.dim : anyOwnsNothing ? pc.red : pc.green;
+    const dFrac = `${f.distinct.count}/${f.distinct.total} (${dpct}%)`;
+    const pFrac = `${f.probe.returned}/${f.probe.total} (${f.probe.pct}%)`;
+    // Pad on the plain text, never on the painted string: colour codes are bytes
+    // that padEnd counts and a terminal does not, which is how a coloured column
+    // ends up crooked in exactly the demo everyone screenshots.
+    const fracW = Math.max(dFrac.length, pFrac.length);
+    lines.push(`distinct  ${paint(dcolor, dFrac)}${" ".repeat(fracW - dFrac.length)}` +
+        `   ${paint(pc.dim, "tools that own a word no other tool has")}`);
+    if (f.distinctVacuous) {
+        lines.push(paint(pc.yellow, `          vacuous: a one-tool catalog has nothing to be distinct from, so this is 100% for any tool`));
+    }
+    lines.push(`probe     ${paint(pc.dim, pFrac)}${" ".repeat(fracW - pFrac.length)}` +
+        `   ${paint(pc.dim, "returned by a simulated search for their own description")}`);
+    if (f.windowCoversCatalog) {
+        lines.push(paint(pc.yellow, `          vacuous: ${f.toolCount} tools fit inside a window of ${f.method.topK}, so none can fall outside it`));
+    }
+    lines.push("");
+    // Worst first. A reader scanning the top of the table should be looking at
+    // the tools that cannot be told apart, not at an alphabetical list.
+    const byWorst = [...f.perTool].sort((a, b) => {
+        const ar = a.rank ?? Number.POSITIVE_INFINITY;
+        const br = b.rank ?? Number.POSITIVE_INFINITY;
+        return (a.ownTermCount - b.ownTermCount ||
+            br - ar ||
+            (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    });
+    const shown = byWorst.slice(0, 15);
+    const nameW = Math.min(34, Math.max(12, ...shown.map((t) => cell(t.name).length)));
+    if (f.sources && f.sources.length > 1) {
+        // The whole point of a stack run is which server a colliding tool came
+        // from, so it goes beside the name rather than into a footnote.
+        lines.push(paint(pc.dim, `  merged ${f.sources.length} catalogs: ${f.sources.join(", ")}`));
+    }
+    lines.push(paint(pc.dim, `  words  ${"tool".padEnd(nameW)}  vocabulary no other tool has`));
+    for (const t of shown) {
+        const count = t.ownTermCount === 0
+            ? paint(pc.red, "    0")
+            : t.ownTermCount === 1
+                ? paint(pc.yellow, "    1")
+                : paint(pc.green, String(t.ownTermCount).padStart(5));
+        let tail;
+        if (t.ownTermCount === 0) {
+            tail = paint(pc.red, t.sharedWith.length ? `none: every word also on ${cell(t.sharedWith.join(", "))}` : "none");
+        }
+        else {
+            const more = t.ownTermCount - t.ownTerms.length;
+            tail = paint(pc.dim, cell(t.ownTerms.join(", ")) + (more > 0 ? ` (+${more})` : ""));
+        }
+        // The probe only ever appears as a flag on a row it failed. A column of
+        // "1" down the whole table would be a number that never varies presented
+        // as if it were a measurement.
+        const probe = t.rank === undefined
+            ? paint(pc.red, "   [probe: no description]")
+            : t.reachable
+                ? ""
+                : paint(pc.red, `   [probe: rank ${t.rank}]`);
+        const from = t.origin ? paint(pc.dim, `  [${t.origin}]`) : "";
+        lines.push(`  ${count}  ${cell(t.name).padEnd(nameW)}  ${tail}${probe}${from}`);
+    }
+    // Describe the hidden rows from the hidden rows, never from an assumption.
+    // This line used to read "(+N more, each owning at least one word)" without
+    // checking: on a catalog where all 18 tools owned nothing it printed that
+    // three lines under a `0/18` headline saying the opposite.
+    const hiddenRows = byWorst.slice(shown.length);
+    if (hiddenRows.length) {
+        const hiddenAtZero = hiddenRows.filter((t) => t.ownTermCount === 0).length;
+        lines.push(paint(pc.dim, `         (+${hiddenRows.length} more` +
+            (hiddenAtZero ? `, ${hiddenAtZero} of them owning no word` : ", each owning at least one word") +
+            `; --json for all of them)`));
+    }
+    return lines.join("\n");
+}
+/** The findings half of `efaimo find`, printed under the table. */
+export function renderFindFindingsPretty(f, findings) {
+    const lines = [""];
+    if (!findings.length) {
+        lines.push(paint(pc.green, "  no findability findings."));
+    }
+    else {
+        for (const x of sortFindings(findings))
+            renderFinding(lines, x);
+    }
+    lines.push("");
+    for (const note of f.notes) {
+        // The two vacuity notes are already printed inline, in yellow, on the row
+        // the reader is looking at. Repeating them here as prose was the same
+        // warning twice in one screen; the data still carries them for --json and
+        // --md, where there is no inline row to carry it.
+        if (note.startsWith("VACUOUS"))
+            continue;
+        for (const [i, line] of wrapNote(safeText(note)).entries()) {
+            lines.push(paint(pc.dim, i === 0 ? `note: ${line}` : `      ${line}`));
+        }
+    }
+    // What to do next. A clean run used to end on "no findability findings" and
+    // a rules URL, which tells a first-time reader nothing about how to keep it
+    // that way. `distinct` is named because it is the number that can fail at
+    // any catalog size; the probe cannot.
+    if (!f.distinctVacuous) {
+        lines.push(paint(pc.dim, `gate it: efaimo find "<server>" --min-distinct ${Math.floor(f.distinct.pct)}` +
+            (f.distinct.pct < 100 ? "   (raise it as you fix the tools above)" : "")));
+    }
+    lines.push(paint(pc.dim, `rules: ${DOCS_RULES}`));
+    return lines.join("\n");
+}
+/** Soft-wrap a long note at ~92 columns on word boundaries, so terminals do not ragged-wrap mid-number. */
+function wrapNote(s, width = 92) {
+    const out = [];
+    for (const paragraph of s.split("\n")) {
+        let line = "";
+        for (const word of paragraph.split(/\s+/)) {
+            if (line && line.length + 1 + word.length > width) {
+                out.push(line);
+                line = word;
+            }
+            else {
+                line = line ? `${line} ${word}` : word;
+            }
+        }
+        out.push(line);
+    }
+    return out;
+}
 export function renderDiffPretty(d, opts) {
     const lines = [];
     const sign = d.delta >= 0 ? "+" : "";
@@ -232,3 +403,51 @@ export function renderDiffPretty(d, opts) {
     }
     return lines.join("\n");
 }
+/**
+ * What moved between two `check` runs.
+ *
+ * The three token columns stay in three rows on purpose. Summing them gives a
+ * single percentage that is arithmetically true and describes none of the
+ * three costs, because metadata is carried permanently while referenced files
+ * load only on demand, and in practice almost all movement lands in the column
+ * that costs the least to hold. A dominant mover is printed beside its total
+ * for the same reason: when one subject is most of a change, the total is
+ * about that subject rather than about the population.
+ */
+export function renderCheckDiffPretty(d) {
+    const lines = [];
+    lines.push(paint(pc.dim, `efaimo v${VERSION}`));
+    const rules = d.rulesVersions.before ?? "?";
+    lines.push(`diff check  ${paint(pc.bold, `${d.paired} paired`)}${d.added.length ? `, ${d.added.length} added` : ""}${d.removed.length ? `, ${d.removed.length} removed` : ""}`);
+    lines.push(paint(pc.dim, d.rulesDrift
+        ? `efaimo ${d.versions.before} -> ${d.versions.after}, rules ${d.rulesVersions.before} -> ${d.rulesVersions.after}  DRIFTED`
+        : `efaimo ${d.versions.before} -> ${d.versions.after}, rules ${rules} on both sides`));
+    lines.push("");
+    const sign = (n) => (n > 0 ? `+${n.toLocaleString("en-US")}` : n.toLocaleString("en-US"));
+    const pct = (n) => `${n > 0 ? "+" : ""}${n.toFixed(1)}%`;
+    lines.push(paint(pc.bold, "grades"));
+    if (d.rulesDrift) {
+        lines.push(`  ${paint(pc.yellow, "unattributable")}: the ruleset changed between the runs, so a moved grade may be the ruler`);
+    }
+    const g = (m) => `  ${m.name.padEnd(34)} ${m.before.letter} (${m.before.score}) -> ${m.after.letter} (${m.after.score})`;
+    for (const m of d.improved)
+        lines.push(paint(pc.green, g(m)));
+    for (const m of d.worsened)
+        lines.push(paint(pc.red, g(m)));
+    lines.push(paint(pc.dim, `  improved ${d.improved.length}   worsened ${d.worsened.length}   held ${d.held}   findings ${d.findingCounts.before} -> ${d.findingCounts.after}`));
+    lines.push("");
+    if (d.costs.length) {
+        lines.push(paint(pc.bold, "token cost, by when it loads"));
+        for (const c of d.costs) {
+            const color = c.delta > 0 ? pc.yellow : c.delta < 0 ? pc.green : pc.dim;
+            lines.push(`  ${c.column.padEnd(11)} ${paint(pc.dim, `(${c.when})`.padEnd(20))} ${String(c.before.toLocaleString("en-US")).padStart(9)} -> ${String(c.after.toLocaleString("en-US")).padStart(9)}  ${paint(color, pct(c.pct))}`);
+            if (c.dominatedBy) {
+                lines.push(paint(pc.dim, `              ${c.dominatedBy.name} is ${c.dominatedBy.shareOfMovement.toFixed(1)}% of that movement (${sign(c.dominatedBy.delta)}); the total describes it, not the rest`));
+            }
+        }
+        lines.push("");
+    }
+    for (const n of d.notes)
+        lines.push(paint(pc.dim, `  ${n}`));
+    return lines.join("\n");
+}

package/dist/rules/find/index.d.ts

@@ -0,0 +1,4 @@
+import type { FindRule } from "../../core/types.js";
+export declare const FIND_RULES: FindRule[];
+/** E141-E146 are findability rules: reported by `efaimo find`, never part of a `check` grade. */
+export declare function isFindabilityRuleId(id: string): boolean;

package/dist/rules/find/index.js

@@ -0,0 +1,262 @@
+/**
+ * Findability rules, E141-E146.
+ *
+ * A separate family with its own command on purpose. They are not readiness
+ * (which asks whether a 2026-07-28 client can talk to this server) and not
+ * quality (which asks what a model experiences once a tool is in front of it).
+ * They ask a third thing: under deferred loading, does anything ever put this
+ * tool in front of the model at all.
+ *
+ * E141 is the one that is not a heuristic. The others read a simulation and
+ * are worth less; they are kept because the simulation is the only thing here
+ * that models the real mechanism, and because the cases they do catch (a tool
+ * with no description, two tools with the same one) are worth catching.
+ *
+ * None of them feeds `check`'s grade, and `find` produces no grade of its own.
+ * ADR-030 has the reasoning.
+ */
+function cap(items, n) {
+    return { shown: items.slice(0, n), more: Math.max(0, items.length - n) };
+}
+/**
+ * A target-supplied value going into a rule message or detail.
+ *
+ * The reporters strip control characters but keep newlines, because a detail
+ * block is legitimately multi-line. That makes a newline inside a tool name a
+ * way for the audited server to add its own line to the auditor's output. The
+ * values these rules interpolate - names, terms - are all single-line by
+ * nature, so they are flattened here, at the point where a multi-line region
+ * is built out of them.
+ */
+function one(s) {
+    return s.replace(/[\r\n]+/g, " ");
+}
+const list = (xs) => xs.map(one).join(", ");
+const e141 = {
+    id: "E141",
+    title: "tool owns no exclusive vocabulary",
+    surface: "find",
+    check({ find }) {
+        const shared = find.perTool.filter((t) => t.ownTermCount === 0);
+        const { shown, more } = cap(shared, 5);
+        const findings = shown.map((t) => ({
+            ruleId: "E141",
+            severity: "warn",
+            title: "tool owns no exclusive vocabulary",
+            // Stated as what it is: an existence claim about queries, not a
+            // prediction about one search. Every term this tool has appears on some
+            // other tool, so there is no query that matches it alone. Whether it
+            // still wins a shared query depends on term frequencies, which is a much
+            // weaker thing to rely on than owning a word.
+            message: `tool "${one(t.name)}" has no term that no other tool has, so no search can return it without also returning a competitor`,
+            target: t.name,
+            // "also appears on", not "covered by": no single tool on this list
+            // necessarily carries the whole vocabulary. They are the tools with the
+            // most overlap, which is where to look first when writing the fix.
+            detail: t.sharedWith.length ? `every word it has also appears on: ${list(t.sharedWith)} (most overlap first)` : undefined,
+            fixHint: "put something in the description that only this tool does: the object it acts on, the format it returns, the case it is for",
+        }));
+        if (more) {
+            findings.push({
+                ruleId: "E141",
+                severity: "warn",
+                title: "tool owns no exclusive vocabulary",
+                message: `...and ${more} more tools that share every one of their terms with another tool`,
+            });
+        }
+        return findings;
+    },
+};
+const e142 = {
+    id: "E142",
+    title: "a search for the tool's own description does not return it",
+    surface: "find",
+    check({ find }) {
+        const findings = [];
+        const unsearchable = find.perTool.filter((t) => t.rank === undefined);
+        for (const t of cap(unsearchable, 5).shown) {
+            findings.push({
+                ruleId: "E142",
+                severity: "warn",
+                title: "a search for the tool's own description does not return it",
+                message: `tool "${one(t.name)}" offers no words to search for: its description is empty or made only of function words, so nothing but the exact name reaches it`,
+                target: t.name,
+                fixHint: "write a description containing the words someone would use to describe the task this tool does",
+            });
+        }
+        const missed = find.perTool.filter((t) => t.rank !== undefined && !t.reachable);
+        for (const t of cap(missed, 5).shown) {
+            findings.push({
+                ruleId: "E142",
+                severity: "warn",
+                title: "a search for the tool's own description does not return it",
+                message: `tool "${one(t.name)}" ranks ${t.rank} of ${find.toolCount} for a search built from its own description (${list(t.query)}), outside a result window of ${find.method.topK}`,
+                target: t.name,
+                detail: t.outrankedBy.length ? `outranked by: ${list(t.outrankedBy)}` : undefined,
+                fixHint: "make the description carry a term the other tools do not share",
+            });
+        }
+        const more = cap(unsearchable, 5).more + cap(missed, 5).more;
+        if (more) {
+            findings.push({
+                ruleId: "E142",
+                severity: "warn",
+                title: "a search for the tool's own description does not return it",
+                message: `...and ${more} more tools a search for their own description does not return`,
+            });
+        }
+        return findings;
+    },
+};
+const e143 = {
+    id: "E143",
+    title: "tools are indistinguishable to a search",
+    surface: "find",
+    check({ find }) {
+        // Report each pair once. A ties with B is the same fact as B ties with A,
+        // and printing both halves doubles the finding count, which would double
+        // the apparent size of the problem.
+        const seen = new Set();
+        const findings = [];
+        for (const t of find.perTool) {
+            for (const other of t.tiedWith) {
+                const key = t.name < other ? `${one(t.name)} ${one(other)}` : `${one(other)} ${one(t.name)}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                if (findings.length >= 5)
+                    continue;
+                findings.push({
+                    ruleId: "E143",
+                    severity: "warn",
+                    title: "tools are indistinguishable to a search",
+                    message: `tools "${one(t.name)}" and "${one(other)}" score identically for a search built from "${one(t.name)}"'s description (${list(t.query)}); only the alphabetical tie-break separates them`,
+                    target: t.name,
+                    fixHint: "give each description a term the other does not have, or merge the tools",
+                });
+            }
+        }
+        // The true pair count comes from tiedWithCount, not from the names above.
+        // `tiedWith` is capped at three per tool for display, so counting the
+        // pairs it yields reported 30 for a catalog whose real answer was 66: a
+        // count of what survived a display cap, printed as a count of the problem.
+        // Each pair is counted from both ends, hence the halving.
+        const totalPairs = Math.round(find.perTool.reduce((n, t) => n + t.tiedWithCount, 0) / 2);
+        if (totalPairs > findings.length) {
+            findings.push({
+                ruleId: "E143",
+                severity: "warn",
+                title: "tools are indistinguishable to a search",
+                message: `...and ${totalPairs - findings.length} more indistinguishable pairs (${totalPairs} in total)`,
+            });
+        }
+        return findings;
+    },
+};
+const e146 = {
+    id: "E146",
+    title: "the only word a tool owns is its own name",
+    surface: "find",
+    check({ find }) {
+        // Names ARE searchable, so this tool is findable in principle and E141
+        // correctly does not fire. It is not findable by anyone describing a task,
+        // which is the situation deferred loading creates, so the two cases are
+        // reported separately rather than merged into one number.
+        const nameOnly = find.perTool.filter((t) => t.ownTermCount > 0 && t.ownOutsideNameCount === 0);
+        const { shown, more } = cap(nameOnly, 5);
+        const findings = shown.map((t) => ({
+            ruleId: "E146",
+            severity: "info",
+            title: "the only word a tool owns is its own name",
+            message: t.ownTermCount === 1
+                ? `tool "${one(t.name)}" owns one term and it comes from its own name; nothing in its description is unique, so only someone who already knows the name can single it out`
+                : `tool "${one(t.name)}" owns ${t.ownTermCount} terms and every one of them comes from its own name; nothing in its description is unique, so only someone who already knows the name can single it out`,
+            target: t.name,
+            fixHint: "put a word in the description that no other tool's description uses",
+        }));
+        if (more) {
+            findings.push({
+                ruleId: "E146",
+                severity: "info",
+                title: "the only word a tool owns is its own name",
+                message: `...and ${more} more tools whose only exclusive words are their own name`,
+            });
+        }
+        return findings;
+    },
+};
+const e144 = {
+    id: "E144",
+    title: "tool name carries no domain term",
+    surface: "find",
+    check({ find }) {
+        // All-generic AND no name token of its own.
+        //
+        // "Generic" alone was too weak: the fixture server's `add` is a perfectly
+        // descriptive name for an arithmetic tool, and the rule told its author to
+        // "put the subject in the name" with no usable suggestion. What separates
+        // `add` from `run` is not the word list, it is whether the word belongs to
+        // this tool alone in this catalog. `ownTermCount > ownOutsideNameCount`
+        // means at least one exclusive term came from the name, which is exactly
+        // the case where a broad pattern search does reach it.
+        const generic = find.perTool.filter((t) => t.genericName && t.ownTermCount === t.ownOutsideNameCount);
+        const { shown, more } = cap(generic, 5);
+        const findings = shown.map((t) => ({
+            ruleId: "E144",
+            severity: "info",
+            title: "tool name carries no domain term",
+            message: `tool "${one(t.name)}" is named only with generic words, so a broad pattern search (Claude writes things like ".*weather.*") can reach it only through its description`,
+            target: t.name,
+            fixHint: "put the subject in the name: what does it act on",
+        }));
+        if (more) {
+            findings.push({
+                ruleId: "E144",
+                severity: "info",
+                title: "tool name carries no domain term",
+                message: `...and ${more} more tools named only with generic words`,
+            });
+        }
+        return findings;
+    },
+};
+const e145 = {
+    id: "E145",
+    title: "deferred catalog with tools a search cannot single out",
+    surface: "find",
+    check({ find }) {
+        if (!find.deferRecommended)
+            return [];
+        // The union, not the sum. These two sets overlap heavily - a tool with no
+        // exclusive vocabulary is often also one the probe misses - and adding
+        // them read as twice as many problems as there are. On a 15-tool server
+        // this line once claimed 24.
+        const affected = new Set();
+        for (const t of find.perTool) {
+            if (t.ownTermCount === 0 || !t.reachable)
+                affected.add(t.name);
+        }
+        if (!affected.size)
+            return [];
+        return [
+            {
+                ruleId: "E145",
+                severity: "warn",
+                title: "deferred catalog with tools a search cannot single out",
+                // The reason comes from the analysis, not from a repeat of one
+                // threshold. Anthropic lists several conditions; hardcoding the token
+                // one here printed "~3500 tokens, past the ~10.0k" on a catalog that
+                // qualified on tool count instead.
+                message: `tool search is recommended for this catalog (${find.deferBecause.map(one).join("; ")}), ` +
+                    `and ${affected.size} of ${find.toolCount} tool${affected.size === 1 ? " cannot" : "s cannot"} be singled out by a search. ` +
+                    `Once this catalog is deferred, a tool nothing surfaces costs nothing and does nothing.`,
+                fixHint: "fix the descriptions above, or split the server so fewer tools compete in one catalog",
+            },
+        ];
+    },
+};
+export const FIND_RULES = [e141, e142, e143, e144, e145, e146];
+/** E141-E146 are findability rules: reported by `efaimo find`, never part of a `check` grade. */
+export function isFindabilityRuleId(id) {
+    return /^E14\d$/.test(id);
+}

package/dist/rules/skill/index.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { scanTextForInjection } from "../injection.js";
+import { tokenize, QUERY_STOPWORDS } from "../../find/tokenize.js";
 import { formatTokens } from "../../util/misc.js";
 const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const STANDARD_FIELDS = new Set(["name", "description", "license", "compatibility", "metadata", "allowed-tools"]);
@@ -77,6 +78,14 @@ const s101 = {
         return findings;
     },
 };
+// Grounded on the 38 public skills in research/skills-index/manifest.json,
+// measured 2026-09-03. The shortest real description there is 68 characters
+// (`template-skill`) and the fewest content terms any of them carries is 4,
+// also `template-skill`. Both floors sit below every real description in that
+// corpus and above the filler this rule exists to catch, and both are far
+// under the spec's 1024-character ceiling.
+const S102_MIN_CHARS = 40;
+const S102_MIN_CONTENT_TERMS = 4;
 const s102 = {
     id: "S102",
     title: "weak trigger description",
@@ -87,7 +96,19 @@ const s102 = {
             return []; // S101 already errors
         const findings = [];
         const label = skillLabel(skill);
-        if (desc.length < 20) {
+        // The content this description carries once the words every description
+        // contains are removed. A length floor alone was not enough: until
+        // 2026-09-03 this rule read `desc.length < 20`, then asked only whether one
+        // of four trigger words appeared anywhere, so "Useful for various tasks."
+        // scored a clean 100 because "for" happens to sit inside "for various
+        // tasks". It tested for the presence of a trigger WORD rather than for the
+        // presence of a trigger, which is a keyword check wearing the costume of a
+        // semantic one. Counting what survives the stopword list is the same
+        // measurement `find` makes on tool catalogs: a description with almost no
+        // distinguishing content cannot be matched to a task by any host, whatever
+        // words it happens to include.
+        const contentTerms = new Set(tokenize(desc).filter((w) => !QUERY_STOPWORDS.has(w)));
+        if (desc.length < S102_MIN_CHARS) {
             findings.push({
                 ruleId: "S102",
                 severity: "warn",
@@ -97,6 +118,16 @@ const s102 = {
                 fixHint: "state what the skill does AND when to use it, with concrete trigger words",
             });
         }
+        else if (contentTerms.size < S102_MIN_CONTENT_TERMS) {
+            findings.push({
+                ruleId: "S102",
+                severity: "warn",
+                title: "weak trigger description",
+                message: `description carries only ${contentTerms.size} distinct content ${contentTerms.size === 1 ? "term" : "terms"} once common words are removed; there is nothing here for a host to match a task against`,
+                target: label,
+                fixHint: "name the situations, artifacts and words a user would actually type",
+            });
+        }
         else if (!/\buse\b|\bwhen\b|\bfor\b|\bhelps?\b/i.test(desc)) {
             findings.push({
                 ruleId: "S102",