efaimo 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -4,9 +4,163 @@ 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.2] - 2026-08-03
 
-## [0.1.0]
+The 0.1.2 code backlog: edge-case fixes surfaced by the five-agent review, none
+of which changes a published number or the documented command surface, plus the
+security and CI hardening already staged.
+
+### Fixed
+
+- `check --mcp <directory>` with no source files and no MCP SDK dependency now
+  fails instead of returning a clean A(100): an empty scan is a failure, never a
+  pass.
+- S101: a skill with no frontmatter reports its missing `name` and `description`
+  as errors, so a total absence no longer grades higher than a broken one.
+- E105: a server that exits on a bare stateless `tools/list` is flagged. The
+  crash outcome was unhandled, so a crashing server looked more migrated than
+  one that answers with a not-initialized error.
+- E124: the "N of M parameters lack descriptions" summary is no longer dropped
+  by the display cap on schemas with five or more oversized enums.
+- S106: the escape check is lexical (the resolved path), not a `..` substring,
+  so a file merely named `notes..md` is not flagged as escaping.
+- A Poetry `mcp = "^2.0"` constraint in `pyproject.toml` is read as the 2.x
+  line, not legacy; the version regex had captured the `=` assignment.
+- `weigh --diff` with a skill baseline fails with a clear message instead of a
+  raw TypeError; a server baseline is required.
+- `--max-tokens` and `--allow-increase` reject non-positive / negative values
+  instead of turning the gate into an always-fail with a nonsense message.
+- `efaimo test --live` against an OpenAI o-series reasoning model no longer
+  sends an unsupported `temperature` (a 400) and gives it token headroom.
+- The live test harness retries a transient 429 or 5xx with backoff instead of
+  discarding every already-paid trial on the first blip.
+- The test report prints a clean note instead of "95% interval NaN to NaN" when
+  an arm produces no scoreable trial.
+- A dead stdio target fails in about one `--timeout`, not two: the legacy
+  handshake and the stateless fallback now share the budget.
+- Internal: dropped a dead exported constant and the unused per-pattern
+  `severity` on the injection heuristics (every hit is info + ungraded by
+  design).
+
+### Security
+
+- The lockfile was re-resolved so the dev/CI tree carries
+  `@hono/node-server` 2.0.12 instead of the 1.19.x line that
+  GHSA-frvp-7c67-39w9 covers (moderate, path traversal in `serve-static`, in
+  the half of the MCP SDK this CLI never executes). A fresh `npx efaimo`
+  install already resolved the patched line; this aligns the committed tree
+  with what users actually get, and `pnpm audit --prod` is clean again.
+
+### Changed
+
+- `@modelcontextprotocol/sdk` floor moved within-range from ^1.29.0 to ^1.30.0
+  (what a fresh install resolves anyway). The full suite (136 tests) is green.
+- CI: the reference-server smoke is pinned to
+  `@modelcontextprotocol/server-everything@2026.7.4`. Per-commit CI should be
+  deterministic; news about the reference server's latest belongs to a
+  scheduled run, not to a push.
+- CI: `spec-drift.yml` and the example workflow now pin actions by commit SHA
+  like the other workflows, and the example declares least-privilege
+  `permissions`.
+
+## [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 colors 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 a capped read (2MB) on the same guarded path that
+  caps referenced files at 512KB, 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] - 2026-07-18
 
 First release.
 
@@ -19,7 +173,7 @@ First release.
   broken or auth-gated server is skipped with a reason, not fatal.
   `--out`/`--diff`/`--max-tokens`/`--allow-increase` for CI budget gates,
   `--badge` for a shields endpoint.
-- `efaimo check --mcp`: a quality grade (E121-E130: descriptions, schemas,
+- `efaimo check --mcp`: a quality grade (E121-E128, E130: descriptions, schemas,
   annotations, cost) plus a separate, ungraded 2026-07-28 migration diff
   (E101-E118: what the stateless spec breaks and how to fix it, each item naming
   its SEP). Speaks both the legacy handshake and bare stateless requests, so
@@ -43,5 +197,7 @@ 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
+[unreleased]: https://github.com/efaimo-ai/efaimo/compare/v0.1.2...HEAD
+[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
 [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
@@ -53,8 +53,8 @@ hygiene. Run it on a folder and every skill gets its own grade, not one aggregat
 **We graded 36 public Agent Skills**: every skill in `anthropics/skills`,
 `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
+`claude-api` scores a C (73) with an over-limit description and ~18k-token
+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.2"
   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. Until 2026-08-02 this warning lived only in
+`SECURITY.md`, which was 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) {
@@ -46,6 +50,14 @@ export async function checkMcpTarget(target, opts = {}) {
 }
 export function checkMcpRepoOnly(repoPath, label) {
     const repo = scanRepo(repoPath);
+    // An empty result is a failure, never a pass. With no source files read and no
+    // dependency manifest naming an MCP SDK, there was nothing to examine here, and
+    // a clean A(100) would be a grade for a directory we never looked inside. Fail
+    // loudly, the way checkSkillSet does for a missing SKILL.md.
+    if (repo.filesScanned === 0 && !repo.sdk) {
+        throw new Error(`no MCP server source found under "${repoPath}": no code files and no SDK dependency. ` +
+            `Point --mcp at the server's run command, or at a directory that contains its source.`);
+    }
     const emptyIntro = {
         targetLabel: label,
         transport: "stdio",

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}`));
@@ -66,12 +82,18 @@ function seconds(value, label = "--timeout") {
         fail(`${label} must be a positive number of seconds, got "${value}"`);
     return n;
 }
-function parseNumberOpt(value, label) {
+function parseNumberOpt(value, label, bound) {
     if (value === undefined)
         return undefined;
     const n = Number(value);
     if (!Number.isFinite(n))
         fail(`${label} must be a number, got "${value}"`);
+    // A budget or a percentage below its floor is not a stricter gate, it is a
+    // nonsensical one: `--max-tokens -5` turned "over budget" into always-true
+    // with a negative ceiling in the message. Reject it at the boundary.
+    if (bound && (bound.exclusive ? n <= bound.min : n < bound.min)) {
+        fail(`${label} must be ${bound.exclusive ? "greater than" : "at least"} ${bound.min}, got "${value}"`);
+    }
     return n;
 }
 function anthropicKeyFor(opts) {
@@ -100,12 +122,14 @@ 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");
+    const maxTokens = parseNumberOpt(opts.maxTokens, "--max-tokens", { min: 0, exclusive: true });
+    const allowIncreasePct = parseNumberOpt(opts.allowIncrease, "--allow-increase", { min: 0 });
     const anthropic = anthropicKeyFor(opts);
     const targets = [];
     if (opts.client) {
@@ -114,6 +138,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 +233,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)})`));
             }
         }
     }
@@ -198,8 +245,14 @@ program
             fail("--diff works on a single MCP server result");
         const baselineRaw = JSON.parse(fs.readFileSync(opts.diff, "utf8"));
         const baseline = ("data" in baselineRaw && baselineRaw.data ? baselineRaw.data : baselineRaw);
-        if (!baseline?.totals)
-            fail(`"${opts.diff}" is not a weigh baseline (write one with --out)`);
+        // A skill weigh baseline also carries a `totals` object, so a bare
+        // truthiness check passed it through and diffServerWeigh then died on the
+        // missing tool array with a raw TypeError. A server baseline is the one
+        // whose totals hold the three serializations; require the Claude-style
+        // total specifically so a skill baseline is rejected with a clear message.
+        if (!baseline?.totals || typeof baseline.totals.claudeStyle !== "number") {
+            fail(`"${opts.diff}" is not an MCP server weigh baseline; write one with: efaimo weigh <server> --out ${opts.diff}`);
+        }
         const d = diffServerWeigh(baseline, single);
         console.log("");
         console.log(opts.md ? renderDiffMarkdown(d) : renderDiffPretty(d, { maxTokens, allowIncreasePct }));
@@ -226,6 +279,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 +288,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 +361,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 +395,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")