efaimo 0.1.1 → 0.2.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,12 +124,14 @@ 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)}%)`,
         `  delta          ${paint(pc.bold, `${sign}${r.deltaPoints} points`)}   ${paint(verdictColor, r.verdict)}`,
-        `  significance   p = ${r.p < 0.0001 ? "<0.0001" : r.p.toFixed(4)}   95% CI ${r.ci.lo >= 0 ? "+" : ""}${r.ci.lo} to ${r.ci.hi >= 0 ? "+" : ""}${r.ci.hi} points`,
+        Number.isFinite(r.ci.lo)
+            ? `  significance   p = ${r.p < 0.0001 ? "<0.0001" : r.p.toFixed(4)}   95% CI ${r.ci.lo >= 0 ? "+" : ""}${r.ci.lo} to ${r.ci.hi >= 0 ? "+" : ""}${r.ci.hi} points`
+            : `  significance   not computable: an arm produced no scoreable trial`,
         "",
     ];
     for (const n of r.notes)
@@ -128,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)
@@ -168,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("");
@@ -181,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)`));
@@ -203,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)`);
@@ -212,6 +240,145 @@ 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)));
+    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}]`);
+        lines.push(`  ${count}  ${cell(t.name).padEnd(nameW)}  ${tail}${probe}`);
+    }
+    // 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 ? "+" : "";

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/injection.d.ts

@@ -1,8 +1,7 @@
-import type { Finding, Severity } from "../core/types.js";
+import type { Finding } from "../core/types.js";
 interface InjectionPattern {
     key: string;
     re: RegExp;
-    severity: Severity;
     label: string;
 }
 /**

package/dist/rules/injection.js

@@ -9,19 +9,16 @@ export const INJECTION_PATTERNS = [
     {
         key: "override-instructions",
         re: /ignore\s+(?:all\s+|any\s+)?(?:previous|prior|earlier|above)\s+(?:instructions|messages|rules|prompts)/i,
-        severity: "error",
         label: "attempts to override prior instructions",
     },
     {
         key: "hide-from-user",
         re: /do\s+not\s+(?:tell|reveal|mention|inform|show|disclose)\b[\s\S]{0,40}\b(?:user|human|operator)/i,
-        severity: "error",
         label: "instructs the agent to hide behavior from the user",
     },
     {
         key: "act-without-consent",
         re: /without\s+(?:telling|asking|notifying|informing)\s+(?:the\s+)?(?:user|human)/i,
-        severity: "error",
         label: "instructs the agent to act without user consent",
     },
     {
@@ -29,51 +26,43 @@ export const INJECTION_PATTERNS = [
         // "post" and "token" dropped: they match API documentation ("Token counting
         // POST /v1/...") far more than exfiltration.
         re: /\b(?:api[_-]?key|secret|password|credential)s?\b[\s\S]{0,40}\b(?:send|forward|exfiltrat|upload|leak|transmit|include\s+it)\b/i,
-        severity: "error",
         label: "references sending credentials or secrets somewhere",
     },
     {
         key: "sensitive-file-read",
         re: /\b(?:read|open|cat|print|upload)\b[\s\S]{0,40}(?:\.env\b|\.ssh\b|id_rsa|credentials|\.aws\b|\.npmrc\b)/i,
-        severity: "error",
         label: "references reading sensitive local files",
     },
     {
         key: "disable-safety",
         re: /\b(?:disable|bypass|ignore|remove)\s+(?:safety|guardrails?|filters?|restrictions?|policy|policies)\b/i,
-        severity: "error",
         label: "asks to bypass safety or policy",
     },
     {
         key: "cross-tool-steering",
         re: /before\s+(?:using|calling|running)\b[^.?!]{0,40}?\btools?\b[\s,]{1,4}(?:always\s+|first\s+|please\s+)?(?:call|run|use|fetch|invoke)\b/i,
-        severity: "warn",
         label: "steers the agent to call another tool first (cross-tool steering)",
     },
     {
         key: "templated-exfil-url",
         // Bounded runs (no adjacent unbounded same-class quantifiers) to avoid ReDoS.
         re: /https?:\/\/[^\s"'<>]{1,150}[?&][^\s"'<>]{0,150}(?:\$\{[^}]{1,60}\}|\{\{[^}]{1,60}\}\}|\{[^}]{1,60}\})/,
-        severity: "warn",
         label: "URL with a templated query parameter (possible exfiltration channel)",
     },
     {
         key: "zero-width-chars",
         // eslint-disable-next-line no-control-regex
         re: /[​‌‍⁠]/,
-        severity: "warn",
         label: "zero-width or invisible characters present",
     },
     {
         key: "hidden-html-comment",
         re: /<!--[^>]{0,240}\b(?:must|always|never|call|run|fetch|send|ignore)\b[^>]{0,240}-->/i,
-        severity: "warn",
         label: "HTML comment containing imperative instructions (hidden from rendered view)",
     },
     {
         key: "persona-override",
         re: /\byou\s+are\s+now\b|\bpretend\s+to\s+be\b|\bnew\s+system\s+prompt\b/i,
-        severity: "warn",
         label: "persona or system-prompt override language",
     },
 ];

package/dist/rules/mcp/index.js

@@ -166,6 +166,23 @@ const e105 = {
                 },
             ];
         }
+        if (bare.kind === "exit") {
+            // A crash on the bare request is not a timeout and not a clean answer: the
+            // server did not serve a stateless tools/list, so a 2026-07-28 client
+            // cannot talk to it. Left unhandled, this outcome produced NO finding, so
+            // a crashing server looked one item MORE migrated than one that answers
+            // with a not-initialized error.
+            return [
+                {
+                    ruleId: "E105",
+                    severity: "warn",
+                    title: "requires the removed initialize handshake",
+                    message: `the server process exited on a bare stateless tools/list (${bare.errorMessage ?? "no reply"}), so it does not answer requests without a prior initialize`,
+                    detail: `${SPEC} removes initialize and sessions; a server that exits on a bare request cannot serve a ${SPEC} client. A server that answers, even with an error, is judged by E106/E107/E118 instead.`,
+                    fixHint: "upgrade to a 2.x SDK, or answer requests without a prior initialize instead of exiting",
+                },
+            ];
+        }
         if (bare.kind === "timeout") {
             return [
                 {
@@ -526,7 +543,10 @@ const e124 = {
             }
         }
         if (totalParams > 5 && undocumented / totalParams > 0.3) {
-            findings.push({
+            // Prepend, not append: capList keeps the first 5, and on the worst schemas
+            // (5+ oversized enums) an appended summary was exactly the line that got
+            // dropped. The aggregate is the headline, so it leads.
+            findings.unshift({
                 ruleId: "E124",
                 severity: "warn",
                 title: "schema issues",