efaimo 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,124 @@ All notable changes to efaimo are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project uses
 [Semantic Versioning](https://semver.org/).
 
+## [0.6.0] - 2026-11-02
+
+### Added
+
+- **S108: a reference file nothing points at**. A file under
+  `references/` that no markdown link or backticked path resolves to, whose
+  path never appears in `SKILL.md`, whose directory is never named there, and
+  that no reference file which IS reached mentions either. It ships in the
+  package, installs byte-perfect, and an agent has no route to it.
+
+  Found in this project's own skills on 2026-09-04: `read-back` had shipped a
+  4.6 KB failure gallery that grew for a month with nothing linking to it, and
+  `unreleased-guard` had shipped `the-gap.md` the same way. The installer
+  tests, the house style guard and an A(100) were all green, because none of
+  them is about whether a shipped file is reachable. The workspace that
+  publishes those skills got a checker the same day; this is the rule for
+  everyone else's `references/`.
+
+  Reported and **not scored**, the way S105 is. Measured before it was
+  written, on the public corpus at the commits `research/skills-index/manifest.json`
+  pins: 2 of 36 skills carry a `references/` directory at all, 4 files between
+  them, no orphan, so there is no population to calibrate a penalty on and no
+  published grade moves. Scoring it is a separate decision. It fires under
+  `--strict`, which is where our own seven repositories run it.
+
+  Transitive on purpose: a reader who opens `references/api.md` can follow a
+  link inside it, so a file reached that way is not an orphan. Scoped to
+  `references/` on purpose: `scripts/` is executed rather than read and
+  `assets/` is consumed by scripts, so an unmentioned file there is a
+  different claim.
+
+### Changed
+
+- **`rulesVersion` is `3`**. No grade moves with S108, but a
+  report from this ruleset carries a rule id that ruleset `2` could not have
+  produced, and `check --diff` across the two would attribute that to the
+  subject rather than to the ruler.
+
+### Security
+
+- **Seven advisories against the MCP SDK and zod, fixed by upgrading**.
+  `@modelcontextprotocol/client` and
+  `@modelcontextprotocol/server` move from 2.0.0 to 2.3.1, the first release
+  that carries every patch, and still pinned exactly. zod's floor moves from
+  `^4.5.4` to `^4.6.6`. `pnpm audit --prod` went from 7 findings (5 high, 2
+  moderate) to none.
+
+  What they reach in this tool, read from the call sites: `efaimo mcp` serves
+  over stdio only, so the four server advisories about the HTTP transport
+  (GHSA-f897-62hf-6gxq body size, GHSA-jm63-cq47-j5jp shared transport,
+  GHSA-46jr-4wx8-v453 memory, GHSA-rvq5-wwqv-78pq bearer auth) describe code it
+  never runs. The OAuth advisory on the client (GHSA-6qxp-vccf-f47h) needs an
+  auth provider, and efaimo passes none. The one with a plausible path is
+  GHSA-6prh-2h8m-c8cw, headers re-sent across an origin redirect: `--header`
+  values go to Streamable HTTP and legacy SSE targets, and `requestInit` sets
+  `redirect: "error"`, but nobody has shown that every request the SSE
+  fallback makes inherits it. zod (GHSA-mrhx-c7xc-m3w5) has no known path here.
+
+  Who gets it when: zod's range floats, so a fresh `npx efaimo@0.5.0` already
+  resolves a patched zod. The SDK pins are exact, so that half reaches users
+  with this release and not before.
+
+  Measured after the upgrade with the same command as 0.5.0's entry: `check
+  --mcp "node dist/cli.js mcp"` still reports `grade A (100)` and `clean,
+  nothing to migrate`.
+
+- **Ten dev-only advisories, fixed by moving vitest from 4.1.10 to 4.1.12**,
+  which re-resolves vite from 8.2.0 to 8.3.5 and source-map-js
+  to 1.2.2. None of them ships in the package; `pnpm audit` over every
+  dependency now finds nothing.
+
+## [0.5.0] - 2026-09-04
+
+### Changed
+
+- **`efaimo mcp` is built on the 2.x SDK line and now satisfies the
+  specification this tool audits other servers against.** The 1.x line speaks
+  2025-11-25; it cannot answer `server/discover` and cannot carry the SEP-2549
+  cache fields, so the one MCP server this project ships failed two MUST-level
+  items of the 2026-07-28 revision, and `check --mcp` said so about it on every
+  run. The skill this project publishes about that migration opens with "upgrade
+  the SDK first". This is that.
+
+  Measured against the built server, before and after, with the same command:
+
+  ```
+  before   2026-07-28 readiness  3 items to migrate   E106, E118, E107
+  after    2026-07-28 readiness  clean, nothing to migrate
+  ```
+
+  Read off the wire rather than from our own tool as well: a modern opening now
+  answers `server/discover` with `supportedVersions`, `capabilities`,
+  `resultType: "complete"`, `ttlMs` and `cacheScope`, and `tools/list` carries
+  the same three fields. A 2025-era client that opens with `initialize` is still
+  served, unchanged, because `serveStdio` pins the era per connection rather
+  than making the server pick one.
+
+- **The client half moved with it**, from `@modelcontextprotocol/sdk` to
+  `@modelcontextprotocol/client`. Doing only the server half would have left
+  both generations installed, and E101 stops firing the moment any 2.x package
+  is present, so the half-migration would have silenced the rule that was
+  telling the truth.
+
+### Fixed
+
+- **Two moderate advisories, by subtraction.** `qs` arrived through
+  `body-parser` through `express` through the 1.x SDK, which pulls a whole HTTP
+  and OAuth stack that a stdio server never speaks. `pnpm audit --prod` now
+  reports no known vulnerabilities, and production dependencies went from 30 to
+  13.
+
+### Notes
+
+- No rule changed, so no grade moved. `rulesVersion` is untouched and the
+  published skills index does not need regenerating.
+- `check --skill`, `weigh`, `find` and `test` are byte-identical in behaviour;
+  the only thing that moved is what `efaimo mcp` puts on the wire.
+
 ## [0.4.0] - 2026-09-03
 
 ### Fixed
@@ -408,6 +526,8 @@ First release.
   Documented rule set (`docs/RULES.md`), token methodology (`docs/METHODOLOGY.md`),
   and integration guide (`docs/INTEGRATIONS.md`).
 
+[0.6.0]: https://github.com/efaimo-ai/efaimo/releases/tag/v0.6.0
+[0.5.0]: https://github.com/efaimo-ai/efaimo/releases/tag/v0.5.0
 [0.4.0]: https://github.com/efaimo-ai/efaimo/releases/tag/v0.4.0
 [0.3.0]: https://github.com/efaimo-ai/efaimo/releases/tag/v0.3.0
 [0.2.0]: https://github.com/efaimo-ai/efaimo/releases/tag/v0.2.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/banner.png" alt="efaimo. The audit CLI for Agent Skills and MCP servers." width="820">
+  <img src="https://raw.githubusercontent.com/efaimo-ai/efaimo/main/assets/banner.png" alt="efaimo. The audit CLI for Agent Skills and MCP servers." width="820">
 </p>
 
 <p align="center">
@@ -87,7 +87,7 @@ csv-cleanup skill that a capable model does not need, and a skill that encodes a
 convention the model cannot guess.
 
 <p align="center">
-  <img src="assets/test-ab.png" alt="efaimo test A/B results: csv-cleanup measures +0 points (no measurable effect) while contoso-crm-import measures +100 points (helps); both skills lint clean at grade A" width="880">
+  <img src="https://raw.githubusercontent.com/efaimo-ai/efaimo/main/assets/test-ab.png" alt="efaimo test A/B results: csv-cleanup measures +0 points (no measurable effect) while contoso-crm-import measures +100 points (helps); both skills lint clean at grade A" width="880">
 </p>
 
 <details>
@@ -137,7 +137,7 @@ npx efaimo check --mcp "npx -y my-server"    # quality grade + 2026-07-28 migrat
 per tool, with an optional `--anthropic` exact Claude count.
 
 <p align="center">
-  <img src="assets/demo.png" alt="efaimo weigh example output" width="720">
+  <img src="https://raw.githubusercontent.com/efaimo-ai/efaimo/main/assets/demo.png" alt="efaimo weigh example output" width="720">
 </p>
 
 `check --mcp` connects live (it speaks both the legacy handshake and the new
@@ -155,7 +155,7 @@ surface that is an A. Pass `--strict-readiness` when you want CI to fail on
 the diff. Full list: [docs/RULES.md](./docs/RULES.md).
 
 <p align="center">
-  <img src="assets/check.png" alt="efaimo check example output: quality grade A (95) plus a four-item 2026-07-28 migration diff for the reference server" width="800">
+  <img src="https://raw.githubusercontent.com/efaimo-ai/efaimo/main/assets/check.png" alt="efaimo check example output: quality grade A (95) plus a four-item 2026-07-28 migration diff for the reference server" width="800">
 </p>
 
 *(That is the official reference server: solid quality, four things left to
@@ -253,7 +253,7 @@ your host actually serializes it, and grades the quality, before any of it reach
 your context window.
 
 <p align="center">
-  <img src="assets/architecture.png" alt="efaimo weighs, checks, and tests what your agent loads" width="880">
+  <img src="https://raw.githubusercontent.com/efaimo-ai/efaimo/main/assets/architecture.png" alt="efaimo weighs, checks, and tests what your agent loads" width="880">
 </p>
 
 ## How it compares
@@ -349,7 +349,7 @@ npx efaimo weigh "npx -y my-server" --diff base.json --allow-increase 10
 `--badge badge.svg` writes an SVG plus a shields.io endpoint JSON for your
 README. These two are real efaimo output for the reference server:
 
-<img src="assets/badge-weigh.svg" alt="context cost: 1120 tok (o200k)"> <img src="assets/badge-grade.svg" alt="efaimo: A (95)">
+<img src="https://raw.githubusercontent.com/efaimo-ai/efaimo/main/assets/badge-weigh.svg" alt="context cost: 1120 tok (o200k)"> <img src="https://raw.githubusercontent.com/efaimo-ai/efaimo/main/assets/badge-grade.svg" alt="efaimo: A (95)">
 
 More recipes (pre-commit, GitLab, editor audit, programmatic use):
 [docs/INTEGRATIONS.md](./docs/INTEGRATIONS.md).
@@ -358,7 +358,7 @@ More recipes (pre-commit, GitLab, editor audit, programmatic use):
 
 | family | covers |
 |---|---|
-| **S101 to S106** | skills: frontmatter and trigger quality, trigger collisions, context budget, reference integrity, injection hygiene |
+| **S101 to S108** | skills: frontmatter and trigger quality, trigger collisions, context budget, reference integrity, injection hygiene, a filename one capitalisation away from `SKILL.md`, and a reference file nothing points at |
 | **E101 to E118** | MCP 2026-07-28 readiness: deprecated primitives, statelessness, `server/discover`, `resultType`, cache fields, transport |
 | **E121 to E128, E130** | MCP quality: description quality, annotations, schema hygiene, tool-count and token-cost budgets |
 | **E141 to E146** | MCP findability: exclusive vocabulary, whether a search returns the tool, indistinguishable pairs, names that carry no domain word |

package/SKILL.md

@@ -3,8 +3,8 @@ name: efaimo
 description: Audit MCP servers and Agent Skills for quality and context-window cost. Use when the user wants to check an MCP server's token cost, lint a skill, verify 2026-07-28 MCP spec readiness, find out whether a search can single out a server's tools under deferred tool loading, or add an efaimo badge or CI gate.
 license: Apache-2.0
 metadata:
-  version: "0.4.0"
-  homepage: "https://efaimo.ai"
+  version: "0.6.0"
+  homepage: "https://efaimo.com"
 ---
 
 # efaimo
@@ -74,3 +74,14 @@ methodology doc for the full method.
 efaimo is a linter and cost profiler, not a security scanner: its injection checks
 are surface heuristics. For supply-chain security use a dedicated scanner. Full
 rule reference: https://github.com/efaimo-ai/efaimo/blob/main/docs/RULES.md
+
+<!-- generated:siblings -->
+
+## Siblings
+
+Every skill in this set is about a report that was true about the wrong thing. The set: https://efaimo.com/skills
+
+- `denominator` - the counts efaimo prints are only worth as much as the sets they were taken over.
+- `mcp-stateless-migration` - when `check --mcp` prints a readiness list and you want to work it.
+
+<!-- /generated:siblings -->

package/dist/clients/introspect.js

@@ -1,8 +1,8 @@
 import crossSpawn from "cross-spawn";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { Client } from "@modelcontextprotocol/client";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { SSEClientTransport } from "@modelcontextprotocol/client";
 import { introspectStateless } from "./stateless.js";
 import { minimalChildEnv } from "../util/childEnv.js";
 import { truncate, withTimeout } from "../util/misc.js";

package/dist/mcp/server.d.ts

@@ -1,3 +1,3 @@
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-export declare function buildMcpServer(): Server;
+import { McpServer } from "@modelcontextprotocol/server";
+export declare function buildMcpServer(): McpServer;
 export declare function runMcpServer(): Promise<void>;

package/dist/mcp/server.js

@@ -1,88 +1,94 @@
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { z } from "zod";
 import { checkSkillSet } from "../check/check.js";
 import { weighSkills } from "../weigh/weigh.js";
 import { findSkills } from "../skills/parse.js";
 import { renderCheckMarkdown, renderSkillSetMarkdown, renderWeighMarkdown } from "../reporters/markdown.js";
 import { VERSION } from "../version.js";
+/**
+ * `efaimo mcp`: a small, read-only MCP server that exposes the skill checks to an
+ * agent, so it can lint or weigh a skill mid-session before committing it to
+ * context. Deliberately narrow: the tools only read files. They spawn no process
+ * and open no socket (unlike `check --mcp`, which connects to a live server), and
+ * `test` is not exposed at all because it spends tokens. That keeps the surface
+ * safe for an agent to call unattended.
+ *
+ * Built on the 2.x SDK line since 0.5.0. The 1.x line speaks 2025-11-25 and
+ * cannot answer `server/discover` or carry the SEP-2549 cache fields, so this
+ * server failed two MUST-level items of the specification the rest of this tool
+ * audits other servers against, and the skill this project publishes about that
+ * migration opens with "upgrade the SDK first". It was the only server we ship
+ * and the only one we had not migrated.
+ *
+ * `serveStdio` owns the era decision rather than this file: the opening exchange
+ * selects it, one instance is pinned for the connection, and a 2025-era client
+ * that opens with `initialize` is still served. Registering the tools once, on a
+ * factory that serves both eras, is the whole reason to use it instead of
+ * wiring a transport by hand.
+ */
 // Both tools only read local files, so the same hints apply: safe to call without
 // a confirmation, safe to repeat, and not reaching out to any external service.
 const READ_ONLY = { readOnlyHint: true, idempotentHint: true, openWorldHint: false };
-function requireString(args, key) {
-    const v = args[key];
-    if (typeof v !== "string" || v.trim() === "") {
-        throw new Error(`"${key}" is required and must be a non-empty string`);
-    }
-    return v;
-}
-const pathSchema = (what) => ({
-    type: "object",
-    properties: { path: { type: "string", description: what } },
-    required: ["path"],
-    additionalProperties: false,
+// One shared shape. `.min(1)` is the schema saying what `requireString` used to
+// say at runtime: an empty path is not a path. Under the 2.x registration the
+// SDK validates against this before the handler runs, so the check moved from
+// our code into the contract, which is where a client can also see it.
+const pathInput = (what) => z.object({ path: z.string().min(1).describe(what) });
+const CHECK_DESCRIPTION = "Lint an Agent Skill, or a folder of skills, for spec compliance, trigger quality, " +
+    "context-window cost, reference integrity, and injection hygiene. Returns a grade from " +
+    "A to F and the findings. Read-only: reads files only.";
+const WEIGH_DESCRIPTION = "Measure the context-window token cost of an Agent Skill: the metadata loaded into every " +
+    "session and the body loaded when the skill triggers. Returns token counts per skill. " +
+    "Read-only: reads files only.";
+const text = (s) => ({ content: [{ type: "text", text: s }] });
+const failure = (e) => ({
+    content: [{ type: "text", text: `error: ${e instanceof Error ? e.message : String(e)}` }],
+    isError: true,
 });
-const TOOLS = [
-    {
-        name: "efaimo_check_skill",
-        description: "Lint an Agent Skill, or a folder of skills, for spec compliance, trigger quality, " +
-            "context-window cost, reference integrity, and injection hygiene. Returns a grade from " +
-            "A to F and the findings. Read-only: reads files only.",
-        inputSchema: pathSchema("Path to a SKILL.md file or a directory that contains skills."),
+export function buildMcpServer() {
+    const server = new McpServer({ name: "efaimo", version: VERSION }, { capabilities: { tools: {} } });
+    server.registerTool("efaimo_check_skill", {
+        description: CHECK_DESCRIPTION,
+        inputSchema: pathInput("Path to a SKILL.md file or a directory that contains skills."),
         annotations: READ_ONLY,
-        async run(args) {
-            const p = requireString(args, "path");
-            const res = await checkSkillSet(p, p);
+    }, async ({ path }) => {
+        try {
+            const res = await checkSkillSet(path, path);
             if (res.perSkill.length === 1 && res.setFindings.length === 0) {
-                return renderCheckMarkdown(res.perSkill[0].report);
+                return text(renderCheckMarkdown(res.perSkill[0].report));
             }
-            return renderSkillSetMarkdown(res);
-        },
-    },
-    {
-        name: "efaimo_weigh_skill",
-        description: "Measure the context-window token cost of an Agent Skill: the metadata loaded into every " +
-            "session and the body loaded when the skill triggers. Returns token counts per skill. " +
-            "Read-only: reads files only.",
-        inputSchema: pathSchema("Path to a SKILL.md file or a directory that contains skills."),
-        annotations: READ_ONLY,
-        async run(args) {
-            const p = requireString(args, "path");
-            const set = findSkills(p);
-            if (!set.skills.length)
-                throw new Error(`no SKILL.md found under "${p}"`);
-            return renderWeighMarkdown(await weighSkills(set));
-        },
-    },
-];
-export function buildMcpServer() {
-    const server = new Server({ name: "efaimo", version: VERSION }, { capabilities: { tools: {} } });
-    server.setRequestHandler(ListToolsRequestSchema, () => ({
-        tools: TOOLS.map((t) => ({
-            name: t.name,
-            description: t.description,
-            inputSchema: t.inputSchema,
-            annotations: t.annotations,
-        })),
-    }));
-    server.setRequestHandler(CallToolRequestSchema, async (req) => {
-        const tool = TOOLS.find((t) => t.name === req.params.name);
-        if (!tool) {
-            return { content: [{ type: "text", text: `unknown tool: ${req.params.name}` }], isError: true };
+            return text(renderSkillSetMarkdown(res));
         }
+        catch (e) {
+            return failure(e);
+        }
+    });
+    server.registerTool("efaimo_weigh_skill", {
+        description: WEIGH_DESCRIPTION,
+        inputSchema: pathInput("Path to a SKILL.md file or a directory that contains skills."),
+        annotations: READ_ONLY,
+    }, async ({ path }) => {
         try {
-            const text = await tool.run(req.params.arguments ?? {});
-            return { content: [{ type: "text", text }] };
+            const set = findSkills(path);
+            if (!set.skills.length)
+                throw new Error(`no SKILL.md found under "${path}"`);
+            return text(renderWeighMarkdown(await weighSkills(set)));
         }
         catch (e) {
-            const message = e instanceof Error ? e.message : String(e);
-            return { content: [{ type: "text", text: `error: ${message}` }], isError: true };
+            return failure(e);
         }
     });
     return server;
 }
 export async function runMcpServer() {
-    const server = buildMcpServer();
-    await server.connect(new StdioServerTransport());
+    // A factory, not an instance: `serveStdio` pins one per connection after the
+    // opening exchange tells it which era it is talking to.
+    serveStdio(() => buildMcpServer(), {
+        onerror: (e) => console.error(`efaimo mcp: ${e.message}`),
+    });
     console.error(`efaimo mcp v${VERSION}: read-only skill tools ready on stdio`);
+    // stdin holds the process open; there is nothing to await. Returning a promise
+    // that never settles would only make the shutdown path harder to read.
+    await new Promise(() => { });
 }

package/dist/rules/skill/index.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { scanTextForInjection } from "../injection.js";
 import { tokenize, QUERY_STOPWORDS } from "../../find/tokenize.js";
-import { formatTokens } from "../../util/misc.js";
+import { formatTokens, readTextSafe, isBinaryPath } 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"]);
 function skillLabel(s) {
@@ -309,4 +309,116 @@ const s106 = {
         return findings;
     },
 };
-export const SKILL_RULES = [s101, s102, s103, s104, s105, s106];
+// S108. A file under references/ that nothing points at.
+//
+// Found on 2026-09-04 in two of this project's own seven published skills:
+// read-back shipped a 4.6 KB failure gallery that had been growing for a
+// month, unreleased-guard shipped the-gap.md, and no SKILL.md linked to
+// either. Both were packaged, both installed byte-perfect into a user's skills
+// directory, and an agent had no route to them. The agentskills.io layout puts
+// material "loaded into context as needed" under references/, and the only
+// thing that can cause a load is a path in the instructions. Installer tests,
+// house style and an A(100) were all green about it, because none of them is
+// about whether a shipped file is reachable.
+//
+// Reachable means: a reference the parser already resolved (a markdown link
+// or a backticked path), the file's skill-relative path appearing anywhere in
+// the body, or an ancestor directory named with its trailing slash ("see
+// references/"); and transitively the same from any reference file that is
+// itself reached, because a reader who opens references/api.md can follow a
+// link inside it. The lenient direction is deliberate: a false red here
+// teaches the reader to skip the rule.
+//
+// Scoped to references/ on purpose. scripts/ is executed rather than read and
+// assets/ is consumed by scripts, so an unmentioned file there is a different
+// claim. Measured on the public corpus at the pinned commits before this was
+// written (research/skills-index/manifest.json): 2 of 36 skills carry a
+// references/ directory at all, 4 files between them, no orphan. Our own set
+// had two on 2026-09-04 and has none since. There is no population to
+// calibrate a penalty on, so this is reported without being scored, the way
+// S105 is; scoring it is a separate decision that has to move grades with
+// evidence behind it.
+const S108_MAX = 10;
+const s108 = {
+    id: "S108",
+    title: "reference file nothing points at",
+    surface: "skill",
+    check({ skill }) {
+        const refDir = path.join(skill.dir, "references");
+        const prefix = refDir + path.sep;
+        const candidates = skill.files.filter((f) => f.path.startsWith(prefix));
+        if (!candidates.length)
+            return [];
+        const rel = (abs) => path.relative(skill.dir, abs).split(path.sep).join("/");
+        // The file's own path, or any ancestor directory of it named on its own
+        // with its trailing slash, appearing in the text.
+        //
+        // "On its own" is load-bearing and the first version did not have it: it
+        // asked whether the text contained "references/", and every link to a
+        // sibling file under references/ contains exactly that, so linking ONE
+        // reference file marked every other file in the directory as reached and
+        // the rule could not fire on the fixture written to make it fire. The
+        // slash has to be followed by something that cannot continue a path.
+        const dirNamed = (text, dir) => new RegExp(dir.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "/(?![A-Za-z0-9_.-])").test(text);
+        const mentions = (text, r) => {
+            if (text.includes(r))
+                return true;
+            const parts = r.split("/");
+            for (let i = 1; i < parts.length; i++) {
+                if (dirNamed(text, parts.slice(0, i).join("/")))
+                    return true;
+            }
+            return false;
+        };
+        const reached = new Set();
+        const resolvedRefs = new Set(skill.referencedPaths.filter((x) => x.exists && !x.escapes).map((x) => path.resolve(x.resolved)));
+        for (const c of candidates) {
+            if (resolvedRefs.has(path.resolve(c.path)) || mentions(skill.body, rel(c.path)))
+                reached.add(c.path);
+        }
+        // Transitive: a reached text file can point at its siblings, by the
+        // skill-relative path or by a path relative to itself.
+        const scanned = new Set();
+        let grew = true;
+        while (grew) {
+            grew = false;
+            for (const r of [...reached]) {
+                if (scanned.has(r) || isBinaryPath(r))
+                    continue;
+                scanned.add(r);
+                const text = readTextSafe(r);
+                if (text === undefined)
+                    continue;
+                const from = path.dirname(r);
+                for (const c of candidates) {
+                    if (reached.has(c.path))
+                        continue;
+                    const own = path.relative(from, c.path).split(path.sep).join("/");
+                    if (mentions(text, rel(c.path)) || text.includes(own)) {
+                        reached.add(c.path);
+                        grew = true;
+                    }
+                }
+            }
+        }
+        const label = skillLabel(skill);
+        const findings = [];
+        for (const c of candidates) {
+            if (reached.has(c.path))
+                continue;
+            if (findings.length >= S108_MAX)
+                break;
+            findings.push({
+                ruleId: "S108",
+                severity: "warn",
+                title: "reference file nothing points at",
+                message: `"${rel(c.path)}" ships with the skill and nothing in SKILL.md, or in any reference it does reach, names it; an agent has no path to it, so it costs the reader disk and the publisher maintenance and is never loaded`,
+                target: label,
+                fixHint: "link it from SKILL.md at the point where it applies, or delete it",
+                graded: false,
+            });
+        }
+        return findings;
+    },
+};
+export const SKILL_RULES = [s101, s102, s103, s104, s105, s106, s108];

package/dist/rules/version.d.ts

@@ -12,6 +12,11 @@
  *        no `rulesVersion` field at all; the absence IS the value.
  *   "2"  the first ruleset that declares itself. Adds the findability family
  *        (E141-E145), which no earlier version had.
+ *   "3"  adds S108, a reference file nothing points at. Reported and not
+ *        scored, so no grade moves with it; the number moves anyway, because a
+ *        report from this ruleset carries a rule id that "2" could not have
+ *        produced, and a diff across the two would attribute that to the
+ *        subject.
  *
  * Bump it when a rule is added, removed, renumbered, or changed in what it
  * fires on. `test/meta.test.ts` pins the rule inventory, so an added or
@@ -23,4 +28,4 @@
  * would make it move on every release whether or not a rule moved, which is
  * the thing it exists to distinguish.
  */
-export declare const RULES_VERSION = "2";
+export declare const RULES_VERSION = "3";

package/dist/rules/version.js

@@ -12,6 +12,11 @@
  *        no `rulesVersion` field at all; the absence IS the value.
  *   "2"  the first ruleset that declares itself. Adds the findability family
  *        (E141-E145), which no earlier version had.
+ *   "3"  adds S108, a reference file nothing points at. Reported and not
+ *        scored, so no grade moves with it; the number moves anyway, because a
+ *        report from this ruleset carries a rule id that "2" could not have
+ *        produced, and a diff across the two would attribute that to the
+ *        subject.
  *
  * Bump it when a rule is added, removed, renumbered, or changed in what it
  * fires on. `test/meta.test.ts` pins the rule inventory, so an added or
@@ -23,4 +28,4 @@
  * would make it move on every release whether or not a rule moved, which is
  * the thing it exists to distinguish.
  */
-export const RULES_VERSION = "2";
+export const RULES_VERSION = "3";

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.4.0";
+export declare const VERSION = "0.6.0";

package/dist/version.js

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

package/docs/RULES.md

@@ -65,7 +65,7 @@ never reused, so a gap is permanent and is better stated than smoothed over.
 | 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). **Reported but never scored** |
 
-## Skills (S101-S107)
+## Skills (S101-S108)
 
 | id | sev | what it catches | spec |
 |---|---|---|---|
@@ -76,6 +76,7 @@ never reused, so a gap is permanent and is better stated than smoothed over.
 | 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 |
 | S107 | warn | a file one capitalisation away from a skill, such as `skill.md`. Set-level and never scored: the spec names `SKILL.md` exactly, so it is not a skill here on any platform, but a case-insensitive filesystem (the macOS and Windows default) may hand it to a host, which makes a repository work on a laptop and have no skill at all in Linux CI | internal |
+| S108 | warn | a file under `references/` that nothing points at: no markdown link or backticked path resolves to it, its path does not appear in `SKILL.md`, no ancestor directory of it is named there, and no reference file that IS reached mentions it either. It ships and installs perfectly and an agent has no route to it. **Reported but never scored** _(ruleset 3)_: at the pinned public corpus only 2 of 36 skills carry a `references/` directory and neither has an orphan, so there is no population to calibrate a penalty on; the two real instances were in this project's own skills | internal |
 
 ## Findability (E141-E145)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "efaimo",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Audit what your agent loads: quality and context cost for MCP servers and Agent Skills",
   "keywords": [
     "mcp",
@@ -65,17 +65,19 @@
     "prepublishOnly": "npm run typecheck && npm run build && npm run test"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/client": "2.3.1",
+    "@modelcontextprotocol/server": "2.3.1",
     "commander": "^15.0.0",
     "cross-spawn": "^7.0.6",
     "gpt-tokenizer": "^3.4.0",
     "picocolors": "^1.1.1",
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.0",
+    "zod": "^4.6.6"
   },
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6",
     "@types/node": "^26.1.1",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.12"
   }
 }