workers/mcp/CLAUDE.md states the always-on/gated split three different wrong ways, unguarded

[serge-ivo]

The always-on/gated split is stated wrong in three ways, and no gate checks it

workers/mcp/CLAUDE.md:85:

114 are always registered; 18 are surface-gated (apply=4, repo=3, coding=11+3).

Three separate errors in one sentence:

1. 114 contradicts the constant. workers/mcp/src/tool-count.ts:26 — MCP_TOOL_ALWAYS_ON = 117.
2. It does not sum to its own total. 114 + 18 = 132, against MCP_TOOL_COUNT = 135 two lines
   earlier in the same paragraph.
3. The parenthetical does not sum to 18. apply 4 + repo 3 + coding "11+3" = 21.

platform-docs/mcp.md states the same split correctly — 117 always-on, 18 gated, with a table
listing 4 apply + 3 repo + 11 coding = 18. So the public doc is right and the doc agents read
while working inside the worker is wrong.

Why it survived

scripts/docs-drift.mjs check 6 compares every documented "N tools" claim to
MCP_TOOL_COUNT. 135 is the only number it checks. MCP_TOOL_ALWAYS_ON and
MCP_TOOL_GATED are exported right beside it and are compared to nothing, so the split can say
anything. The per-surface table is checked in workers/mcp tests against MCP_TOOL_GATED, but
prose stating the split is not.

This is the same shape as the drift that produced check 6 in the first place: a number that
looked authoritative, in a file nothing measured. The header of docs-drift.mjs records that
history, including a green tick printed over three hand-picked paths while the served site
advertised "~67 tools".

Acceptance criteria

1. CLAUDE.md:85 states the split correctly and consistently with tool-count.ts.
2. docs-drift.mjs compares documented always-on / gated claims to MCP_TOOL_ALWAYS_ON and
   MCP_TOOL_GATED, in the same style as its existing count check.
3. The success line states its denominator per ADR 0002 — how many split claims were found, in
   how many files — and the input set is asserted, not assumed: the check fails if it
   collects implausibly few files, because "found nothing" and "found nothing wrong" print the
   same tick.
4. The check goes red on the current text, demonstrated before the text is fixed.
5. Any file stating the split — workers/mcp/CLAUDE.md, workers/mcp/README.md,
   platform-docs/mcp.md, store/ served HTML — is in the input set. platform-docs/mcp.md is
   currently correct; that is not a reason to exclude it, since agreeing today is exactly how
   the .well-known manifest hid in serverInfo.version and server.json disagree, and neither moves when the tool surface does #573.

Verified vs inferred

• Verified: CLAUDE.md:85's text, all three arithmetic failures, tool-count.ts:23/26/30,
  platform-docs/mcp.md's correct split and its 18-row gated table, and that docs-drift.mjs
  check 6 references only MCP_TOOL_COUNT.
• Inferred: nothing. Every claim is a file read or an addition.

[serge-ivo]

Landed as d51c3ee. CI green.

AC1 — the text

workers/mcp/CLAUDE.md:85 now reads "117 are always registered; 18 are surface-gated (apply=4, repo=3, coding=11)". The gated split is apply 4 + repo 3 + coding 11, which is what platform-docs/mcp.md's table has listed correctly all along — so coding=11+3 was the error, not the 11.

AC2–3 — the check

scripts/lib/mcp-split.mjs, called from docs-drift.mjs, compares every always-on / gated claim to MCP_TOOL_ALWAYS_ON and to MCP_TOOL_COUNT - MCP_TOOL_ALWAYS_ON — derived the way tool-count.ts derives MCP_TOOL_GATED, not restated, since a fourth hand-typed copy of that subtraction is the thing being guarded against. Success line:

✓ MCP always-on/gated split: 117 always-on + 18 gated == 135 constant == 10 claim(s)
  across 4 file(s) stating it, 40 swept (3 required to state it)

No arm for "the split sums to the total." Once both halves are pinned to the constants, 117 + 18 = 135 is arithmetic on values already forced. A third assertion would restate the subtraction again.

Three phrasings, all covered, because a parser tested only against the sentence someone wrote first stops measuring the moment a second file says it differently:

file	phrasing
platform-docs/mcp.md	"117 are always present. The remaining 18 are gated to"
workers/mcp/README.md	"117 are always registered; 18 are gated to the console"
workers/mcp/CLAUDE.md	"18 tools are surface-gated"

A digit is required in front, so README.md:282's "All six are always registered" — prose about a subset — is correctly not a claim about the total.

The per-surface parenthetical is checked only when it shares a line with a gated claim. An unrelated (retries=3, backoff=2) elsewhere in the prose is not a restatement of the split, and asserting over it would manufacture a false failure — which is how a check earns its deletion.

AC5 — the input set, including the file that was already right

Swept: docFiles() + servedHtmlFiles(), 40 files, with a floor. Required to state it: workers/mcp/CLAUDE.md, workers/mcp/README.md, platform-docs/mcp.md — the last of which was correct throughout, and is required anyway. A test pins that decision, citing #573: a file that agrees is exactly how store/.well-known/mcp-server.json hid from the wire-surface check's first pass.

store/llms-full.txt is the fourth file that states the split. It is swept but not required to speak, because it is generated — requiring a claim from it would fail the day its generator changed shape, for a reason having nothing to do with the split. Both halves are tested: a wrong number in it fails, its silence does not.

AC4 — red before the text was fixed

Run with the check in place and CLAUDE.md untouched, then again end-to-end after the refactor (copy/restore through a scratchpad — never git stash, which is repo-global across worktrees here):

✗ [mcp-split] 2 doc claim(s) disagree with the tool-count constants
  (MCP_TOOL_ALWAYS_ON 117, gated 18 = 135 - 117), out of 40 file(s) swept:
    workers/mcp/CLAUDE.md:85  always-on says 114, constant says 117
      `instance-tools/`. 114 are always registered; 18 are surface-gated (apply=4, repo=3, coding=11+3).
    workers/mcp/CLAUDE.md:85  per-surface breakdown (apply=4, repo=3, coding=11+3) says 21, constant says 18

pnpm docs:drift exit 1. Nine more arms in scripts/lib/mcp-split.test.mjs + four in doc-claims.test.mjs, including both G1 failures (constants unreadable, sweep collapsed) and the invisible one — a file rewritten to "117 always-on and 18 gated", which matches neither regex and would otherwise read as agreement.

Worth recording

The public docs were right and the guidance was wrong, which is the opposite of the usual direction and is why nothing caught it: workers/mcp/CLAUDE.md sits in check 6's SUBSET_CLAIMS exemption — for the good reason that it quotes per-file counts and deliberate historical statements ("67 of those 86 tools until #305") that a total-sweep would fire on. Being exempt from one check is how it ended up in none.

The ratchet redirected the implementation. Written inline first, check-file-size.mjs refused it — docs-drift.mjs crossed 800 lines and the message said "add a pin — or split it now, which is cheaper than it will ever be again". Splitting was right on its own terms: it is what doc-claims.mjs and wire-surface.mjs already do, so the comparison takes strings and can be tested against shapes the repo no longer contains — including the broken sentence itself, now a fixture. docs-drift.mjs is back to 790 lines and takes no pin.