[bug] The docs-drift tool count reads three files and reports "every doc claim" — the public /about page says ~67 tools while production serves 135

[serge-ivo]

The number a prospective user reads is half the real one

https://proagentstore.online/about/ — measured today:

~67 tools across creator operations, public trials, private instance runtime, coding, and error observability

https://mcp.proagentstore.online/health — measured the same minute:

{"ok":true,"service":"proagentstore-mcp","tools":135}

Source: store/about/index.html:179. The constant it disagrees with is workers/mcp/src/tool-count.ts:23 (MCP_TOOL_COUNT = 135).

This is #210's own defect, in the one surface a person reads before they decide whether to use the product — and pnpm docs:drift is green.

Why the guard did not see it

scripts/docs-drift.mjs:307:

const claimFiles = [
    p("platform-docs/mcp.md"),
    p("store/llms-full.txt"),
    p("workers/mcp/README.md"),
].filter(existsSync);

Three files. The failure message and the success line both speak in a wider voice — the CI output reads:

✓ MCP tool count: 135 registered == constant == every doc claim (+ 16 per-file counts)

"every doc claim" is a claim about the repo; the measurement is over three paths. That is the same shape as #536 and #531: a guard whose printed number is trusted because of how it is worded, taken over a subset.

The root of it is one layer up. docFiles() (scripts/docs-drift.mjs:49) opens with "Everything a reader or an agent is expected to trust" and then collects only platform-docs/*.md, store/llms.txt, store/llms-full.txt, README.md, AGENTS.md, SECURITY.md, and per-package README/AGENTS/CLAUDE.md. The store's own HTML — the marketing site, which workers/host builds and serves — is in none of it. Grepped: store/about/index.html is the only HTML page in the tree carrying a tool count, so the fix is small; but nothing was ever going to report it.

A second, independent stale claim in a file the guard DOES read

store/llms.txt:65:

Twelve tools require an exact confirm value, compared with ===. In eleven cases the value is the tool's own name: write_agent_file, batch_write_agent_files, unregister_instance_runtime, cancel_instance_task, cancel_instance, delete_instance_knowledge, delete_instance_memory, delete_instance_file, delete_instance_trigger, delete_instance_connector_grant, clear_instance_messages. The exception is remove_repo …

Counted from the code — every requireConfirmation(…) call site outside safety.ts and the tests — there are 13, twelve of which use the tool's own name. The missing one is delete_supervision (workers/mcp/src/instance-tools/composition.ts:97 declares the arg, :115 enforces confirm === "delete_supervision").

platform-docs/mcp.md:135-148 and workers/mcp/README.md:328 both list it correctly, so the drift is isolated to the LLM-facing file — which is precisely the reader that cannot ask. store/llms.txt is inside docFiles(), but the confirm-value list is not one of the eight checks, so nothing compares it to anything.

What to do, cheapest first

1. One line, fixes today's defect: correct store/about/index.html:179 to the real number, or better, drop the number ("the full tool surface — see the MCP docs") so a marketing page is not a second place the count has to be maintained.
2. Add the store HTML to claimFiles. store/**/*.html for the N tools regex. This is the smallest change that makes the guard's sentence true, and it would have failed on the line above.
3. Widen docFiles() to include the served HTML, so the removed-command and removed-identity checks cover the marketing site too. Grepped before proposing: cloudflared, --tunnel and the FAGS runtime-plane strings do not currently appear in any store/*.html (the only freeagentstore reference is a sibling-store profile link in store/developers/profile.html:206, which is the ecosystem cross-link, not a runtime-identity claim). So this widening lands green and holds new ground rather than opening a backlog.
4. Derive the confirm list. requireConfirmation(safety, toolName, confirm, expected, …) gives both halves; a check like the MCP tool-table one — every documented confirm pair equals a registration, and every registration is documented — turns store/llms.txt, platform-docs/mcp.md and workers/mcp/README.md into one derived table. That is the same construction that makes the tool-count check strong: tool-count.ts is asserted by index.test.ts running the REAL registration path, not by a regex over prose.
5. Make the success line say its denominator. ✓ MCP tool count: 135 == constant == every claim in 4 files costs nothing and stops the next reader over-trusting it. Consider it a general rule for this script — see the systemic issue filed alongside this one.

Alternatives considered and rejected

• Scan every file in the repo for N tools. Rejected: workers/mcp/CLAUDE.md:85 legitimately says "67 of those 86 tools until [standards][tracking] Split worst large files into testable modules #305" — a historical statement — and the per-file module-layout counts are already checked separately by their own rule. A blanket scan would fire on the prose that explains the rule, which is the failure mode usage-claims.test.ts and control-labels.ts both had to design around.
• Assert the about page against /health at build time. Rejected: it makes the docs build depend on a deployed service, and the constant already exists locally.

Acceptance criteria

1. node scripts/docs-drift.mjs FAILS on store/about/index.html as it stands today — demonstrate that before fixing the page, the way [bug] A "Runs on" tile claims "Attached · online" for a node the pin excludes — one line below "Status: Offline", and the invariant test only covers the pinned tile #531 proved its assertion by reverting the fix.
2. After the fix, the live /about/ number equals MCP_TOOL_COUNT, or states no number at all.
3. store/llms.txt's confirm list names all 13 tools and the count says 13/12, and a check compares that list to the requireConfirmation call sites rather than to another document.
4. Each ✓ line in docs-drift.mjs names how many files it read.

Regression risk

Widening docFiles() to HTML risks the removed-command check firing on prose inside a <code> block. fencedLines() (scripts/docs-drift.mjs:81) is Markdown-fence-specific and has no HTML equivalent, so step 3 needs an HTML-aware "is this an instruction" rule or it will need its own exclusions. Step 2 alone (the N tools regex over HTML) has no such coupling and can ship first.

Verified vs inferred

Verified: the live /about/ string and the live /health count (both fetched today); store/about/index.html:179; claimFiles at scripts/docs-drift.mjs:307; docFiles() at :49; 13 requireConfirmation call sites; store/llms.txt:65 listing eleven; platform-docs/mcp.md:148 listing delete_supervision; node scripts/docs-drift.mjs green at cfe8ff7.

Inferred: that no other served HTML page carries a checkable numeric claim — grepped for N tools|agents|migrations across store/**/*.html and found only this one, but a claim phrased differently would not have matched.

[serge-ivo]

Shipped in 8ca77af. CI green at that SHA (every gate, including pnpm test, pnpm test:e2e chromium+webkit, and docs:drift itself); Deploy Host Worker 31652373626 succeeded.

Verified live, after the deploy

$ curl -sS https://mcp.proagentstore.online/health
{"ok":true,"service":"proagentstore-mcp","tools":135}

$ curl -sS https://proagentstore.online/about/ | grep -o "[0-9~]* tools across[^<]*"
135 tools across creator operations, public trials, private instance runtime, coding, and error observability (

$ curl -sS https://proagentstore.online/llms.txt | grep -o "^- [A-Za-z]* tools require an exact .confirm. value.*own name:"
- Thirteen tools require an exact `confirm` value, compared with `===`. In twelve cases the value is the tool's own name:

$ curl -sS https://proagentstore.online/llms.txt | grep -o "delete_instance_connector_grant.\{0,50\}"
delete_instance_connector_grant`, `delete_supervision`, `clear_instance_messages`. The exce

$ curl -sS https://proagentstore.online/llms-full.txt | grep -o "^- [A-Za-z]* tools require an exact .confirm. value[^.]*\. [A-Za-z]* use the tool"
- Thirteen tools require an exact `confirm` value (compared with `===`, never fuzzy-matched). Twelve use the tool

Acceptance criteria

1. The guard FAILS on the page as it stood — demonstrated before fixing anything. With the widened sweep in place and every doc still untouched:

✗ [mcp-count] 1 doc claim(s) disagree with MCP_TOOL_COUNT (135), out of 40 file(s) swept:
    store/about/index.html:179  says 67
      <p><strong>MCP Server</strong> — … ~67 tools across creator operations

✗ [confirm-gates] store/llms.txt's confirm sentence states 12/11; the code gates 13 tools, 12 of them by their own name.
✗ [confirm-gates] store/llms-full.txt's confirm sentence states 12/11; …
✗ [confirm-gates] store/llms.txt omits 1 confirm-gated tool(s): delete_supervision.
    gated at workers/mcp/src/instance-tools/composition.ts:115
✗ [confirm-gates] store/llms-full.txt omits 1 confirm-gated tool(s): delete_supervision.

5 drift(s).

Two arms beyond the ones this issue asked for were also watched fail rather than argued:

• rephrasing the page to 135 MCP tools (which the regex does not match) fails with "1 file(s) are listed as stating the MCP tool total and no longer do" — the failure mode that would otherwise retire the check on that file in silence;
• pointing servedHtmlFiles() at a subdirectory exits 1 (collected 4, expected at least 8) instead of certifying the tree.

2. /about/ now reads 135, equal to MCP_TOOL_COUNT and to live /health. Kept a number rather than deleting one: with the page inside the sweep, a wrong number is now a red build, so the maintenance cost is zero and understating the product to a prospective user was the actual harm.

3. store/llms.txt names all 13 and says Thirteen/twelve, and the new check 7 derives the list from the requireConfirmation call sites — not from another document. It immediately found a second instance the audit had not reached: store/llms-full.txt:99 carried the identical "Twelve … Eleven" defect, delete_supervision missing. Both LLM-facing files were wrong, platform-docs/mcp.md and workers/mcp/README.md were right, and all four are now compared to the code every run.

4. Every ✓ line names its denominator:

✓ nav ↔ sources: 10 nav entries vs 10 source pages, both directions
✓ generated docs: git tracks 0 file(s) under store/docs
✓ removed commands: 3 tokens absent from 512 fenced line(s) in 25 doc file(s)
✓ removed identity: 2 tokens absent from 12 platform-docs/llms file(s)
✓ MCP tool table: 135 registered across 25 source(s) == 135 documented rows in workers/mcp/README.md, exact match
✓ MCP tool count: 135 registered == constant == 4 claim(s) across 39 file(s) swept (4 required to state it, 1 exempt) + 16 per-file counts
✓ confirm gates: 13 requireConfirmation site(s) == every list in 4 file(s) (25 MCP sources read)
✓ docs links: 6 /docs/<slug>/ reference(s) across 40 file(s) resolve to 10 nav page(s)
✓ API surface: in-scope coverage    : 312/312 (100.0% excluding 85 intentionally-excluded)

The mcp-count line moved from "== every doc claim (+ 16 per-file counts)" over 3 paths to a stated 39 files. Noted in the commit body so the number change is not silent.

The hard question — should a guard parse a number out of prose?

It may, but only bidirectionally, and that is the part this repo was missing. A one-way check ("every number I find must equal the constant") degrades to nothing the moment someone rewords the sentence, and prints the same tick while doing it — \b(\d+)\s+tools?\b does not match 135 MCP tools. So four files are now listed as required to produce a claim: a claim that is deleted or rephrased past the regex is a named red build, not silence. That buys the same property a generated include would, without making the docs build depend on a generator, and it works identically for .md, .txt and .html.

The counts in the two llms files stay written as words ("Thirteen"), deliberately: digits there would collide with the tool-total regex, and two parsers fighting over the same characters is exactly how the next one goes quiet.

Parsers are pure, in scripts/lib/doc-claims.mjs, with 17 tests in scripts/lib/doc-claims.test.mjs that execute each failure mode — including the two exact strings that shipped, and an explicit test recording that 135 MCP tools is invisible to the regex.

Deliberately not done

• Step 3 of this issue — widening docFiles() to the served HTML for the removed-command and removed-identity checks. fencedLines() is Markdown-fence-specific and HTML needs its own "is this an instruction" rule; the issue's own Regression-risk section says step 2 can ship first, and it did. The /docs/<slug>/ link check did take the HTML — it is a URL match with no fence semantics to get wrong. If the removed-command widening is wanted it needs its own ticket, since the HTML instruction rule is the whole of the work.
• ADR 0002 itself — this change follows [docs] Record as ADR 0002: a guard must assert the SIZE of what it measured — the three that lied are exactly the three with no denominator assertion #559's proposed G1–G4 rather than inventing a variant, and docs-drift.mjs cites check-design-tokens.mjs:97-101 as the pattern it copies. Writing the record is [docs] Record as ADR 0002: a guard must assert the SIZE of what it measured — the three that lied are exactly the three with no denominator assertion #559's deliverable.