efaimo 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,156 @@ 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.4.0] - 2026-09-03
+
+### Fixed
+
+- **`check --skill <dir>` finds skills it used to walk past**.
+  Two causes, both silent. The walk never entered a directory whose name starts
+  with a dot, so `.claude/skills/<name>/`, which is where a project keeps its
+  own skills, was invisible; and its depth bound of 3 missed layouts one level
+  deeper such as `skills/custom_skills/<name>/`. On the public corpus this
+  found 34 skills where `scripts/skills-index.mjs` found 38, and both numbers
+  were reported with confidence.
+
+  Dot directories are now entered for skill discovery and nowhere else, with
+  `.git` still excluded. The depth bound is 6 and is measured rather than
+  picked: the deepest real skill in that corpus sits 4 directories below a
+  directory of repositories and 3 below a repository root, so six leaves two
+  levels of headroom while still keeping an accidental `check --skill /` from
+  walking a disk.
+
+  **And when the bound does bite, it says so.** `SkillSet.truncatedAt` lists
+  the directories the walk refused to enter, because a bound that truncates in
+  silence is the same failure as a check that examines nothing. On the public
+  corpus it fires 16 times, all of them XML schema trees inside the `xlsx` and
+  `pptx` skills, which is the bound doing its job audibly.
+
+- **One walker instead of two**. `scripts/skills-index.mjs`
+  carried its own copy with different rules, which is why the two disagreed.
+  It now calls the CLI's discovery, so they cannot drift apart again, and it
+  passes the truncation warning through. The published July index regenerates
+  byte-identically under the shared walk, which is how this was checked.
+
+### Added
+
+- **S107: a filename one capitalisation away from a skill**.
+  Set-level and warn-level, so it moves no grade, in the same way S103 treats
+  a collision that belongs to a pair rather than to either member.
+
+  The spec names `SKILL.md` exactly and discovery matches it exactly, so
+  `skill.md` is not a skill here on any platform. It is not nothing anywhere:
+  a case-insensitive filesystem, the default on macOS and Windows, may hand it
+  to a host that opens it by name, so the same repository can carry a working
+  skill on the author's laptop and no skill at all in Linux CI. Nothing in
+  this tool would previously have mentioned such a file, which is the worst
+  property a near miss can have. Five exist in the public corpus.
+
+## [0.3.0] - 2026-09-03
+
+### Added
+
+- **`check --out` and `check --diff`**: what moved between two
+  audits of the same subject. Same grammar as `weigh --out` / `weigh --diff`,
+  which is why it is a flag rather than a sixth subcommand. Nothing published
+  says whether skills and MCP servers are getting heavier or whether their
+  quality holds, because that needs the same thing measured twice and nothing
+  made the comparison cheap.
+
+  A delta is exactly the shape a broken measurement takes, so the controls a
+  careful person would run by hand are enforced instead of documented:
+
+  - **Rules drift is a hard stop.** Different `rulesVersion` between the two
+    runs means a moved grade cannot be attributed to the subject, because the
+    ruler moved too. `--allow-rules-drift` proceeds and marks
+    every grade line unattributable.
+  - **An empty pairing fails.** Nothing in common is two reports about
+    different subjects, not "no change".
+  - **The three token costs are never summed.** Metadata is carried
+    permanently, the body loads on trigger, referenced files load on demand;
+    one combined percentage would describe none of them.
+  - **A dominant mover is named beside its total**, because when one subject is
+    most of a change, the total is about that subject and not the population.
+
+  `--fail-on-regression` exits 1 when any subject present in
+  both runs scored lower.
+
+  Measured on the public skills corpus, 2026-07-17 pinned against 2026-09-03
+  HEAD, same ruleset both sides, over the **32 skills `check --skill` pairs**:
+  metadata -0.8%, body +7.5%, referenced files +61.4% with one skill at 96.5%
+  of that movement; grades 0 improved and 4 worsened.
+
+  The population matters and is worth stating, because
+  `research/skills-delta-2026-09-03/REPORT.md` reports body **+7.0%** over
+  **36** paired skills for the same corpus on the same dates. Both are true.
+  `scripts/skills-index.mjs` finds four skills that `check --skill` does not,
+  for the walker reason in Known below, so the two are measuring slightly
+  different populations. Every other figure is identical between them; the
+  body percentage is the one the four missing skills move.
+
+- **`efaimo find` takes several servers**. Pass more than one
+  and their catalogs are merged into one and measured together, each tool
+  labelled with where it came from. A flag-shaped change rather than a new
+  subcommand, because the engine already took a flat tool array and only the
+  CLI surface was single-target.
+
+  The reason it is worth having: a server's author keeps their own tool names
+  apart as a matter of course, nobody coordinates across the several servers a
+  person actually installs, and the model sees one flat list with no
+  indication of origin. A single-server run is structurally unable to see the
+  collision that actually bites.
+
+  The origin is carried for the report and deliberately kept out of the index.
+  Prefixing names with their server would hand every tool a term no other tool
+  has, and a catalog of indistinguishable tools would score a perfect 100.
+  There is a test for exactly that, and it had to be rewritten once: its first
+  origin labels were "server-one" and "server-two", whose only surviving token
+  is "server" for both, so the sabotage it existed to catch passed.
+
+  Measured live on `server-everything@2026.7.4` plus `@playwright/mcp@0.0.78`:
+  37 tools merged, 35 distinct (94.6%). No cross-server collision between
+  those two, which is the right answer for a filesystem server and a browser
+  server, and the two tools owning nothing are playwright's own already
+  documented `browser_close` and `browser_navigate`.
+
+### Fixed
+
+- **S102 no longer passes filler**. The rule read
+  `description.length < 20` and then asked only whether one of four trigger
+  words appeared anywhere, so `Useful for various tasks.` scored a clean
+  A (100) in silence because "for" sits inside "for various tasks". It was
+  testing for the presence of a trigger WORD rather than for the presence of a
+  trigger. A skill whose whole body was one sentence also scored 100.
+
+  Two floors replace it, both grounded on the 38 public skills in
+  `research/skills-index/manifest.json` measured 2026-09-03, where the shortest
+  real description is 68 characters and the thinnest carries 4 distinct content
+  terms: under 40 characters, or fewer than 4 distinct terms surviving the
+  stopword list, is a warning. The second is the same measurement `find` makes
+  on tool catalogs, since a description with no distinguishing content cannot
+  be matched to a task whatever words it contains.
+
+  Impact on the corpus: none. The 38 skills produce zero S102 findings before
+  and after, and the grade distribution is unchanged. This was found by
+  sabotaging the grader while reviewing two new skills, not by a report.
+
+  Note that this changes grades in principle, so it is deliberately sequenced
+  after the 2026-09-03 delta measurement, whose reproduction is pinned to
+  `v0.2.0`.
+
+### Known
+
+- **`check --skill <dir>` does not find every skill under a tree**
+  _(present in 0.2.0 as well)_. It walks
+  `<root>/<name>/SKILL.md` and `<root>/skills/<name>/SKILL.md` but misses skills
+  inside a dot directory (`.claude/skills/<name>/`) and skills one level deeper
+  (`skills/custom_skills/<name>/`). On the corpus above it found 34 where
+  `scripts/skills-index.mjs` found 38, all four in the same repository. Two of
+  this tool's own walkers disagreeing about the same tree is a defect whichever
+  is right; a `--diff` built on the narrower walk silently compares an
+  incomplete population. Not fixed here because the fix is a design decision
+  about depth and dot directories, separate from this change.
+
 ## [0.2.0] - 2026-09-02
 
 ### Added
@@ -258,7 +408,8 @@ First release.
   Documented rule set (`docs/RULES.md`), token methodology (`docs/METHODOLOGY.md`),
   and integration guide (`docs/INTEGRATIONS.md`).
 
-[unreleased]: https://github.com/efaimo-ai/efaimo/compare/v0.2.0...HEAD
+[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
 [0.1.2]: https://github.com/efaimo-ai/efaimo/releases/tag/v0.1.2
 [0.1.1]: https://github.com/efaimo-ai/efaimo/releases/tag/v0.1.1

package/README.md

@@ -58,6 +58,13 @@ instructions, and the median skill's instructions run ~1,632 tokens loaded on
 every trigger. Full report, the corpus manifest, and the two commands that
 reproduce it: [the Skills Quality Index](./research/skills-index/REPORT.md).
 
+That index is a photograph. [Measured twice](./research/skills-delta-2026-09-03/REPORT.md)
+re-runs the same corpus seven weeks later with the same ruleset: the cost that
+sits in context permanently moved -0.8%, the body +7.0%, and referenced files,
+which load out of sight and which no rule here counts, +61.4%. Grades moved one
+way only, 0 improved against 4 worse. The uncomfortable part points inward: the
+two columns this tool has thresholds for are the two that held.
+
 ### Does the skill actually help? (experimental)
 
 Linting tells you a skill is well-formed. It does not tell you the skill makes the
@@ -399,3 +406,7 @@ Built by [efaimo ai](https://efaimo.ai), open tooling for the space between host
 and tools. `efaimo` is the flagship CLI; capabilities grow as subcommands under one
 name. Apache-2.0. See [CONTRIBUTING.md](./CONTRIBUTING.md) and
 [docs/RULES.md](./docs/RULES.md) to add a rule.
+
+EFAIMO AI is a registered trademark of the publisher (KR 40-2585820, class 42).
+The lowercase `efaimo ai` used throughout is the same mark; the package name and
+the commands stay lowercase.

package/SKILL.md

@@ -3,7 +3,7 @@ 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.2.0"
+  version: "0.4.0"
   homepage: "https://efaimo.ai"
 ---
 

package/dist/check/check.js

@@ -85,5 +85,20 @@ export async function checkSkillSet(pathInput, label) {
         return { name, dir: skill.dir, report: buildReport("skill", name, findings, []) };
     });
     const setFindings = set.skills.flatMap((skill) => runRules(setRules, { skill, set, weigh }));
+    // S107 is emitted here rather than by a SkillRule because its subject is a
+    // file that is NOT a skill: no rule that takes a parsed skill could ever see
+    // it. Set level and warn level on purpose, so it moves no grade, matching
+    // how S103 treats a collision that belongs to a pair rather than to either
+    // member.
+    for (const file of set.miscasedSkillFiles ?? []) {
+        setFindings.push({
+            ruleId: "S107",
+            severity: "warn",
+            title: "filename is one capitalisation away from a skill",
+            message: `"${path.relative(set.root, file)}" is not loaded here, because the spec names SKILL.md exactly. A case-insensitive filesystem (the macOS and Windows default) may still hand it to a host, so this can work on a laptop and be missing entirely in Linux CI.`,
+            target: path.relative(set.root, file),
+            fixHint: "rename it to SKILL.md, or delete it if it is not a skill",
+        });
+    }
     return { label, root: set.root, perSkill, setFindings, weigh };
 }

package/dist/check/diff.d.ts

@@ -0,0 +1,124 @@
+/**
+ * What moved between two runs of the same audit.
+ *
+ * Why this exists. Everything else here measures a subject once. Nobody
+ * publishes whether MCP servers and Agent Skills are getting heavier, or
+ * whether their quality holds, because that needs the same thing measured
+ * twice and nothing made that comparison cheap enough to bother. Two pinned
+ * runs is the smallest artifact that can answer it.
+ *
+ * The reason it is a flag on `check` rather than a shell pipeline is that a delta
+ * is exactly the shape a broken measurement takes. Change the ruler between
+ * the two runs and every subject appears to move; pair the wrong items and
+ * everything looks new. Both mistakes produce a plausible number and neither
+ * announces itself, so the controls a careful person would run by hand are
+ * enforced here instead of documented:
+ *
+ * 1. RULES DRIFT IS A HARD STOP. If the two reports carry different
+ *    `rulesVersion` values, a grade that moved cannot be attributed to the
+ *    subject, because the ruler moved too. `--allow-rules-drift` proceeds and
+ *    every grade line is then marked unattributable, which is the honest
+ *    output rather than a silent one.
+ * 2. AN EMPTY PAIRING IS A FAILURE. If nothing pairs, that is not "no
+ *    change", it is two reports about different things, and reporting "0
+ *    changed" would be the same vacuous pass an empty grep gives.
+ * 3. THE THREE TOKEN COSTS ARE NEVER SUMMED. Metadata sits in context
+ *    permanently, the body loads on trigger, referenced files load on demand.
+ *    Adding them produces a single headline percentage that is arithmetically
+ *    true and tells the reader the wrong thing, because almost all of the
+ *    movement usually lives in the column that costs the least to carry.
+ * 4. A DOMINANT MOVER IS NAMED. When one item is most of a total's movement,
+ *    the total describes that item and not the population, so it is called
+ *    out beside the total rather than left for the reader to discover.
+ */
+export interface CheckDiffItem {
+    name: string;
+    score: number;
+    letter: string;
+    errors: number;
+    warns: number;
+    infos: number;
+    ruleIds: string[];
+    metadata?: number;
+    body?: number;
+    referenced?: number;
+}
+export interface CheckEnvelope {
+    tool?: string;
+    version?: string;
+    rulesVersion?: string;
+    kind?: string;
+    data?: unknown;
+}
+export interface GradeMove {
+    name: string;
+    before: {
+        score: number;
+        letter: string;
+    };
+    after: {
+        score: number;
+        letter: string;
+    };
+}
+export interface CostMove {
+    name: string;
+    before: number;
+    after: number;
+    delta: number;
+}
+export interface CostColumn {
+    column: "metadata" | "body" | "referenced";
+    when: string;
+    before: number;
+    after: number;
+    delta: number;
+    pct: number;
+    moved: CostMove[];
+    /** Set when a single item is more than half of the absolute movement. */
+    dominatedBy?: {
+        name: string;
+        delta: number;
+        shareOfMovement: number;
+    };
+}
+export interface CheckDiffResult {
+    kind: string;
+    versions: {
+        before: string;
+        after: string;
+    };
+    rulesVersions: {
+        before?: string;
+        after?: string;
+    };
+    rulesDrift: boolean;
+    paired: number;
+    added: string[];
+    removed: string[];
+    improved: GradeMove[];
+    worsened: GradeMove[];
+    held: number;
+    findingCounts: {
+        before: number;
+        after: number;
+    };
+    costs: CostColumn[];
+    notes: string[];
+}
+export declare class CheckDiffRefused extends Error {
+}
+/**
+ * Both shapes `check` emits, flattened to one list.
+ *
+ * A single target puts the report at `data` itself; a set puts one report per
+ * entry in `data.perSkill` and the token counts in a parallel `data.weigh`
+ * list. Pairing the two lists by name rather than by position matters: they
+ * are built by different passes and nothing guarantees the orders agree, and
+ * a positional join would silently attribute one skill's tokens to another.
+ */
+export declare function flattenCheck(envelope: CheckEnvelope): CheckDiffItem[];
+export interface CheckDiffOptions {
+    allowRulesDrift?: boolean;
+}
+export declare function diffCheck(before: CheckEnvelope, after: CheckEnvelope, opts?: CheckDiffOptions): CheckDiffResult;

package/dist/check/diff.js

@@ -0,0 +1,165 @@
+export class CheckDiffRefused extends Error {
+}
+const asRecord = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+/**
+ * Both shapes `check` emits, flattened to one list.
+ *
+ * A single target puts the report at `data` itself; a set puts one report per
+ * entry in `data.perSkill` and the token counts in a parallel `data.weigh`
+ * list. Pairing the two lists by name rather than by position matters: they
+ * are built by different passes and nothing guarantees the orders agree, and
+ * a positional join would silently attribute one skill's tokens to another.
+ */
+export function flattenCheck(envelope) {
+    const data = asRecord(envelope.data);
+    if (!data)
+        return [];
+    const weighByName = new Map();
+    const weigh = asRecord(data.weigh);
+    if (Array.isArray(weigh?.perSkill)) {
+        for (const w of weigh.perSkill) {
+            const r = asRecord(w);
+            if (r && typeof r.name === "string")
+                weighByName.set(r.name, r);
+        }
+    }
+    const fromReport = (name, report) => {
+        const grade = asRecord(report.grade) ?? {};
+        const counts = asRecord(report.counts) ?? {};
+        const findings = Array.isArray(report.findings) ? report.findings : [];
+        const w = weighByName.get(name);
+        return {
+            name,
+            score: num(grade.score),
+            letter: typeof grade.letter === "string" ? grade.letter : "?",
+            errors: num(counts.error),
+            warns: num(counts.warn),
+            infos: num(counts.info),
+            ruleIds: findings.map((f) => f.ruleId).filter((r) => typeof r === "string"),
+            ...(w
+                ? {
+                    metadata: num(w.metadataTokens),
+                    body: num(w.bodyTokens),
+                    referenced: num(w.refFileTokens),
+                }
+                : {}),
+        };
+    };
+    if (Array.isArray(data.perSkill)) {
+        const out = [];
+        for (const entry of data.perSkill) {
+            const e = asRecord(entry);
+            const report = asRecord(e?.report);
+            const name = typeof e?.name === "string" ? e.name : undefined;
+            if (name && report)
+                out.push(fromReport(name, report));
+        }
+        return out;
+    }
+    const target = typeof data.target === "string" ? data.target : undefined;
+    if (target && asRecord(data.grade))
+        return [fromReport(target, data)];
+    return [];
+}
+export function diffCheck(before, after, opts = {}) {
+    for (const [label, env] of [
+        ["before", before],
+        ["after", after],
+    ]) {
+        if (env.tool !== "efaimo") {
+            throw new CheckDiffRefused(`the ${label} file is not an efaimo report (its "tool" field is ${JSON.stringify(env.tool)}); diff compares two runs of this tool, so pass JSON produced by --json`);
+        }
+    }
+    if (before.kind !== after.kind) {
+        throw new CheckDiffRefused(`these are different kinds of report (${before.kind} and ${after.kind}); comparing them would pair things that are not the same measurement`);
+    }
+    if (before.kind !== "check") {
+        throw new CheckDiffRefused(`diff currently compares "check" reports only, and these are "${before.kind}"; run \`efaimo check ... --json\` at both points`);
+    }
+    const rulesDrift = Boolean(before.rulesVersion && after.rulesVersion && before.rulesVersion !== after.rulesVersion);
+    if (rulesDrift && !opts.allowRulesDrift) {
+        throw new CheckDiffRefused(`the two runs used different rulesets (${before.rulesVersion} and ${after.rulesVersion}). A grade that moved cannot be attributed to the subject, because the ruler moved too. Re-run both points with one version of efaimo, or pass --allow-rules-drift to compare anyway and have every grade line marked unattributable.`);
+    }
+    const b = new Map(flattenCheck(before).map((i) => [i.name, i]));
+    const a = new Map(flattenCheck(after).map((i) => [i.name, i]));
+    const paired = [...b.keys()].filter((k) => a.has(k)).sort();
+    if (!paired.length) {
+        // An empty intersection and "nothing changed" are the same output, and
+        // only one of them is worth printing.
+        throw new CheckDiffRefused(`nothing pairs between the two reports (${b.size} items before, ${a.size} after, 0 in common). That is not "no change", it is two reports about different subjects.`);
+    }
+    const improved = [];
+    const worsened = [];
+    let held = 0;
+    for (const name of paired) {
+        const x = b.get(name);
+        const y = a.get(name);
+        const move = { name, before: { score: x.score, letter: x.letter }, after: { score: y.score, letter: y.letter } };
+        if (y.score > x.score)
+            improved.push(move);
+        else if (y.score < x.score)
+            worsened.push(move);
+        else
+            held++;
+    }
+    const COLUMNS = [
+        ["metadata", "always in context", (i) => i.metadata],
+        ["body", "loads on trigger", (i) => i.body],
+        ["referenced", "loads on demand", (i) => i.referenced],
+    ];
+    const costs = [];
+    for (const [column, when, pick] of COLUMNS) {
+        if (paired.some((n) => pick(b.get(n)) === undefined || pick(a.get(n)) === undefined))
+            continue;
+        const beforeTotal = paired.reduce((s, n) => s + (pick(b.get(n)) ?? 0), 0);
+        const afterTotal = paired.reduce((s, n) => s + (pick(a.get(n)) ?? 0), 0);
+        const moved = paired
+            .map((n) => ({ name: n, before: pick(b.get(n)) ?? 0, after: pick(a.get(n)) ?? 0 }))
+            .filter((m) => m.before !== m.after)
+            .map((m) => ({ ...m, delta: m.after - m.before }))
+            .sort((x, y) => y.delta - x.delta);
+        const totalAbs = moved.reduce((s, m) => s + Math.abs(m.delta), 0);
+        const biggest = [...moved].sort((x, y) => Math.abs(y.delta) - Math.abs(x.delta))[0];
+        const share = biggest && totalAbs ? Math.abs(biggest.delta) / totalAbs : 0;
+        costs.push({
+            column,
+            when,
+            before: beforeTotal,
+            after: afterTotal,
+            delta: afterTotal - beforeTotal,
+            pct: beforeTotal ? ((afterTotal - beforeTotal) / beforeTotal) * 100 : 0,
+            moved,
+            ...(share > 0.5 && biggest
+                ? { dominatedBy: { name: biggest.name, delta: biggest.delta, shareOfMovement: share * 100 } }
+                : {}),
+        });
+    }
+    const notes = [
+        "the three token columns are reported separately on purpose: metadata is carried permanently, the body loads on trigger, and referenced files load on demand, so a single summed percentage would describe none of them",
+    ];
+    if (rulesDrift) {
+        notes.push(`RULES DRIFT ACCEPTED (${before.rulesVersion} -> ${after.rulesVersion}): grade movement below cannot be attributed to the subjects, because the ruleset changed between the two runs`);
+    }
+    if (before.version !== after.version) {
+        notes.push(`the two runs used efaimo ${before.version} and ${after.version}; the rulesets matched, so grades are comparable, but token counts can move if the tokenizer or the walk changed`);
+    }
+    return {
+        kind: before.kind,
+        versions: { before: before.version ?? "?", after: after.version ?? "?" },
+        rulesVersions: { before: before.rulesVersion, after: after.rulesVersion },
+        rulesDrift,
+        paired: paired.length,
+        added: [...a.keys()].filter((k) => !b.has(k)).sort(),
+        removed: [...b.keys()].filter((k) => !a.has(k)).sort(),
+        improved,
+        worsened,
+        held,
+        findingCounts: {
+            before: [...b.values()].reduce((s, i) => s + i.errors + i.warns + i.infos, 0),
+            after: [...a.values()].reduce((s, i) => s + i.errors + i.warns + i.infos, 0),
+        },
+        costs,
+        notes,
+    };
+}

package/dist/cli.js

@@ -11,11 +11,12 @@ import { SPEC_VERSION } from "./clients/rawprobe.js";
 import { weighServer, weighSkills } from "./weigh/weigh.js";
 import { findSkills } from "./skills/parse.js";
 import { diffServerWeigh } from "./weigh/diff.js";
+import { diffCheck, CheckDiffRefused } from "./check/diff.js";
 import { DEFAULT_CONTEXT_WINDOW, formatWindowShare, setContextWindow } from "./weigh/window.js";
 import { checkMcpRepoOnly, checkMcpTarget, checkSkillSet } from "./check/check.js";
 import { analyzeFind, DEFAULT_TOP_K } from "./find/find.js";
 import { runFindRules } from "./core/engine.js";
-import { renderCheckPretty, renderDiffPretty, renderFindFindingsPretty, renderFindPretty, renderScenarioPlan, renderServerWeighPretty, renderSkillSetPretty, renderSkillWeighPretty, renderTestReportPretty, setColor, } from "./reporters/pretty.js";
+import { renderCheckPretty, renderDiffPretty, renderFindFindingsPretty, renderFindPretty, renderScenarioPlan, renderServerWeighPretty, renderSkillSetPretty, renderSkillWeighPretty, renderTestReportPretty, setColor, renderCheckDiffPretty, } from "./reporters/pretty.js";
 import { parseScenario, runScenario } from "./testing/harness.js";
 import { acceptsSamplingParams, anthropicRunner } from "./testing/anthropicRunner.js";
 import { openaiRunner, providerForModel } from "./testing/openaiRunner.js";
@@ -303,6 +304,10 @@ program
     .option("--md", "print Markdown")
     .option("--no-timestamp", NO_TIMESTAMP_HELP)
     .option("--badge [file]", "write a grade badge SVG + shields endpoint JSON")
+    .option("--out <file>", "write the JSON result to a file (usable as a --diff baseline)")
+    .option("--diff <baseline>", "compare against a baseline JSON from --out")
+    .option("--allow-rules-drift", "let --diff proceed when the two runs used different rulesets (grade movement is then unattributable)")
+    .option("--fail-on-regression", "with --diff, exit 1 if any subject present in both runs scored lower")
     .option("--anthropic [model]", "use exact Claude token counts where relevant")
     .option("--window <tokens>", "context window the share is reported against", String(DEFAULT_CONTEXT_WINDOW))
     .option("--no-color", "disable colors")
@@ -348,7 +353,46 @@ program
         });
         report = res.report;
     }
+    // A baseline is written unstamped for the same reason weigh's is: a file
+    // that differs on every write is the one field a comparison must ignore,
+    // and a committed baseline that diffs on nothing but the clock trains
+    // reviewers to skim the file they should be reading. The whole envelope is
+    // written rather than just its data, because the version and rulesVersion
+    // in it are what make the later comparison trustworthy.
+    const baselineAndDiff = (payload) => {
+        if (opts.out) {
+            fs.writeFileSync(opts.out, toJsonEnvelope("check", payload, { timestamp: false }));
+            console.error(pc.dim(`baseline written: ${opts.out}`));
+        }
+        if (!opts.diff)
+            return;
+        let baseline;
+        try {
+            baseline = JSON.parse(fs.readFileSync(opts.diff, "utf8"));
+        }
+        catch (e) {
+            fail(`could not read the baseline "${opts.diff}": ${e.message}`);
+            return;
+        }
+        const current = JSON.parse(toJsonEnvelope("check", payload, { timestamp: false }));
+        try {
+            const d = diffCheck(baseline, current, { allowRulesDrift: opts.allowRulesDrift });
+            console.log("");
+            console.log(renderCheckDiffPretty(d));
+            if (opts.failOnRegression && d.worsened.length)
+                process.exitCode = 1;
+        }
+        catch (e) {
+            // Every refusal here is a comparison that would have produced a
+            // plausible number from incomparable inputs, so it stops rather than
+            // printing one.
+            if (e instanceof CheckDiffRefused)
+                fail(e.message);
+            throw e;
+        }
+    };
     if (skillSet) {
+        baselineAndDiff(skillSet);
         if (opts.json)
             console.log(toJsonEnvelope("check", skillSet, envelopeOpts(opts)));
         else if (opts.md)
@@ -365,6 +409,7 @@ program
     }
     if (!report)
         return;
+    baselineAndDiff(report);
     if (opts.json)
         console.log(toJsonEnvelope("check", report, envelopeOpts(opts)));
     else if (opts.md)
@@ -424,7 +469,7 @@ program
 program
     .command("find")
     .description("would a search surface these tools? (findability under deferred tool loading)")
-    .argument("[target]", "stdio command | http(s) URL")
+    .argument("[targets...]", "one or more MCP servers: stdio command | http(s) URL. Two or more are merged into one catalog and measured together")
     .option("--stdio", "treat target as a stdio command string")
     .option("--header <header>", 'HTTP header "Key: Value" (repeatable)', collectPairs(":"))
     .option("--env <pair>", "KEY=VALUE for stdio servers (repeatable)", collectPairs("="))
@@ -440,10 +485,15 @@ program
     "the catalog: a tool that owns no word the others lack cannot be matched by any query that does not\n" +
     "also match a competitor. `probe` is a simulated BM25 search, offline and deterministic, and it\n" +
     "saturates on well-formed catalogs, so it is a floor test rather than a ranking.\n" +
+    "Pass more than one server and their catalogs are MERGED and measured together, with each tool\n" +
+    "labelled by where it came from. That is the case worth checking: a server author keeps their own\n" +
+    "names apart, nobody coordinates across the several servers a person installs, and the model sees\n" +
+    "one flat list. A single-server run is structurally unable to see a collision between two of them.\n" +
     "No API key, no network beyond connecting to the server. docs/METHODOLOGY.md has the method.")
-    .action(async (targetArg, opts) => {
+    .action(async (targetArgs, opts) => {
     colorSetup(opts);
-    if (!targetArg)
+    const args = targetArgs ?? [];
+    if (!args.length)
         fail("nothing to search: pass an MCP server (stdio command or URL)");
     const timeoutMs = seconds(opts.timeout) * 1000;
     const topK = parseNumberOpt(opts.top, "--top", { min: 1 }) ?? DEFAULT_TOP_K;
@@ -456,20 +506,45 @@ program
     const minDistinct = parseNumberOpt(opts.minDistinct, "--min-distinct", { min: 0 });
     if (minDistinct !== undefined && minDistinct > 100)
         fail(`--min-distinct is a percentage, got "${opts.minDistinct}"`);
-    const target = resolveTarget(targetArg, { forceStdio: opts.stdio, env: opts.env, headers: opts.header });
-    if (target.kind === "skillset" || target.kind === "repo") {
-        fail(`"${target.label}" is a ${target.kind === "skillset" ? "skill path" : "source directory"}; find needs a live MCP server (stdio command or URL). ` +
-            `Skills have no searchable tool catalog; their trigger-overlap check is S103 in \`efaimo check --skill\`.`);
+    const targets = args
+        .map((a) => resolveTarget(a, { forceStdio: opts.stdio, env: opts.env, headers: opts.header }))
+        .map((target) => {
+        if (target.kind === "skillset" || target.kind === "repo") {
+            fail(`"${target.label}" is a ${target.kind === "skillset" ? "skill path" : "source directory"}; find needs a live MCP server (stdio command or URL). ` +
+                `Skills have no searchable tool catalog; their trigger-overlap check is S103 in \`efaimo check --skill\`.`);
+            throw new Error("unreachable");
+        }
+        return target;
+    });
+    // Several servers are merged into ONE catalog rather than measured one at
+    // a time, because the failure worth finding only exists between them. A
+    // server's author keeps their own tool names apart as a matter of course;
+    // nobody coordinates across the five or ten servers a person actually
+    // installs, and the model sees all of them as one flat list with no
+    // indication of which came from where. Measuring them separately would
+    // report every catalog as tidy and miss exactly the collision that makes a
+    // model pick the wrong tool.
+    //
+    // The origin is attached for the report and NOT for the index. Prefixing
+    // names with their server would hand every tool a term no other tool has,
+    // and a catalog of indistinguishable tools would score a perfect 100.
+    let tools = [];
+    let definitionTokens = 0;
+    for (const target of targets) {
+        console.error(pc.dim(`connecting to ${target.label} ...`));
+        const intro = await introspectServer(target, { timeoutMs });
+        // Weighed only to answer one question: is this catalog big enough that a
+        // host would defer it. No API key is involved; the count is the local
+        // o200k estimate the rest of the tool uses.
+        const w = await weighServer(intro);
+        definitionTokens += w.totals.claudeStyle;
+        tools = tools.concat(targets.length > 1 ? intro.tools.map((tool) => ({ ...tool, origin: target.label })) : intro.tools);
     }
-    console.error(pc.dim(`connecting to ${target.label} ...`));
-    const intro = await introspectServer(target, { timeoutMs });
-    // Weighed only to answer one question: is this catalog big enough that a
-    // host would defer it. No API key is involved; the count is the local
-    // o200k estimate the rest of the tool uses.
-    const weigh = await weighServer(intro);
-    const result = analyzeFind(target.label, intro.tools, {
+    const label = targets.length === 1 ? targets[0].label : `${targets.length} servers`;
+    const result = analyzeFind(label, tools, {
         topK,
-        definitionTokens: weigh.totals.claudeStyle,
+        definitionTokens,
+        sources: targets.map((x) => x.label),
     });
     const findings = runFindRules({ find: result });
     if (opts.json) {

package/dist/core/types.d.ts

@@ -26,6 +26,17 @@ export interface ToolDef {
     inputSchema?: unknown;
     outputSchema?: unknown;
     annotations?: Record<string, unknown>;
+    /**
+     * Which server this tool came from, when several are analysed together.
+     *
+     * DISPLAY ONLY. It is deliberately absent from `indexedTerms`, and putting
+     * it there would be the same bug the query builder already documents: a
+     * per-server token has maximal idf, so prefixing names with their origin
+     * would hand every tool a word no other tool has and report a catalog of
+     * indistinguishable tools as perfectly distinct. The measurement has to see
+     * exactly what a model sees, which is a flat list with no origin attached.
+     */
+    origin?: string;
 }
 export interface ResourceDef {
     uri: string;
@@ -188,6 +199,8 @@ export type WeighResult = ServerWeighResult | SkillSetWeighResult;
 /** One tool's result in the findability report (`efaimo find`). */
 export interface ToolFindEntry {
     name: string;
+    /** The server this tool came from, when more than one was analysed. */
+    origin?: string;
     /**
      * Terms this tool has that no other tool in the catalog has.
      *
@@ -247,6 +260,16 @@ export interface FindResult {
         topK: number;
     };
     perTool: ToolFindEntry[];
+    /**
+     * The servers whose catalogs were merged, when more than one.
+     *
+     * Present only for a stack. A single server's author avoids collisions
+     * inside their own catalog as a matter of course, so a one-server run is
+     * structurally unable to see the failure that actually bites: two servers
+     * installed side by side, each internally tidy, exposing tools a model
+     * cannot tell apart.
+     */
+    sources?: string[];
     /**
      * The headline: how many tools own at least one word no other tool has.
      * A measured proportion, deliberately not a letter grade (ADR-030).
@@ -316,6 +339,24 @@ export interface SkillInfo {
 export interface SkillSet {
     root: string;
     skills: SkillInfo[];
+    /**
+     * Directories the walk refused to enter because it hit its depth bound.
+     *
+     * Present only when the bound actually bit. A truncated search that reports
+     * a short list and no reason is the same failure as a check that examines
+     * nothing, so the caller is given the means to say what it did not look at.
+     */
+    truncatedAt?: string[];
+    /**
+     * Files one capitalisation away from being a skill, such as `skill.md`.
+     *
+     * The spec names `SKILL.md` exactly and discovery matches it exactly, so
+     * these are not skills here on any platform. They may still be skills to a
+     * host reading a case-insensitive filesystem, which is the default on macOS
+     * and Windows, so the same repository can work on a laptop and have no
+     * skills at all in Linux CI. Reported by S107.
+     */
+    miscasedSkillFiles?: string[];
 }
 export interface GradeInfo {
     score: number;

package/dist/find/find.d.ts

@@ -112,6 +112,8 @@ export declare function indexedTerms(tool: ToolDef): string[];
  */
 export declare function taskQuery(tool: ToolDef, index: Bm25Index, limit?: number): string[];
 export interface FindOptions {
+    /** Labels of the servers merged into this catalog, when more than one. */
+    sources?: string[];
     topK?: number;
     queryTerms?: number;
     /** Claude-style tool-definition tokens, used only to say whether deferral is likely. */

package/dist/find/find.js

@@ -312,6 +312,7 @@ export function analyzeFind(label, tools, opts = {}) {
             : [];
         return {
             name: tool.name,
+            ...(tool.origin ? { origin: tool.origin } : {}),
             ownTerms: own.slice(0, 4),
             ownTermCount: own.length,
             ownOutsideNameCount: ownOutsideName.length,
@@ -380,6 +381,7 @@ export function analyzeFind(label, tools, opts = {}) {
     return {
         kind: "find",
         label,
+        ...(opts.sources && opts.sources.length > 1 ? { sources: opts.sources } : {}),
         toolCount: tools.length,
         method: { tokenizer: "efaimo-v1", bm25: { ...DEFAULT_BM25 }, queryTerms, topK },
         perTool,

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { loadClientServers, SUPPORTED_CLIENTS } from "./targets/clientConfigs.js
 export { introspectServer } from "./clients/introspect.js";
 export { weighServer, weighSkills } from "./weigh/weigh.js";
 export { diffServerWeigh, type WeighDiff } from "./weigh/diff.js";
+export { diffCheck, flattenCheck, CheckDiffRefused, type CheckDiffResult, type CheckDiffItem } from "./check/diff.js";
 export { countTokens } from "./weigh/tokens.js";
 export { findSkills, parseSkillFile } from "./skills/parse.js";
 export { analyzeFind, indexedTerms, taskQuery, DEFAULT_TOP_K, DEFAULT_QUERY_TERMS, DEFER_RECOMMENDED_TOKENS, DEFER_RECOMMENDED_TOOLS, type FindOptions } from "./find/find.js";

package/dist/index.js

@@ -11,6 +11,7 @@ export { loadClientServers, SUPPORTED_CLIENTS } from "./targets/clientConfigs.js
 export { introspectServer } from "./clients/introspect.js";
 export { weighServer, weighSkills } from "./weigh/weigh.js";
 export { diffServerWeigh } from "./weigh/diff.js";
+export { diffCheck, flattenCheck, CheckDiffRefused } from "./check/diff.js";
 export { countTokens } from "./weigh/tokens.js";
 // Skills
 export { findSkills, parseSkillFile } from "./skills/parse.js";

package/dist/reporters/pretty.d.ts

@@ -2,6 +2,7 @@ import type { CheckReport, Finding, FindResult, ServerWeighResult, SkillSetWeigh
 import type { CheckSkillResult } from "../check/check.js";
 import type { Scenario, TestReport } from "../testing/harness.js";
 import type { WeighDiff } from "../weigh/diff.js";
+import type { CheckDiffResult } from "../check/diff.js";
 export declare function setColor(on: boolean): void;
 export declare function renderCheckPretty(report: CheckReport): string;
 export declare function renderScenarioPlan(s: Scenario): string;
@@ -24,3 +25,15 @@ export declare function renderDiffPretty(d: WeighDiff, opts: {
     maxTokens?: number;
     allowIncreasePct?: number;
 }): string;
+/**
+ * What moved between two `check` runs.
+ *
+ * The three token columns stay in three rows on purpose. Summing them gives a
+ * single percentage that is arithmetically true and describes none of the
+ * three costs, because metadata is carried permanently while referenced files
+ * load only on demand, and in practice almost all movement lands in the column
+ * that costs the least to hold. A dominant mover is printed beside its total
+ * for the same reason: when one subject is most of a change, the total is
+ * about that subject rather than about the population.
+ */
+export declare function renderCheckDiffPretty(d: CheckDiffResult): string;

package/dist/reporters/pretty.js

@@ -290,6 +290,11 @@ export function renderFindPretty(f) {
     });
     const shown = byWorst.slice(0, 15);
     const nameW = Math.min(34, Math.max(12, ...shown.map((t) => cell(t.name).length)));
+    if (f.sources && f.sources.length > 1) {
+        // The whole point of a stack run is which server a colliding tool came
+        // from, so it goes beside the name rather than into a footnote.
+        lines.push(paint(pc.dim, `  merged ${f.sources.length} catalogs: ${f.sources.join(", ")}`));
+    }
     lines.push(paint(pc.dim, `  words  ${"tool".padEnd(nameW)}  vocabulary no other tool has`));
     for (const t of shown) {
         const count = t.ownTermCount === 0
@@ -313,7 +318,8 @@ export function renderFindPretty(f) {
             : t.reachable
                 ? ""
                 : paint(pc.red, `   [probe: rank ${t.rank}]`);
-        lines.push(`  ${count}  ${cell(t.name).padEnd(nameW)}  ${tail}${probe}`);
+        const from = t.origin ? paint(pc.dim, `  [${t.origin}]`) : "";
+        lines.push(`  ${count}  ${cell(t.name).padEnd(nameW)}  ${tail}${probe}${from}`);
     }
     // Describe the hidden rows from the hidden rows, never from an assumption.
     // This line used to read "(+N more, each owning at least one word)" without
@@ -397,3 +403,51 @@ export function renderDiffPretty(d, opts) {
     }
     return lines.join("\n");
 }
+/**
+ * What moved between two `check` runs.
+ *
+ * The three token columns stay in three rows on purpose. Summing them gives a
+ * single percentage that is arithmetically true and describes none of the
+ * three costs, because metadata is carried permanently while referenced files
+ * load only on demand, and in practice almost all movement lands in the column
+ * that costs the least to hold. A dominant mover is printed beside its total
+ * for the same reason: when one subject is most of a change, the total is
+ * about that subject rather than about the population.
+ */
+export function renderCheckDiffPretty(d) {
+    const lines = [];
+    lines.push(paint(pc.dim, `efaimo v${VERSION}`));
+    const rules = d.rulesVersions.before ?? "?";
+    lines.push(`diff check  ${paint(pc.bold, `${d.paired} paired`)}${d.added.length ? `, ${d.added.length} added` : ""}${d.removed.length ? `, ${d.removed.length} removed` : ""}`);
+    lines.push(paint(pc.dim, d.rulesDrift
+        ? `efaimo ${d.versions.before} -> ${d.versions.after}, rules ${d.rulesVersions.before} -> ${d.rulesVersions.after}  DRIFTED`
+        : `efaimo ${d.versions.before} -> ${d.versions.after}, rules ${rules} on both sides`));
+    lines.push("");
+    const sign = (n) => (n > 0 ? `+${n.toLocaleString("en-US")}` : n.toLocaleString("en-US"));
+    const pct = (n) => `${n > 0 ? "+" : ""}${n.toFixed(1)}%`;
+    lines.push(paint(pc.bold, "grades"));
+    if (d.rulesDrift) {
+        lines.push(`  ${paint(pc.yellow, "unattributable")}: the ruleset changed between the runs, so a moved grade may be the ruler`);
+    }
+    const g = (m) => `  ${m.name.padEnd(34)} ${m.before.letter} (${m.before.score}) -> ${m.after.letter} (${m.after.score})`;
+    for (const m of d.improved)
+        lines.push(paint(pc.green, g(m)));
+    for (const m of d.worsened)
+        lines.push(paint(pc.red, g(m)));
+    lines.push(paint(pc.dim, `  improved ${d.improved.length}   worsened ${d.worsened.length}   held ${d.held}   findings ${d.findingCounts.before} -> ${d.findingCounts.after}`));
+    lines.push("");
+    if (d.costs.length) {
+        lines.push(paint(pc.bold, "token cost, by when it loads"));
+        for (const c of d.costs) {
+            const color = c.delta > 0 ? pc.yellow : c.delta < 0 ? pc.green : pc.dim;
+            lines.push(`  ${c.column.padEnd(11)} ${paint(pc.dim, `(${c.when})`.padEnd(20))} ${String(c.before.toLocaleString("en-US")).padStart(9)} -> ${String(c.after.toLocaleString("en-US")).padStart(9)}  ${paint(color, pct(c.pct))}`);
+            if (c.dominatedBy) {
+                lines.push(paint(pc.dim, `              ${c.dominatedBy.name} is ${c.dominatedBy.shareOfMovement.toFixed(1)}% of that movement (${sign(c.dominatedBy.delta)}); the total describes it, not the rest`));
+            }
+        }
+        lines.push("");
+    }
+    for (const n of d.notes)
+        lines.push(paint(pc.dim, `  ${n}`));
+    return lines.join("\n");
+}

package/dist/rules/skill/index.js

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

package/dist/skills/parse.d.ts

@@ -1,4 +1,10 @@
 import type { SkillInfo, SkillSet } from "../core/types.js";
 export declare function parseSkillFile(file: string): SkillInfo;
 /** Resolve a path (SKILL.md file, skill dir, or a directory of skills) into a SkillSet. */
+/**
+ * How deep skill discovery walks. See the note inside `findSkills`: measured
+ * against the public corpus, where the deepest real skill is four directories
+ * below a directory of repositories.
+ */
+export declare const SKILL_WALK_MAX_DEPTH = 6;
 export declare function findSkills(input: string): SkillSet;

package/dist/skills/parse.js

@@ -129,6 +129,12 @@ export function parseSkillFile(file) {
     return base;
 }
 /** Resolve a path (SKILL.md file, skill dir, or a directory of skills) into a SkillSet. */
+/**
+ * How deep skill discovery walks. See the note inside `findSkills`: measured
+ * against the public corpus, where the deepest real skill is four directories
+ * below a directory of repositories.
+ */
+export const SKILL_WALK_MAX_DEPTH = 6;
 export function findSkills(input) {
     const abs = path.resolve(input);
     const stat = fs.statSync(abs);
@@ -139,11 +145,49 @@ export function findSkills(input) {
     if (fs.existsSync(direct)) {
         return { root: abs, skills: [parseSkillFile(direct)] };
     }
+    // Discovery is deliberate rather than incidental, because two walkers with
+    // different rules is what produced the 2026-09-03 defect: this found 34
+    // skills in a corpus where `scripts/skills-index.mjs` found 38, and both
+    // reported their own number with confidence.
+    //
+    // maxDepth 6 is measured, not picked. In the public corpus the deepest real
+    // skill sits 4 directories below a directory-of-repositories
+    // (`<corpus>/<repo>/skills/custom_skills/<name>/SKILL.md`) and 3 below a
+    // repository root. Six leaves two levels of headroom and keeps an accidental
+    // `check --skill /` from walking a disk. When the bound does bite it is
+    // reported rather than swallowed, in `truncatedAt`.
+    //
+    // Dot directories are entered here and nowhere else in this codebase:
+    // `.claude/skills/<name>/` is where a project keeps its own skills, so
+    // skipping them made this blind to the most common real layout. `.git` is
+    // still excluded by DEFAULT_SKIP_DIRS.
     const skills = [];
-    for (const f of walkFiles(abs, { maxDepth: 3 })) {
-        if (path.basename(f) === "SKILL.md")
+    const truncatedAt = [];
+    const miscased = [];
+    for (const f of walkFiles(abs, {
+        maxDepth: SKILL_WALK_MAX_DEPTH,
+        includeDotDirs: true,
+        onDepthLimit: (d) => truncatedAt.push(d),
+    })) {
+        const base = path.basename(f);
+        if (base === "SKILL.md")
             skills.push(parseSkillFile(f));
+        // A file that is only a capitalisation away from being a skill. The spec
+        // names SKILL.md exactly, and this comparison is exact, so `skill.md` is
+        // invisible here on every platform. It is not invisible everywhere: a
+        // case-insensitive filesystem, which is the default on macOS and Windows,
+        // may hand it to a host that opens it by name, so the same repository has
+        // a working skill on the author's laptop and no skill at all in Linux CI.
+        // Nothing else in this tool would ever mention it, which is the worst
+        // property a near miss can have.
+        else if (base.toLowerCase() === "skill.md")
+            miscased.push(f);
     }
     skills.sort((a, b) => a.file.localeCompare(b.file));
-    return { root: abs, skills };
+    return {
+        root: abs,
+        skills,
+        ...(truncatedAt.length ? { truncatedAt } : {}),
+        ...(miscased.length ? { miscasedSkillFiles: miscased.sort() } : {}),
+    };
 }

package/dist/util/misc.d.ts

@@ -3,10 +3,28 @@ export declare function parseCommandString(input: string): {
     command: string;
     args: string[];
 };
-export declare function walkFiles(root: string, opts?: {
+export interface WalkOptions {
     maxDepth?: number;
     skipDirs?: Set<string>;
-}): Generator<string>;
+    /**
+     * Descend into directories whose name starts with a dot.
+     *
+     * Off by default, because most of them are caches and metadata. On for skill
+     * discovery, because `.claude/skills/<name>/` is where a project keeps its
+     * own skills and a tool that cannot see the most common real layout is not
+     * auditing anything. `DEFAULT_SKIP_DIRS` still excludes `.git`.
+     */
+    includeDotDirs?: boolean;
+    /**
+     * Called once for each directory not entered because `maxDepth` was reached.
+     *
+     * A bound that truncates in silence is the same failure as a check that
+     * examines nothing: the caller sees a short list and no reason for it. This
+     * lets the caller say so.
+     */
+    onDepthLimit?: (dir: string) => void;
+}
+export declare function walkFiles(root: string, opts?: WalkOptions): Generator<string>;
 export declare function readTextSafe(file: string, maxBytes?: number): string | undefined;
 export declare function isBinaryPath(file: string): boolean;
 export declare function extractVersion(s: string): number[] | undefined;

package/dist/util/misc.js

@@ -59,9 +59,15 @@ export function* walkFiles(root, opts = {}) {
         for (const e of entries) {
             const full = path.join(dir, e.name);
             if (e.isDirectory()) {
-                if (depth < maxDepth && !skip.has(e.name) && !e.name.startsWith(".")) {
-                    stack.push({ dir: full, depth: depth + 1 });
+                if (skip.has(e.name))
+                    continue;
+                if (!opts.includeDotDirs && e.name.startsWith("."))
+                    continue;
+                if (depth >= maxDepth) {
+                    opts.onDepthLimit?.(full);
+                    continue;
                 }
+                stack.push({ dir: full, depth: depth + 1 });
             }
             else if (e.isFile()) {
                 yield full;

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

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Kept in sync with package.json by test/meta.test.ts. */
-export const VERSION = "0.2.0";
+export const VERSION = "0.4.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-S106)
+## Skills (S101-S107)
 
 | id | sev | what it catches | spec |
 |---|---|---|---|
@@ -75,6 +75,7 @@ never reused, so a gap is permanent and is better stated than smoothed over.
 | 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). **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 |
 
 ## Findability (E141-E145)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "efaimo",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Audit what your agent loads: quality and context cost for MCP servers and Agent Skills",
   "keywords": [
     "mcp",
@@ -58,6 +58,8 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "preflight": "node scripts/preflight.mjs",
+    "preflight:fast": "node scripts/preflight.mjs --fast",
     "spec:drift": "node scripts/spec-drift.mjs",
     "test:watch": "vitest",
     "prepublishOnly": "npm run typecheck && npm run build && npm run test"