efaimo 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -4,7 +4,102 @@ 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/).
 
-## [Unreleased]
+## [0.1.1] - 2026-08-02
+
+Everything below was on `main` and unpublished. That gap was itself the
+problem: `efaimo@0.1.0` still tells every user "the spec finalizes
+2026-07-28" (a future tense about a date that has passed), the README
+documents `--strict-readiness` and `--window`, and neither flag exists in
+0.1.0. Cutting this release is what makes the documentation true.
+
+The MCP specification published on 2026-07-28. The readiness rules here had
+been written against the Release Candidate locked 2026-05-21, and the two are
+not the same document: `DiscoverResult.serverInfo` was deleted,
+`DiscoverResult` became cacheable, and three error codes were renumbered. The
+entries below that name the published spec are the repairs, plus the tooling
+that notices the next revision by itself.
+
+### Security
+
+- `--client` now prints the actual command of every server it is about to
+  spawn, and warns by name when a config came from the CURRENT DIRECTORY
+  rather than your user config. It reads `.mcp.json`, `.cursor/mcp.json` and
+  `.vscode/mcp.json` from the working directory and executes what it finds, so
+  running the audit inside a repository you cloned was arbitrary code
+  execution, announced only by a friendly config key.
+- Terminal control characters are stripped from anything the audited target
+  supplied, at the render boundary of the pretty and markdown reporters. A
+  hostile server could put ESC[1A ESC[2K in a tool name and rewrite the grade
+  line printed above its own finding, so the reader saw "grade A (100), 0
+  errors" while the contradiction was erased. `--no-color` did not help; that
+  only suppresses colours efaimo adds.
+- `.env` loading is restricted to `ANTHROPIC_API_KEY` and `OPENAI_API_KEY`.
+  It previously set ANY key from a working-directory `.env`, so a cloned
+  repository could set `NODE_TLS_REJECT_UNAUTHORIZED=0` and silently disable
+  certificate verification for later HTTPS calls, including ones carrying your
+  key.
+- Skill references that resolve outside the skill directory are no longer read
+  by `weigh`. S106 already warned about them, but only after the read.
+- `SKILL.md` is read through the same 512KB-class cap as referenced files
+  (2MB), instead of an uncapped read.
+- The published composite Action no longer interpolates its inputs into a bash
+  `run:` body, which was script injection in the consumer's runner.
+
+### Added
+
+- `check --strict-readiness`: exit non-zero when the 2026-07-28 migration diff
+  is not clean. Readiness still never touches the grade or the badge, and the
+  default exit code is unchanged. It exists because a team that had finished
+  migrating had no way to stay migrated: `--strict` covers quality only, so
+  nothing in CI could catch a regression back onto the legacy handshake.
+- `--window <tokens>` on `weigh` and `check`: report the context-window share
+  against a window you name instead of the 1,000,000-token default. Absolute
+  token counts do not change; only the denominator does.
+- `npm run spec:drift`, plus a daily `spec-drift` workflow: fails when an MCP
+  revision newer than the one efaimo targets publishes, or when the targeted
+  revision changes under its own tag. The 2026-07-28 publication went unnoticed
+  in this repo for four days because nothing watched the spec itself.
+
+### Changed
+
+- `check --conformance` pins `@modelcontextprotocol/conformance@0.2.0-alpha.10`
+  rather than the floating `alpha` tag, which had moved off `alpha.9` on
+  2026-07-27. A dist-tag is not a pin, and the old one meant reporting "the
+  official conformance suite" for a build nobody here had run.
+- Readiness output no longer claims the spec "finalizes 2026-07-28". It has
+  published; the diff still prints ungraded.
+- Rule detail lines name the revision by its date instead of calling it "the
+  RC", which it no longer is.
+
+### Fixed
+
+- `efaimo test` reports a two-sided Fisher exact p and a 95% interval, and
+  `helps`/`hurts` require p < 0.05. The old rule was a +-15 point threshold at
+  a default of 5 trials per arm, where 5/5 against 4/5 is +20 points and
+  p = 1.0000. Judge now runs at temperature 0; an unparseable judge verdict is
+  excluded rather than scored FAIL; default trials 5 -> 20.
+- E123 fires. The matcher was `(delete|...)` and `_` is a word character,
+  so `delete_file`, `deleteFile` and `drop_table` never matched: the rule was
+  dead for every conventionally named tool.
+- A rule that throws is reported as an ungraded E000 instead of being silently
+  swallowed, which used to RAISE the grade.
+- `weigh`'s heaviest-tools column derives its width from the rows printed, so
+  a 30-character tool name no longer shifts the number column.
+- The median in `scripts/skills-index.mjs` is the true median.
+- `check --mcp` could hang forever on a stdio server. The readiness probes
+  cleaned up their spawned servers only on the happy path, so a probe that threw
+  left the child's stdin open; the child never saw EOF, never exited, and its
+  stdio handles kept the CLI's event loop alive. The report printed and then the
+  process simply never returned. Cleanup now runs in a `finally`, matching the
+  stateless introspection path next door, which already did.
+- `check --mcp` and `weigh` lost server identity on servers that had finished
+  migrating. The published spec deleted `DiscoverResult.serverInfo` and moved
+  identity into `_meta["io.modelcontextprotocol/serverInfo"]`, and efaimo read
+  only the Release Candidate's field. Both shapes are read now, newest first.
+- E118 measured cache fields on `tools/list` only, while its own detail line
+  already listed `server/discover`. The published spec made `DiscoverResult`
+  extend `CacheableResult`, so that surface is required now, is measured now,
+  and the message names whichever surface failed.
 
 ## [0.1.0]
 
@@ -43,5 +138,5 @@ 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.1.0...HEAD
+[0.1.1]: https://github.com/efaimo-ai/efaimo/releases/tag/v0.1.1
 [0.1.0]: https://github.com/efaimo-ai/efaimo/releases/tag/v0.1.0

package/README.md

@@ -21,8 +21,8 @@ fires at all. Good tools exist for single slices of that problem; efaimo's job i
 the whole audit in one command, for both halves of what an agent loads. Lint a
 skill, weigh a server's tool definitions, get a migration diff for the 2026-07-28
 stateless MCP spec, and measure whether a skill actually improves task completion
-([SkillsBench](https://www.skillsbench.ai) found 16 of 84 curated skills making
-agents worse; linting alone cannot catch that).
+([SkillsBench](https://www.skillsbench.ai) found curated skills made agents
+worse on 16 of 84 tasks; linting alone cannot catch that).
 
 ## Agent Skills
 
@@ -35,11 +35,11 @@ Point it at one skill or a whole folder. It validates each skill against the
 
 ```text
 check skill  claude-api
-grade C (71)   1 error  2 warnings  4 info
+grade C (73)   1 error  2 warnings  4 info
 
   x S101  description is 1068 chars (spec max 1024)
   ! S104  instructions are ~18.4k tokens (spec recommends staying under 5k)
-          fix: move detail into references/ files loaded on demand
+          fix: move detail into references/ files loaded on demand (progressive disclosure)
   ! S104  SKILL.md is 570 lines (spec recommends under 500)
   i S104  metadata level is ~294 tokens; the spec targets ~100 and this loads at
           startup for every installed skill
@@ -54,7 +54,7 @@ hygiene. Run it on a folder and every skill gets its own grade, not one aggregat
 `anthropics/claude-cookbooks`, and `obra/superpowers`, at pinned commits. 97%
 score an A, but even this curated set has real issues: Anthropic's own
 `claude-api` scores a C with an over-limit description and ~18k-token
-instructions, and the median skill's instructions run ~1,700 tokens loaded on
+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).
 
@@ -103,9 +103,19 @@ test  contoso-crm-import helps on an unknowable format
 </details>
 
 The first is pure context overhead, the second earns its tokens, and only the
-trial data tells them apart. Experimental and probabilistic: raise the trial
-count for confidence, and treat small deltas as noise. It is opt-in because a
-live run spends tokens on your key. See
+trial data tells them apart.
+
+The verdict is a significance test, not a threshold on the gap. Every run
+reports a two-sided Fisher exact `p` and a 95% interval on the delta, and
+`helps` / `hurts` require `p < 0.05`; anything else is `no measurable effect`
+no matter how large the gap looks. That matters more than it sounds: at the
+old default of 5 trials per arm, 5/5 against 4/5 is +20 points and a `p` of
+exactly 1.0000, and the previous rule called it `helps`. The `+100` run above
+is `p = 0.0002`; a `+25` run at 8 trials per arm is `p = 0.47` and now says so.
+The default is 20 trials per arm, because below about that a partial result
+cannot reach significance at all.
+
+It is opt-in because a live run spends tokens on your key. See
 [examples/scenario.example.yaml](./examples/scenario.example.yaml) and
 [examples/scenario.crm.yaml](./examples/scenario.crm.yaml).
 
@@ -128,18 +138,21 @@ stateless protocol, so a 2026-07-28 server audits fine) and reports two things,
 separately. First, a **quality grade** for what models actually experience:
 descriptions, schemas, annotations, tool count, token cost. Second, an ungraded
 **migration diff** for the 2026-07-28 stateless spec (which removes
-`initialize`, sessions, Sampling, Roots, and Logging, and requires
+`initialize` and sessions, deprecates Sampling, Roots, and Logging, and requires
 `server/discover`, `resultType`, and cache fields): exactly what will break and
 how to fix it, each rule naming the SEP it came from. Readiness never drags the
-grade; not having migrated to a spec that is not final until 2026-07-28 is a
-to-do list, not a defect. Full list: [docs/RULES.md](./docs/RULES.md).
+grade, because the two answer different questions: the grade is what a model
+experiences from this tool surface, readiness is whether a 2026-07-28 client can
+talk to this server. Combining them scored the reference server a C for a tool
+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">
 </p>
 
-*(That is the official reference server: solid quality, four things to migrate
-before the 28th.)*
+*(That is the official reference server: solid quality, four things left to
+migrate.)*
 
 <details>
 <summary>The same output as copyable text</summary>
@@ -151,8 +164,7 @@ grade A (95)   quality: 0 errors  1 warning  0 info
   ! E122  tool "echo": description misses 3/4 quality axes (length 40..600;
           says when to use it; mentions the result)
 
-2026-07-28 readiness  4 items to migrate (a migration diff, not graded: the
-spec finalizes 2026-07-28)
+2026-07-28 readiness  4 items to migrate (a migration diff, not graded)
   ! E104  server declares the logging capability; MCP Logging is deprecated in
           2026-07-28 (SEP-2577) and logging/setLevel is removed
   ! E106  server/discover is not implemented (-32601 Method not found)
@@ -192,19 +204,56 @@ your context window.
 Focused tools already own single slices of this space, and some are very good.
 efaimo is the one tool that covers the whole audit surface. As of mid-2026:
 
-| | efaimo | [skill-validator](https://github.com/agent-ecosystem/skill-validator) | [upskill](https://github.com/huggingface/upskill) | [mcp-spec-check](https://github.com/Roee-Tsur/mcp-spec-check) | [conformance](https://github.com/modelcontextprotocol/conformance) (official) |
-|---|---|---|---|---|---|
-| Agent Skills linting | yes | yes | no | no | no |
-| Skill token cost | yes (3-level split) | yes | no | no | no |
-| Skill outcome testing | with/without A/B trials (experimental) | static LLM scoring | yes (generate + eval, code agents) | no | no |
-| MCP tool-definition cost | yes (3 serializations, `--anthropic` exact) | no | no | no | no |
-| MCP quality rules | yes | no | no | no | no |
-| 2026-07-28 readiness | migration diff: what breaks and how to fix | no | no | yes/no verdict | official test suite |
-| CI budget gate + badge | yes | no | no | no | no |
+| | efaimo | [skill-validator](https://github.com/agent-ecosystem/skill-validator) | [skillgrade](https://github.com/mgechev/skillgrade) | [upskill](https://github.com/huggingface/upskill) | [mcp-spec-check](https://github.com/Roee-Tsur/mcp-spec-check) | [conformance](https://github.com/modelcontextprotocol/conformance) (official) |
+|---|---|---|---|---|---|---|
+| Agent Skills linting | yes | yes | no | no | no | no |
+| Skill token cost | yes (3-level split) | yes | no | no | no | no |
+| Skill outcome testing | with/without A/B trials (experimental) | static LLM scoring | **yes, and more thoroughly**: Docker-isolated runs, script + LLM-rubric graders, weighted scores, CI pass-rate gates | yes (generate + eval, code agents) | no | no |
+| MCP tool-definition cost | yes (3 serializations, `--anthropic` exact) | no | no | no | no | no |
+| MCP quality rules | yes | no | no | no | no | no |
+| 2026-07-28 readiness | migration diff: what breaks and how to fix | no | no | no | yes/no verdict | official test suite |
+| CI budget gate + badge | yes (token budget) | no | pass-rate threshold | no | no | no |
+
+Read that table honestly: on skill outcome testing, `skillgrade` is the more
+serious tool and we would use it over our own `efaimo test` for anything
+depending on the result. Ours is one experimental subcommand in an audit CLI;
+theirs is a testing framework. efaimo's claim is the row count, not any single
+row.
+
+[SkillsBench](https://github.com/benchflow-ai/skillsbench), whose paper this
+README cites, is not in the table because it is a benchmark rather than a tool
+you point at your own work: a fixed suite of tasks with packaged environments
+and verifiers, extensible by contributing tasks upstream. Useful for the
+question "do skills help in general", which is why we cite it, and not for
+"does mine help", which is what `efaimo test` and `skillgrade` answer.
 
 efaimo runs the official conformance suite for you (`check --conformance` on
 http targets) and complements security scanners such as Snyk agent-scan and the
-skills installer (`npx skills`) rather than replacing them.
+skills installer (`npx skills`) rather than replacing them. If your server is
+built on the TypeScript SDK, efaimo tells you what breaks and why, and
+[`@modelcontextprotocol/codemod`](https://www.npmjs.com/package/@modelcontextprotocol/codemod)
+rewrites the SDK v1 to v2 call sites for you. Diff, codemod, re-check.
+
+### "Doesn't tool search already solve this?"
+
+Partly, and that is the point. Anthropic ships a
+[tool search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool):
+mark tools `defer_loading: true` and the model discovers schemas on demand
+instead of carrying all of them, with discovered schemas appended so the prompt
+cache survives. Where it applies, it is a better fix than anything a linter can
+tell you, and efaimo's own rules point at it (E127 and E128 suggest deferred
+loading as a remedy).
+
+It does not make measurement unnecessary, for three reasons. It is opt-in per
+tool, so somebody has to decide which tools are worth deferring, and that
+decision needs the per-tool numbers. It is a client-side feature, so it says
+nothing about what your server publishes to hosts that do not implement it.
+And a mitigation you cannot measure is a mitigation you are trusting on faith:
+`weigh` reports the definitions your server actually ships, which is the input
+every mitigation operates on.
+
+If deferred loading covers your whole setup, you may not need this tool. Run
+`weigh` once and find out; that answer is worth more than our opinion.
 
 ## Install
 
@@ -222,6 +271,9 @@ Or add it to a project with `npm i -D efaimo`, or the GitHub Action:
     command: check --skill ./skills --strict
 ```
 
+The Action is listed on the
+[GitHub Marketplace](https://github.com/marketplace/actions/efaimo).
+
 Gate a pull request on context-window growth, too:
 
 ```bash
@@ -243,11 +295,16 @@ More recipes (pre-commit, GitLab, editor audit, programmatic use):
 |---|---|
 | **S101 to S106** | skills: frontmatter and trigger quality, trigger collisions, context budget, reference integrity, injection hygiene |
 | **E101 to E118** | MCP 2026-07-28 readiness: deprecated primitives, statelessness, `server/discover`, `resultType`, cache fields, transport |
-| **E121 to E130** | MCP quality: description quality, annotations, schema hygiene, tool-count and token-cost budgets |
+| **E121 to E128, E130** | MCP quality: description quality, annotations, schema hygiene, tool-count and token-cost budgets |
+
+`E000` is not a finding about your server: it means one of efaimo's own rules
+threw and was skipped, so the report is incomplete. It is never scored.
 
 Quality (E12x-E13x) and skill (S) findings set the letter grade; readiness
-findings (E101-E118) are reported as an ungraded migration diff until the spec
-ratifies. Every finding carries a stable id you can suppress or link. See
+findings (E101-E118) are reported as an ungraded migration diff, which
+`--strict-readiness` can turn into a non-zero exit
+without touching the grade.
+Every finding carries a stable id you can suppress or link. See
 [docs/RULES.md](./docs/RULES.md).
 
 ## Roadmap
@@ -255,8 +312,9 @@ ratifies. Every finding carries a stable id you can suppress or link. See
 - Harden `efaimo test`: a separately chosen judge model, confidence intervals on
   the delta, multi-turn tool-use trials, and judge calibration, so the
   experimental harness earns unqualified trust.
-- Track the 2026-07-28 spec to ratification, then start grading readiness (today
-  it is an ungraded migration diff on purpose).
+- Readiness rules for the two 2026-07-28 changes that have none yet: the
+  `Mcp-Method` / `Mcp-Name` request headers (SEP-2243), and Tasks moving out of
+  core into the `io.modelcontextprotocol/tasks` extension (SEP-2663).
 - A public, continuously updated Agent Skills Quality Index over a broad corpus.
 
 ## Stability

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, or add an efaimo badge or CI gate.
 license: Apache-2.0
 metadata:
-  version: "0.1.0"
+  version: "0.1.1"
   homepage: "https://efaimo.ai"
 ---
 
@@ -18,6 +18,18 @@ skill well-formed", or "add a CI gate / badge for context cost".
 
 Run via `npx efaimo` (no install needed).
 
+**Before running any of these against a stdio server: auditing one means
+executing it.** `weigh` and `check --mcp` start the command you pass as a child
+process and speak MCP to it, because that is the only way to see the tool
+definitions it would put in a context window. So only point them at commands
+you would be willing to run yourself. A remote target (`https://...`) is not
+executed and is the safe option for something you do not trust. `--client`
+reads the MCP config files in the current directory as well as your user
+config, so running it inside a repository you did not write means starting the
+servers that repository configured. This warning lives in `SECURITY.md` and did
+not live here, which is the wrong way round: the policy is where humans look,
+and this file is where agents take orders.
+
 - **Weigh context cost of an MCP server**
   `npx efaimo weigh "npx -y <server-package>"` for a stdio server, or
   `npx efaimo weigh https://host/mcp` for a remote one. Add `--json` for machine

package/dist/check/check.js

@@ -10,8 +10,12 @@ import { findSkills } from "../skills/parse.js";
 import { weighServer, weighSkills } from "../weigh/weigh.js";
 import { VERSION } from "../version.js";
 function buildReport(surface, target, findings, notes) {
-    // MCP readiness findings (E101-E118) are a migration diff for a spec that is
-    // not final until 2026-07-28; they are reported separately and never graded.
+    // MCP readiness findings (E101-E118) are a migration diff for the 2026-07-28
+    // spec: a migration not yet made is a to-do list, not a defect in what
+    // shipped. Reported separately and never graded (ADR-014, reaffirmed in
+    // ADR-027). That decision is CLOSED: the spec published on 2026-07-28 and
+    // readiness still does not count toward a grade. This comment described it
+    // as open for a day after ADR-027, in the file that implements the split.
     const readinessAll = [];
     const gradedAll = [];
     for (const f of findings) {

package/dist/cli.js

@@ -7,9 +7,11 @@ import { VERSION } from "./version.js";
 import { resolveTarget } from "./targets/resolve.js";
 import { loadClientServers, SUPPORTED_CLIENTS } from "./targets/clientConfigs.js";
 import { introspectServer } from "./clients/introspect.js";
+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 { DEFAULT_CONTEXT_WINDOW, formatWindowShare, setContextWindow } from "./weigh/window.js";
 import { checkMcpRepoOnly, checkMcpTarget, checkSkillSet } from "./check/check.js";
 import { renderCheckPretty, renderDiffPretty, renderScenarioPlan, renderServerWeighPretty, renderSkillSetPretty, renderSkillWeighPretty, renderTestReportPretty, setColor, } from "./reporters/pretty.js";
 import { parseScenario, runScenario } from "./testing/harness.js";
@@ -45,7 +47,21 @@ function collectPairs(sep) {
     };
 }
 function colorSetup(opts) {
-    setColor(opts.color !== false && process.env.NO_COLOR === undefined);
+    // Escape codes are noise once stdout is a file or another tool's stdin, and
+    // `efaimo weigh > report.txt` is a normal thing to do. So colour needs both
+    // the user's consent and a terminal to write to; FORCE_COLOR is the escape
+    // hatch for CI that renders ANSI in its log viewer.
+    const forced = process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== "0";
+    const wanted = opts.color !== false && process.env.NO_COLOR === undefined;
+    setColor(wanted && (forced || process.stdout.isTTY === true));
+}
+function windowSetup(opts) {
+    if (opts.window === undefined)
+        return;
+    const n = Number(opts.window);
+    if (!Number.isFinite(n) || n <= 0)
+        fail(`--window must be a positive number of tokens, got "${opts.window}"`);
+    setContextWindow(n);
 }
 function fail(message) {
     console.error(pc.red(`error: ${message}`));
@@ -100,9 +116,11 @@ program
     .option("--allow-increase <pct>", "with --diff: exit 1 if the increase exceeds pct percent")
     .option("--badge [file]", "write an SVG badge + shields endpoint JSON")
     .option("--anthropic [model]", "also measure exact Claude tokens via the count_tokens API (needs ANTHROPIC_API_KEY)")
+    .option("--window <tokens>", "context window the share is reported against", String(DEFAULT_CONTEXT_WINDOW))
     .option("--no-color", "disable colors")
     .action(async (targetArg, opts) => {
     colorSetup(opts);
+    windowSetup(opts);
     const timeoutMs = seconds(opts.timeout) * 1000;
     const maxTokens = parseNumberOpt(opts.maxTokens, "--max-tokens");
     const allowIncreasePct = parseNumberOpt(opts.allowIncrease, "--allow-increase");
@@ -114,6 +132,29 @@ program
             fail(`no MCP servers found for client "${opts.client}" (checked: ${[...conf.sources, ...conf.missing].join(", ")})`);
         }
         console.error(pc.dim(`config: ${conf.sources.join(", ")}`));
+        // Say what is about to be EXECUTED, not just which file it came from.
+        //
+        // --client reads .mcp.json, .cursor/mcp.json and .vscode/mcp.json from
+        // the CURRENT DIRECTORY as well as the user config, and then spawns
+        // every command in them. Cloning an untrusted repo and running the audit
+        // tool inside it was therefore arbitrary code execution, and the only
+        // thing printed was the friendly config key, never the command. Cursor
+        // and VS Code gate project-scoped MCP config behind workspace trust;
+        // this printed nothing at all.
+        //
+        // Listing them is the minimum. A stdio entry names a real command that
+        // is about to run on this machine.
+        for (const e of conf.entries) {
+            const t = e.target;
+            const shown = t.kind === "stdio"
+                ? [t.command, ...t.args].join(" ") + (t.env && Object.keys(t.env).length ? `   (+${Object.keys(t.env).length} env)` : "")
+                : t.url;
+            console.error(pc.dim(`  ${e.name}: ${shown}`));
+        }
+        if (conf.fromCwd.length) {
+            console.error(pc.yellow(`  ! ${conf.fromCwd.length} of these came from the current directory (${conf.fromCwd.join(", ")}), not your user config.\n` +
+                `    Auditing a stdio server means executing it. Only continue in a repository you trust.`));
+        }
         targets.push(...conf.entries.map((e) => e.target));
     }
     if (targetArg) {
@@ -186,7 +227,7 @@ program
                 .filter((r) => r.kind === "mcp")
                 .reduce((s, r) => s + r.totals.claudeStyle, 0);
             if (mcpTotals > 0) {
-                console.log(pc.bold(`\ncombined MCP context cost (Claude-style, o200k est.): ${mcpTotals.toLocaleString("en-US")} tokens (~${((mcpTotals / 200000) * 100).toFixed(1)}% of a 200k window)`));
+                console.log(pc.bold(`\ncombined MCP context cost (Claude-style, o200k est.): ${mcpTotals.toLocaleString("en-US")} tokens (${formatWindowShare(mcpTotals)})`));
             }
         }
     }
@@ -226,6 +267,7 @@ program
     .option("--repo <path>", "additionally scan this source repo for deprecated API usage")
     .option("--no-probe", "skip live readiness probes (bare request, server/discover, ordering)")
     .option("--strict", "exit 1 on warnings too")
+    .option("--strict-readiness", "exit 1 if the 2026-07-28 migration diff is not clean (never changes the grade)")
     .option("--conformance", "after the audit, run the official MCP conformance suite (http targets)")
     .option("--header <header>", 'HTTP header "Key: Value" (repeatable)', collectPairs(":"))
     .option("--env <pair>", "KEY=VALUE for stdio servers (repeatable)", collectPairs("="))
@@ -234,9 +276,11 @@ program
     .option("--md", "print Markdown")
     .option("--badge [file]", "write a grade badge SVG + shields endpoint JSON")
     .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")
     .action(async (targetArg, opts) => {
     colorSetup(opts);
+    windowSetup(opts);
     if (!targetArg)
         fail("nothing to check: pass a target (see --help)");
     if (opts.mcp && opts.skill)
@@ -305,10 +349,31 @@ program
             console.error(pc.yellow("note: the official conformance suite drives http targets (--url); skipping for this target"));
         }
         else {
-            console.error(pc.dim("\nrunning official MCP conformance suite (npx @modelcontextprotocol/conformance)...\n"));
+            // The `latest` line of the conformance suite (0.1.16) predates the
+            // 2026-07-28 revision, so it silently tests the old protocol. Those
+            // scenarios ship on the `alpha` line only; --spec-version scopes them
+            // to the revision efaimo is about.
+            //
+            // Pinned to an exact version, because a dist-tag is not a pin. `alpha`
+            // moved from 0.2.0-alpha.9 to 0.2.0-alpha.10 on 2026-07-27, and we went
+            // on reporting "the official conformance suite" for a build nobody here
+            // had run: the same "we do not know what we ran" bug this block was
+            // written to fix, through the other door. Bumping it means re-reading
+            // `server --help` first; the two flags below were confirmed against
+            // 0.2.0-alpha.10.
+            const args = [
+                "-y",
+                "@modelcontextprotocol/conformance@0.2.0-alpha.10",
+                "server",
+                "--url",
+                target.url,
+                "--spec-version",
+                SPEC_VERSION,
+            ];
+            console.error(pc.dim(`\nrunning official MCP conformance suite:\n  npx ${args.slice(1).join(" ")}\n`));
             // cross-spawn resolves npx(.cmd) without a shell, so target.url is passed
             // as a literal argument (never interpreted by cmd.exe).
-            const r = crossSpawn.sync("npx", ["-y", "@modelcontextprotocol/conformance", "server", "--url", target.url], {
+            const r = crossSpawn.sync("npx", args, {
                 stdio: "inherit",
             });
             if (r.status !== 0)
@@ -318,6 +383,15 @@ program
     if (report.counts.error > 0 || (opts.strict && report.counts.warn > 0)) {
         process.exitCode = 1;
     }
+    // Readiness stays out of the grade, the badge and the default exit code
+    // (ADR-014, reaffirmed in ADR-027). But a team that HAS migrated had no way
+    // to stay migrated: --strict covers quality only, so nothing in CI could
+    // catch a regression back onto the legacy handshake. This is the opt-in for
+    // exactly that, and it moves the exit code only. Nobody's grade changes,
+    // no published number moves, and the operator decides rather than us.
+    if (opts.strictReadiness && (report.readiness?.findings.length ?? 0) > 0) {
+        process.exitCode = 1;
+    }
 });
 program
     .command("test")

package/dist/clients/rawprobe.d.ts

@@ -6,7 +6,14 @@ import type { ResolvedTarget } from "../targets/resolve.js";
  * stateless requests, server/discover) need raw transport access.
  * Every probe fails soft into a { skipped } marker.
  */
-export declare const RC_VERSION = "2026-07-28";
+/**
+ * The MCP revision efaimo audits against. It was called RC_VERSION until
+ * 2026-08-01, by which point the revision had been published for four days and
+ * the name had been lying for all of them. scripts/spec-drift.mjs reads this
+ * declaration by name, so renaming it again means updating that regex, which
+ * fails loudly rather than silently watching nothing.
+ */
+export declare const SPEC_VERSION = "2026-07-28";
 interface RpcReply {
     result?: Record<string, unknown>;
     error?: {
@@ -16,7 +23,7 @@ interface RpcReply {
     timeout?: boolean;
     procExit?: number | null;
 }
-export declare function rcMeta(): Record<string, unknown>;
+export declare function specMeta(): Record<string, unknown>;
 /**
  * Only an explicit "not initialized" / "session required" error proves the
  * server requires the removed initialize handshake. A plain timeout is NOT proof
@@ -24,11 +31,20 @@ export declare function rcMeta(): Record<string, unknown>;
  * inconclusive; a crash is its own signal. This keeps E105 from false-flagging a
  * healthy but slow server, the worst verdict a readiness checker can emit.
  *
- * Detection is by message, not by error code: the codes SDKs use here are
+ * Detection is by message, not by error code, and the spec that published on
+ * 2026-07-28 is the argument for why. The codes SDKs use here are
  * implementation-defined (TS StreamableHTTP sends -32000 for both "Server not
  * initialized" and "Mcp-Session-Id header is required", -32001 for "Session not
- * found"), -32002 means Resource-not-found in the 2025 specs, and the RC
- * reserves -32022 for UnsupportedProtocolVersion, so no code is diagnostic.
+ * found"), and the MCP-defined ones MOVED between the locked RC and the
+ * published spec: MissingRequiredClientCapability went -32003 to -32021 and
+ * UnsupportedProtocolVersion went -32004 to -32022, and HeaderMismatch moved
+ * the same way, -32001 to -32020. This comment said HeaderMismatch was "added
+ * alongside them", which was wrong: the RC already defined it at -32001 in the
+ * transport prose, and what the published revision added was its entry in the
+ * schema. The distinction matters to anyone still returning -32001.
+ * -32002 (resource not found) is retired outright,
+ * replaced by -32602 and promised never to be reused. Matching on numbers
+ * would have rotted here on 2026-07-28; matching on messages did not.
  */
 export declare function looksLikeInitGate(o: ProbeOutcome): boolean;
 export declare function runProbes(target: Extract<ResolvedTarget, {