efaimo 0.1.0 → 0.1.1

package/dist/testing/stats.js

@@ -0,0 +1,91 @@
+// The statistics behind an `efaimo test` verdict.
+//
+// The verdict used to be a bare threshold on the difference in pass rates:
+// >= +15 points "helps", <= -15 "hurts", exit code 1 on "hurts". With the
+// default 5 trials per arm, 5/5 against 4/5 is +20 points and would have been
+// reported as "helps" with a two-sided Fisher p of 1.0000 - the least
+// significant result the test can produce, labelled as a finding. At 8 trials
+// per arm the 95% interval on a difference of proportions is roughly +-49
+// points wide, so the whole +-15 band sits inside the noise for every trial
+// count the tool supports below about 25 per arm.
+//
+// A tool whose argument is that people publish numbers they cannot support
+// should not do that itself. So the verdict is now gated on a p-value, the
+// interval is reported, and both are printed rather than hidden.
+//
+// Fisher's exact test, not chi-squared: the counts here are single digits, and
+// chi-squared's approximation is not trustworthy at that size.
+/** ln(n!) via lgamma, so the 2x2 table math stays exact enough at small n. */
+function lnFactorial(n) {
+    let s = 0;
+    for (let i = 2; i <= n; i++)
+        s += Math.log(i);
+    return s;
+}
+/** Probability of exactly this 2x2 table under the hypergeometric null. */
+function lnHypergeom(a, b, c, d) {
+    const n = a + b + c + d;
+    return (lnFactorial(a + b) + lnFactorial(c + d) + lnFactorial(a + c) + lnFactorial(b + d) -
+        lnFactorial(n) - lnFactorial(a) - lnFactorial(b) - lnFactorial(c) - lnFactorial(d));
+}
+/**
+ * Two-sided Fisher exact test on
+ *   [withPass, withFail]
+ *   [withoutPass, withoutFail]
+ *
+ * Sums the probability of every table at least as extreme as the observed one,
+ * which is the standard two-sided construction and needs no normal
+ * approximation.
+ */
+export function fisherExactTwoSided(withPass, withTrials, withoutPass, withoutTrials) {
+    const a = withPass, b = withTrials - withPass;
+    const c = withoutPass, d = withoutTrials - withoutPass;
+    if (withTrials <= 0 || withoutTrials <= 0)
+        return 1;
+    const obs = lnHypergeom(a, b, c, d);
+    const rowTop = a + b, rowBot = c + d, colPass = a + c;
+    const lo = Math.max(0, colPass - rowBot);
+    const hi = Math.min(rowTop, colPass);
+    // A tiny epsilon so floating point does not drop the observed table itself.
+    const EPS = 1e-9;
+    let p = 0;
+    for (let x = lo; x <= hi; x++) {
+        const l = lnHypergeom(x, rowTop - x, colPass - x, rowBot - (colPass - x));
+        if (l <= obs + EPS)
+            p += Math.exp(l);
+    }
+    return Math.min(1, p);
+}
+/**
+ * Wilson score interval for one proportion. Chosen over the normal-approximation
+ * interval because that one produces a zero-width interval at 0/n and n/n,
+ * which is exactly where these runs land (8/8 and 0/8 both occur in the two
+ * committed example runs).
+ */
+export function wilson(passes, trials, z = 1.96) {
+    if (trials <= 0)
+        return { lo: 0, hi: 1 };
+    const p = passes / trials;
+    const z2 = z * z;
+    const denom = 1 + z2 / trials;
+    const centre = p + z2 / (2 * trials);
+    const half = z * Math.sqrt((p * (1 - p)) / trials + z2 / (4 * trials * trials));
+    return { lo: Math.max(0, (centre - half) / denom), hi: Math.min(1, (centre + half) / denom) };
+}
+/**
+ * Interval on the DIFFERENCE of two proportions, in percentage points, by the
+ * Newcombe method: combine each arm's Wilson interval. Reported so a reader can
+ * see how wide the uncertainty actually is instead of inferring it from a
+ * point estimate.
+ */
+export function deltaInterval(withPass, withTrials, withoutPass, withoutTrials) {
+    const w = wilson(withPass, withTrials);
+    const o = wilson(withoutPass, withoutTrials);
+    const p1 = withPass / withTrials, p2 = withoutPass / withoutTrials;
+    const d = p1 - p2;
+    const lo = d - Math.sqrt((p1 - w.lo) ** 2 + (o.hi - p2) ** 2);
+    const hi = d + Math.sqrt((w.hi - p1) ** 2 + (p2 - o.lo) ** 2);
+    return { lo: Math.round(Math.max(-1, lo) * 1000) / 10, hi: Math.round(Math.min(1, hi) * 1000) / 10 };
+}
+/** The smallest per-arm trial count at which a total separation (n/n vs 0/n) reaches p < 0.05. */
+export const MIN_TRIALS_FOR_SIGNIFICANCE = 4;

package/dist/util/dotenv.d.ts

@@ -9,4 +9,12 @@
  * secrets are not forwarded to spawned MCP servers: minimalChildEnv() passes an
  * allowlist that excludes API keys.
  */
-export declare function loadDotEnv(dir?: string): string[];
+/**
+ * The only keys this loader may set. It used to set ANY key found in a .env in
+ * the CURRENT DIRECTORY, which means a repository you cloned could inject
+ * NODE_TLS_REJECT_UNAUTHORIZED=0 and silently disable certificate verification
+ * for every later HTTPS call, including the ones carrying your API key. The
+ * file header already said only two keys were wanted; this enforces it.
+ */
+export declare const ALLOWED: Set<string>;
+export declare function loadDotEnv(dir?: string, allowed?: ReadonlySet<string>): string[];

package/dist/util/dotenv.js

@@ -11,7 +11,15 @@ import { resolve } from "node:path";
  * secrets are not forwarded to spawned MCP servers: minimalChildEnv() passes an
  * allowlist that excludes API keys.
  */
-export function loadDotEnv(dir = process.cwd()) {
+/**
+ * The only keys this loader may set. It used to set ANY key found in a .env in
+ * the CURRENT DIRECTORY, which means a repository you cloned could inject
+ * NODE_TLS_REJECT_UNAUTHORIZED=0 and silently disable certificate verification
+ * for every later HTTPS call, including the ones carrying your API key. The
+ * file header already said only two keys were wanted; this enforces it.
+ */
+export const ALLOWED = new Set(["ANTHROPIC_API_KEY", "OPENAI_API_KEY"]);
+export function loadDotEnv(dir = process.cwd(), allowed = ALLOWED) {
     let text;
     try {
         text = readFileSync(resolve(dir, ".env"), "utf8");
@@ -32,6 +40,8 @@ export function loadDotEnv(dir = process.cwd()) {
         const key = line.slice(0, eq).trim();
         if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
             continue;
+        if (!allowed.has(key))
+            continue;
         if (process.env[key] !== undefined)
             continue;
         let val = line.slice(eq + 1).trim();

package/dist/util/safeText.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Strip terminal control characters from text that originated outside efaimo.
+ * Tab and newline survive because layout depends on them; everything else that
+ * can move a cursor, clear a line, or address the terminal is removed.
+ */
+export declare function safeText(s: string): string;
+/** Same, for a value that may be undefined. */
+export declare function safeTextOpt(s: string | undefined): string | undefined;

package/dist/util/safeText.js

@@ -0,0 +1,48 @@
+// Text that came from the thing being audited must not be able to drive the
+// terminal it is reported in.
+//
+// Tool names, titles, descriptions, server instructions, stderr tails and
+// repo-scan excerpts all originate with the target. They were interpolated
+// into stdout raw, so a hostile server could emit ESC[1A ESC[2K inside a tool
+// name and rewrite the grade line printed above its own finding: the auditor
+// reads "grade A (100), 0 errors" while the finding that contradicts it is
+// erased. OSC 8 forges a hyperlink; OSC 52 writes the reader's clipboard.
+// `--no-color` did not help, because that only suppresses the colours efaimo
+// itself adds.
+//
+// This matters out of proportion to its severity. An auditing tool whose
+// verdict can be rewritten by the thing it audits has a credibility problem
+// before it has a security one, and the HTTP transport is exactly where a user
+// expects no code execution and therefore no consequences.
+//
+// Applied at the RENDER boundary, never on ingestion: escape bytes in a
+// description are real bytes that a model would receive and really do cost
+// tokens, so `weigh` has to keep counting them. What must not happen is that
+// they reach a terminal as control codes.
+//
+// JSON output needs no pass here: JSON.stringify already encodes control
+// characters as  escape sequences, which are inert text.
+// C0 except tab and newline, DEL, and the C1 block. C1 is included because a
+// lone 0x9B is CSI in a terminal that decodes single-byte C1, which is the
+// same attack without an ESC byte to grep for.
+// Built from code points rather than written as literals so this file does not
+// itself contain the bytes it exists to remove; the same reason gates.mjs next
+// door builds its dash class with String.fromCharCode.
+const CONTROLS = new RegExp("[" +
+    "\\u0000-\\u0008" + // C0 up to backspace (tab 0x09 and newline 0x0A kept)
+    "\\u000B-\\u001F" + // vertical tab through unit separator, ESC included
+    "\\u007F" + // DEL
+    "\\u0080-\\u009F" + // C1, single-byte CSI/OSC among them
+    "]", "g");
+/**
+ * Strip terminal control characters from text that originated outside efaimo.
+ * Tab and newline survive because layout depends on them; everything else that
+ * can move a cursor, clear a line, or address the terminal is removed.
+ */
+export function safeText(s) {
+    return s.replace(CONTROLS, "");
+}
+/** Same, for a value that may be undefined. */
+export function safeTextOpt(s) {
+    return s === undefined ? undefined : safeText(s);
+}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Kept in sync with package.json by test/meta.test.ts. */
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.1.1";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Kept in sync with package.json by test/meta.test.ts. */
-export const VERSION = "0.1.0";
+export const VERSION = "0.1.1";

package/dist/weigh/weigh.js

@@ -69,7 +69,9 @@ export async function weighSkills(set) {
         let refFileTokens = 0;
         let refFileCount = 0;
         for (const ref of skill.referencedPaths) {
-            if (!ref.exists || isBinaryPath(ref.resolved))
+            // Never read outside the skill root. S106 warns about these, but only
+            // after weigh had already opened the file and counted its tokens.
+            if (ref.escapes || !ref.exists || isBinaryPath(ref.resolved))
                 continue;
             const text = readTextSafe(ref.resolved);
             if (text === undefined)

package/dist/weigh/window.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The context window a token count is reported as a share of.
+ *
+ * There is no single correct denominator: it is a property of the model the
+ * host happens to be running, not of the server being measured. Every current
+ * frontier Claude model (Fable 5, Opus 5, Opus 4.8/4.7/4.6, Sonnet 5, Sonnet
+ * 4.6) is 1M; Haiku 4.5 is 200K, as are many non-Claude and local models, where the
+ * same tool definitions cost 5x the share shown here.
+ *
+ * So the share is always printed with the window it was computed against, and
+ * `--window` lets the caller name their own. The absolute token count is the
+ * number efaimo actually stands behind; this is a readability aid on top of it.
+ *
+ * Note that no rule grades on this share -- E128's thresholds are absolute
+ * token counts, so changing the window never moves a grade.
+ */
+export declare const DEFAULT_CONTEXT_WINDOW = 1000000;
+export declare function setContextWindow(tokens: number): void;
+export declare function getContextWindow(): number;
+/** "1M", "200k", "128k", "4,096" -- how the window is named in output. */
+export declare function formatWindow(tokens?: number): string;
+/**
+ * "~0.1% of a 1M window" -- always names the denominator, so the reader is
+ * never left guessing which model it assumed.
+ */
+export declare function formatWindowShare(tokens: number, window?: number): string;

package/dist/weigh/window.js

@@ -0,0 +1,44 @@
+/**
+ * The context window a token count is reported as a share of.
+ *
+ * There is no single correct denominator: it is a property of the model the
+ * host happens to be running, not of the server being measured. Every current
+ * frontier Claude model (Fable 5, Opus 5, Opus 4.8/4.7/4.6, Sonnet 5, Sonnet
+ * 4.6) is 1M; Haiku 4.5 is 200K, as are many non-Claude and local models, where the
+ * same tool definitions cost 5x the share shown here.
+ *
+ * So the share is always printed with the window it was computed against, and
+ * `--window` lets the caller name their own. The absolute token count is the
+ * number efaimo actually stands behind; this is a readability aid on top of it.
+ *
+ * Note that no rule grades on this share -- E128's thresholds are absolute
+ * token counts, so changing the window never moves a grade.
+ */
+export const DEFAULT_CONTEXT_WINDOW = 1_000_000;
+let contextWindow = DEFAULT_CONTEXT_WINDOW;
+export function setContextWindow(tokens) {
+    if (!Number.isFinite(tokens) || tokens <= 0) {
+        throw new Error(`--window must be a positive number of tokens, got ${tokens}`);
+    }
+    contextWindow = tokens;
+}
+export function getContextWindow() {
+    return contextWindow;
+}
+/** "1M", "200k", "128k", "4,096" -- how the window is named in output. */
+export function formatWindow(tokens = contextWindow) {
+    if (tokens >= 1_000_000 && tokens % 1_000_000 === 0)
+        return `${tokens / 1_000_000}M`;
+    if (tokens >= 1_000 && tokens % 1_000 === 0)
+        return `${tokens / 1_000}k`;
+    return tokens.toLocaleString("en-US");
+}
+/**
+ * "~0.1% of a 1M window" -- always names the denominator, so the reader is
+ * never left guessing which model it assumed.
+ */
+export function formatWindowShare(tokens, window = contextWindow) {
+    const pct = (tokens / window) * 100;
+    const shown = pct < 0.1 && pct > 0 ? "<0.1" : pct.toFixed(1);
+    return `~${shown}% of a ${formatWindow(window)} window`;
+}

package/docs/METHODOLOGY.md

@@ -48,6 +48,29 @@ wrapped total. For the other two serializations no wrapper exists, and summing
 per-tool counts may differ from the total by a few tokens, because a tokenizer
 can merge characters across element boundaries when tools are concatenated.
 
+## The context window we compare against
+
+Alongside the absolute token count, efaimo prints the share of a context window
+it represents. There is no correct denominator for that: the window belongs to
+whichever model the host is running, not to the server being measured. Current
+frontier Claude models (Fable 5, Opus 5, Opus 4.8/4.7/4.6, Sonnet 5, Sonnet
+4.6) are **1M**, so that is the default. Haiku 4.5 is 200k, as are many
+non-Claude and local models, where identical tool definitions cost five times
+the share.
+
+Because the denominator is an assumption rather than a measurement, efaimo
+always names it in the output ("~4.3% of a 1M window") and lets you set your
+own with `--window` (since 0.1.1; 0.1.0 hardcoded 200k and printed `of a 200k window`):
+
+```bash
+npx efaimo weigh "npx -y my-server" --window 200000
+```
+
+**No rule grades on this share.** The cost thresholds (E127, E128) are absolute
+token counts, so changing `--window` changes what you read and never changes a
+grade. The absolute number is the one efaimo stands behind; the share is a
+readability aid on top of it.
+
 ## Skills
 
 For Agent Skills efaimo reports the three progressive-disclosure levels defined by
@@ -81,3 +104,50 @@ prompt-cache hits and reproducibility.
 efaimo estimates the **cost of tool/skill definitions sitting in context**. It does
 not measure per-call argument/result tokens, host framing, or model-side reasoning.
 For end-to-end token accounting, instrument your agent run directly.
+
+## `efaimo test`: what the verdict means
+
+The verdict is a significance test, not a threshold on the size of the gap.
+
+Each arm runs N trials of the same task, one with the skill in the system
+prompt and one without, and an LLM judge returns PASS or FAIL per trial. The
+two arms form a 2x2 table, and the report carries:
+
+- a **two-sided Fisher exact p**. Fisher rather than chi-squared because the
+  counts are single digits, where the chi-squared approximation is not
+  trustworthy;
+- a **95% Newcombe interval on the delta**, built from each arm's Wilson
+  interval. Wilson rather than the normal approximation because runs land on
+  the boundaries (8/8, 0/8), where the normal interval has zero width and
+  would claim certainty from eight trials.
+
+`helps` and `hurts` require **p < 0.05**. Anything else is `no measurable
+effect`, however large the gap looks, and the report says so with the p
+attached. The default is 20 trials per arm: below roughly that, a partial
+result cannot reach significance at all.
+
+Until 2026-08-02 the rule was `>= +15 points helps`, with a default of 5
+trials. At that size 5/5 against 4/5 is +20 points and p = 1.0000. See ADR-028.
+
+Two things the judge does, which matter for reading a result:
+
+- it runs at **temperature 0**, so the same answer grades the same way twice.
+  The subject arm stays at temperature 1, because normal behaviour is the thing
+  being measured;
+- a reply that is neither PASS nor FAIL is **excluded and counted separately**,
+  not scored as a failure. A refusal or an API error is not evidence about the
+  skill.
+
+### What this design still cannot tell you
+
+Named here rather than left for a reader to discover:
+
+- **The judge is the same model as the subject.** A separate judge model would
+  be stronger.
+- **The control arm receives no system prompt at all**, so "the skill's
+  content" is confounded with "having any system prompt". A length-matched
+  placebo is the fix and is not implemented.
+- **Two scenarios is a demonstration, not a benchmark.** The committed runs
+  show the method works, not that skills in general do or do not help.
+
+Treat a single scenario as evidence about that scenario.

package/docs/RULES.md

@@ -7,43 +7,49 @@ Grade starts at 100; each error costs 15, each warning 5, each info 1.
 `A >= 90, B >= 80, C >= 70, D >= 60, else F`.
 
 MCP checks split into **2026-07-28 readiness** (E101-E118) and **quality**
-(E121-E130); skill checks are S1xx. **Only quality and skill findings are
+(E121-E128 and E130, with no E129); skill checks are S1xx. **Only quality and skill findings are
 graded.** Readiness findings are reported as a separate, ungraded **migration
-diff**: the stateless revision they target is a locked Release Candidate
-(2026-05-21) that does not finalize until 2026-07-28, and not yet migrating to
-an unreleased spec is a to-do, not a defect. Readiness severities still order
-the diff by urgency, but the diff never affects the grade, the badge, or the
-exit code (including `--strict`). Once the spec ratifies, expect readiness to
-start counting in a minor release. Source-pattern rules are heuristics and say
-so in their detail line.
+diff**: the two answer different questions. The grade is what a model
+experiences from this tool surface; readiness is whether a 2026-07-28 client can
+talk to this server. Combining them scored the official reference server a C(79)
+for a tool surface that is an A(95), which is why they are two numbers printed
+next to each other rather than one. Readiness severities still order the diff by
+urgency, but the diff never affects the grade or the badge, and never affects
+the exit code unless you ask for it with `--strict-readiness`. Source-pattern
+rules are heuristics and say so in their detail line.
 
 ## MCP readiness (E101-E118)
 
 | id | sev | what it catches | source of truth |
 |---|---|---|---|
 | E101 | warn | depends on a pre-`2026-07-28` SDK line (TS `@modelcontextprotocol/sdk` 1.x, Python `mcp` 1.x) instead of the 2.x stateless line | changelog / SDK releases |
-| E102 | warn | source uses **Sampling** (`sampling/createMessage`), deprecated (SEP-2577) | draft changelog |
-| E103 | warn | source uses **Roots** (`roots/list`), deprecated (SEP-2577) | draft changelog |
-| E104 | warn | server declares the **logging** capability or source uses MCP Logging, deprecated (SEP-2577); `logging/setLevel` is removed | draft changelog |
+| E102 | warn | source uses **Sampling** (`sampling/createMessage`), deprecated (SEP-2577) | 2026-07-28 changelog |
+| E103 | warn | source uses **Roots** (`roots/list`), deprecated (SEP-2577) | 2026-07-28 changelog |
+| E104 | warn | server declares the **logging** capability or source uses MCP Logging, deprecated (SEP-2577); `logging/setLevel` is removed | 2026-07-28 changelog |
 | E105 | warn | the server does not answer a bare stateless `tools/list` (timeout, crash, or a not-initialized error), so it requires the removed `initialize` handshake. A server that answers (even with an error) is judged by E106/E107/E118 instead | SEP-2567 / stateless core |
-| E106 | warn | `server/discover` is not implemented (MUST in the RC, SEP-2575) | draft changelog |
-| E107 | info | results omit the required `resultType` field (`"complete"` \| `"input_required"`) | draft changelog |
-| E108 | info | source relies on removed SSE resumability (`Last-Event-ID`) | draft changelog |
+| E106 | warn | `server/discover` is not implemented (MUST in 2026-07-28, SEP-2575) | 2026-07-28 changelog |
+| E107 | info | results omit the required `resultType` field (`"complete"` \| `"input_required"`) | 2026-07-28 changelog |
+| E108 | info | source relies on removed SSE resumability (`Last-Event-ID`) | 2026-07-28 changelog |
 | E109 | info | auth advertises deprecated DCR (RFC 7591) with no detected CIMD support | PR #2858 / CIMD |
-| E110 | warn | source uses legacy elicitation (`elicitation/create`); replaced by MRTR `input_required` results (SEP-2322) | draft changelog |
+| E110 | warn | source uses legacy elicitation (`elicitation/create`); replaced by MRTR `input_required` results (SEP-2322) | 2026-07-28 changelog |
 | E111 | info | in-process session-state patterns; statelessness expects server-minted handles in tool args | stateless core |
-| E112 | warn | `tools/list` order is nondeterministic across connections (hurts prompt-cache hits) | draft changelog |
+| E112 | warn | `tools/list` order is nondeterministic across connections (hurts prompt-cache hits) | 2026-07-28 changelog |
 | E113 | info | no Server Card found at `/.well-known/mcp` (discovery metadata; heuristic path) | roadmap / Server Card WG |
-| E114 | info | source uses the removed `ping` utility | draft changelog |
-| E115 | info | source uses `resources/subscribe`, replaced by `subscriptions/listen` | draft changelog |
+| E114 | info | source uses the removed `ping` utility | 2026-07-28 changelog |
+| E115 | info | source uses `resources/subscribe`, replaced by `subscriptions/listen` | 2026-07-28 changelog |
 | E116 | warn | server prints non-JSON noise on stdout (breaks stdio framing) | transport basics |
-| E117 | warn | only the deprecated HTTP+SSE transport worked; Streamable HTTP failed | draft changelog |
-| E118 | warn | `tools/list` result omits the now-required `ttlMs`/`cacheScope` cache fields (SEP-2549, CacheableResult; also required on prompts/list, resources/list, resources/read, resources/templates/list, server/discover) | draft changelog |
+| E117 | warn | only the deprecated HTTP+SSE transport worked; Streamable HTTP failed | 2026-07-28 changelog |
+| E118 | warn | a `tools/list` or `server/discover` result omits the required `ttlMs`/`cacheScope` cache fields (SEP-2549, CacheableResult; also required on prompts/list, resources/list, resources/read, resources/templates/list). Both surfaces efaimo calls are measured and the message names the ones that failed. `server/discover` counts only since the published spec made `DiscoverResult` extend `CacheableResult`; under the locked RC it did not | 2026-07-28 changelog |
 
-## MCP quality (E121-E130)
+## MCP quality (E121-E128, E130)
+
+There is no E129. The range used to be written "E121-E130", which implies a
+contiguous block and invites a lookup that finds nothing; ids are stable and
+never reused, so a gap is permanent and is better stated than smoothed over.
 
 | id | sev | what it catches |
 |---|---|---|
+| E000 | warn | a rule threw and was skipped, so this report is incomplete. **Reported but never scored**: a broken rule is our defect, not the target's, and must not cost it points. It exists because `runRules` used to swallow the exception silently, which made a crashing rule indistinguishable from a passing one and silently RAISED the grade |
 | E121 | error/warn | tool description missing, a placeholder, or under ~20 chars |
 | E122 | warn | description misses 3+ of 4 quality axes (length, when-to-use, params documented, mentions result), mirrors Glama's tool-definition-quality dimensions, computed locally |
 | E123 | warn/info | no tools declare annotations; a destructive-looking tool lacks `destructiveHint` |
@@ -52,7 +58,7 @@ so in their detail line.
 | E126 | warn/info | tool names mix conventions or exceed 64 chars |
 | E127 | warn | a single tool definition costs 800+ tokens (needs `weigh` data) |
 | E128 | warn | total tool-definition tax over ~10k / ~25k tokens, estimated (needs `weigh` data); hard CI failure is left to the `--max-tokens`/`--diff` gate |
-| E130 | info | instruction-injection patterns in a tool description or server instructions (shallow heuristic, never a security verdict; use a dedicated scanner for depth) |
+| E130 | info | instruction-injection patterns in a tool description or server instructions (shallow heuristic, never a security verdict; use a dedicated scanner for depth). **Reported but never scored** |
 
 ## Skills (S101-S106)
 
@@ -62,7 +68,7 @@ so in their detail line.
 | S102 | warn/info | description too thin or never says when to use the skill | agentskills.io |
 | S103 | error/warn | duplicate skill names, or two skills with heavily overlapping descriptions (trigger collision) | internal |
 | S104 | warn/info | metadata over ~100 tokens, body over ~5k tokens or 500 lines, or long body with no progressive disclosure | agentskills.io |
-| S105 | info | instruction-injection patterns in the skill body or description (shallow heuristic, never a security verdict) | internal |
+| S105 | info | instruction-injection patterns in the skill body or description (shallow heuristic, never a security verdict). **Reported but never scored** | internal |
 | S106 | error/warn/info | referenced file missing, escaping the skill dir (`..`), or nested more than one level deep | agentskills.io |
 
 ## Notes on heuristics

package/examples/contoso-crm-import/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: contoso-crm-import
+description: Format a contact list as a Contoso CRM bulk-import file. Use when the user asks to prepare, convert, or export contacts for Contoso CRM import.
+license: Apache-2.0
+---
+
+# Contoso CRM bulk-import format
+
+Convert a contact list into the exact file Contoso CRM accepts on import. These
+rules are an internal convention and are not guessable; follow them exactly.
+
+## Output rules
+1. Semicolon-delimited. No header row.
+2. Four columns, in this order: member_id;display_name;email;source
+3. member_id: the first three letters of the last name, uppercased, then a hyphen,
+   then a row number zero-padded to four digits starting at 0001 (0001, 0002, ...).
+4. display_name: the full name exactly as given.
+5. email: lowercased.
+6. source: always the literal value import-2026.
+
+Output only the rows.

package/examples/csv-cleanup/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: csv-cleanup
+description: Clean and validate CSV data. Use when the user asks to deduplicate, trim, or sanity-check a CSV before import.
+license: Apache-2.0
+---
+
+# CSV cleanup
+
+Use this when the user wants to tidy CSV data.
+
+## Steps
+1. Detect the delimiter (comma, tab, or semicolon) from the header row.
+2. Trim leading and trailing whitespace from every cell.
+3. Drop rows that are exact duplicates of an earlier row.
+4. Report the final row and column counts, and how many duplicates were removed.
+
+Always show the cleaned result and a one-line summary of what changed.

package/examples/scenario.crm.yaml

@@ -0,0 +1,22 @@
+# efaimo test scenario: a skill that encodes a convention the model cannot guess.
+# Contrast with scenario.example.yaml, where a capable model needs no skill.
+# Real run (spends tokens): npx efaimo test examples/scenario.crm.yaml --live
+name: contoso-crm-import helps on an unknowable format
+skill: ./contoso-crm-import
+model: claude-sonnet-5
+trials: 8
+task: |
+  Prepare these contacts for Contoso CRM import:
+
+  Ada Lovelace, ADA@Example.com
+  Grace Hopper, Grace.Hopper@NAVY.MIL
+  Alan Turing, a.turing@Bletchley.uk
+judge: |
+  PASS if the answer contains these three rows (ignore any surrounding prose or code
+  fences), each semicolon-delimited as member_id;display_name;email;source:
+    LOV-0001;Ada Lovelace;ada@example.com;import-2026
+    HOP-0002;Grace Hopper;grace.hopper@navy.mil;import-2026
+    TUR-0003;Alan Turing;a.turing@bletchley.uk;import-2026
+  The member_id (first three letters of the last name uppercased, a hyphen, then a
+  four-digit zero-padded row number), the lowercased email, and the literal source
+  value import-2026 must all be exact. Any other format is FAIL.

package/examples/scenario.example.yaml

@@ -0,0 +1,17 @@
+# efaimo test scenario: does the csv-cleanup skill actually help?
+# Dry run (no API calls):   npx efaimo test examples/scenario.example.yaml
+# Real run (spends tokens): npx efaimo test examples/scenario.example.yaml --live
+name: csv-cleanup helps on a messy CSV
+skill: ./csv-cleanup
+model: claude-sonnet-5
+trials: 8
+task: |
+  Clean this CSV and summarize what you changed:
+
+  name , email ,city
+  Ada ,ada@example.com, London
+  Ada ,ada@example.com, London
+  Grace,grace@example.com ,New York
+judge: |
+  PASS only if the answer (a) removes the duplicate Ada row, (b) trims the stray
+  whitespace around cells, and (c) states the final row count. Otherwise FAIL.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "efaimo",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Audit what your agent loads: quality and context cost for MCP servers and Agent Skills",
   "keywords": [
     "mcp",
@@ -46,6 +46,7 @@
   },
   "files": [
     "dist",
+    "examples",
     "SKILL.md",
     "NOTICE",
     "CHANGELOG.md",
@@ -57,6 +58,7 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "spec:drift": "node scripts/spec-drift.mjs",
     "test:watch": "vitest",
     "prepublishOnly": "npm run typecheck && npm run build && npm run test"
   },