A gate script that quotes example code in a message string reads as a real SDK call site to the envelope-caller census — it masks comments, never string literals

[os-project-manager]

What was measured

packages/client/src/envelope-caller-census.test.ts walks every .ts / .tsx / .js / .mjs / .cjs file in the workspace looking for four SDK spellings — analytics.query, analytics.meta, analytics.explain, automation.trigger — and blanks comments only, through the house scanner scripts/js-comment-mask.mjs (maskComments). String literals are left intact, and deliberately so: the file's own header explains that a naive stripper which also blanked literals would open a phantom comment on any block-comment opener inside a string and shrink the census in silence.

The consequence is that example code quoted inside a string literal is counted as a real SDK call site. Gate scripts under scripts/** are full of exactly such strings: refusal messages that show the author what to write instead, fixtures that embed a synthetic changeset body, usage banners.

Measured on PR #13596, running the census's own four patterns through the repo's own maskComments over each file that PR changes:

pattern	origin/main	that PR's branch	delta
analytics.query	0	2	+2
analytics.meta	0	0	0
analytics.explain	0	0	0
automation.trigger	0	0	0

Both occurrences sat inside one string literal — a fixture's migration table in scripts/check-adr-0087-registration.mjs. The census went red (expected 21 to be 19) and the merge queue ejected the PR. The two comment mentions that same PR adds were masked correctly and contributed nothing, which is what isolates the mechanism to literals.

Why this is worth a card and not only the one fix

That PR has been fixed on its own terms: its fixture now demonstrates the symbol the fixture itself names, which is what it should have demonstrated anyway. The general shape is untouched, and it is a trap for the next gate author:

• the failure lands in a different package from the edit (packages/client) and names a ledger the author has never read;
• it is invisible to every local gate family a path derivation produces for a scripts/** edit — nothing in that family reads the census;
• it surfaces in the merge queue, i.e. after review, at the most expensive point;
• the diagnostic is a bare count mismatch, which says nothing about strings, masking, or gate scripts.

Which way it should be resolved is not obvious, and is left to triage. A sketch of the space, with no recommendation attached:

1. Do nothing — accept it as a known cost, and let each gate author learn it once, in the merge queue.
2. Make the census's own diagnostic self-explaining: when a counted site falls inside a string-literal span, say so in the failure text.
3. Teach the census a defensible literal/context distinction — weighed against the measured reason literals are NOT masked today.
4. Move the burden to gate authors (a convention for how example code is spelled inside author-facing messages), with the standing objection that a convention no instrument enforces is not a mechanism.

⛔ Nothing here proposes weakening, skipping or exempting the census, and nothing here proposes registering fixture prose in its ledger. The ledger's whole purpose is to be true; prose booked as call sites would be false data in it.

Context — surfaced while fixing the merge-queue ejection on #13596 (card #13080). The census is #13079's instrument. Neither is changed by this card, and this card asks for no change to either as a precondition.

Generated by Claude Code