efaimo 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,77 @@ 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
@@ -455,6 +526,7 @@ 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

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.5.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/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.5.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.5.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.5.0",
+  "version": "0.6.0",
   "description": "Audit what your agent loads: quality and context cost for MCP servers and Agent Skills",
   "keywords": [
     "mcp",
@@ -65,19 +65,19 @@
     "prepublishOnly": "npm run typecheck && npm run build && npm run test"
   },
   "dependencies": {
-    "@modelcontextprotocol/client": "2.0.0",
-    "@modelcontextprotocol/server": "2.0.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",
-    "zod": "^4.5.4"
+    "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"
   }
 }