docs(ratchet): the run-when-main footer names its third importer

[os-steve]

Fixes #1533

What changed

Comment text only, in the run-when-main footer of scripts/check-source-token-ratchet.mjs, plus an empty-frontmatter changeset. stripComments and every other executable line are untouched, and that is checked mechanically rather than asserted — this filter over the diff returns nothing:

git diff -U0 -- scripts/check-source-token-ratchet.mjs \
  | grep -E '^[+-]' | grep -vE '^(\+\+\+|---)' | grep -vE '^[+-]\s*//'

Editing the function would have caused the exact hazard the comment exists to prevent, so the diff is confined to lines that cannot run.

The importer set, re-derived rather than copied

Measured on this branch's base, origin/main at 81a79ee, on 2026-09-05 around 22:35Z, by resolving actual import ... from '...check-source-token-ratchet.mjs' statements — not by name occurrence:

Importer	Takes
test/source-token-ratchet.test.ts:8	anchor, fmt, BUFFER, CEILINGS
test/docs-readme-token-figures.test.ts:7	BUFFER, CEILINGS
test/docs-object-term-consistency.test.ts:8	stripComments

Two files that a name-only grep adds and that are not importers: test/deal-threshold-parity.test.ts declares its own local const stripComments at :71, and test/script-main-guard.test.ts spawns the gate by path. Both are named in the new comment so the next reader does not have to re-discover them.

Small correction to the card, in the card's own spirit: its table lists the first importer at :7; it is at :8, and it was at :8 at d9fad90, the ref the card measured. Nothing turns on the number — it is only one more instance of a hand-transcribed fact drifting from its source, which is what this card is about. That is also why the new comment names files and symbols and no line numbers.

Why the third importer is the load-bearing one

test/docs-object-term-consistency.test.ts is the #802 Chinese-term guard. It runs every .ts file through stripComments and scans only what comes back, so a retired spelling may live in a comment but not in code. Editing stripComments therefore edits what that guard scans, and widening it makes the guard pass by reading nothing — indistinguishable from clean. That suite's own defence is a single assertion, that stripping a known file leaves its ledger standing; it catches a stripper that returns nothing, not one that returns too little. The old footer said the opposite: that nothing imports the stripping rule, so changing it is free. Naming the consequence, not just the count, is what should stop the sentence rotting back.

The written record, corrected — with a chronology the card could not see

.changeset/ratchet-runmain-comment-names-what-imports.md is on main and states:

stripComments and verdict are imported by no test in the repo.

stripComments and verdict stay exported and unimported on purpose

Half of that is false in the tree today: verdict is still imported by nothing, but stripComments has an importer. That landed changeset is a shipped release note and is left untouched; this PR's changeset is the correction of record, so the record stops contradicting the tree.

But the sharper version of the story is not that a fix re-affirmed an already-false claim. Verified on a deepened clone (the checkout is shallow at 50 commits, and the shallow reading of these dates is wrong — it attributes the changeset to the boundary commit 7a67bc0; after git fetch --deepen 300 the boundary moves to 2026-08-05 and both readings sit well inside it):

• The footer sentence and that changeset both landed together in 03847ef, PR docs(ratchet): the run-when-main comment names what the tests import #1380, 2026-08-30T15:22:48Z. Nothing has touched scripts/check-source-token-ratchet.mjs since.
• The stripComments import landed in 9f59f6a, PR fix(i18n): unify the Chinese product term for crm_case to 工单 #1525 for [观察] 文档里的状态名/字段标签与语言包是否一致，无人检查——一周内同一缺陷类出现三次，全靠人眼撞见 #802, 2026-09-03T08:00:07Z.

So the sentence was true when it was written and was falsified three days later by an edit in a different directory, with nothing in this file able to notice. That is a more uncomfortable finding than a careless claim: no amount of care at authoring time would have prevented it. It is why the replacement paragraph dates itself, names the ref it was derived at, and carries the one-line grep that re-derives it.

Not built: the pin (card item 2)

The card floats a test asserting the footer's importer list equals the real importers and honestly calls it a maintainer call. Not built, on AGENTS.md section 3. Do not build platform-level tooling here: a comment-to-importer consistency check is a drift-class gate over this repo's tooling, not a pin on a HotCRM business fact, and that section's own precedent is #1423, where the comment-volume gate was deliberately not built. It would also land in test/, which is inside epic #1579's active territory. The mitigation shipped instead is the derivation recipe in the comment itself.

The ratchet cannot see this change, twice over

pnpm hygiene:tokens is green, and that fact is not offered as evidence the comment is correct. It cannot be, for two independent reasons: the gate counts comment-stripped characters, and its scan root is srcDirs(), which reads src/ only — scripts/ is never measured at all. Business semantics reads ~84,579 against the ~85,000 ceiling, headroom ~421, identical to the pre-change reading. No wording was trimmed to protect that headroom.

Gates — full pnpm verify chain, each step's exit code captured before any pipe

Run on b02debf in a dedicated worktree.

Step	Exit	What that run actually establishes
pnpm validate	0	Metadata still validates; unrelated to this diff, which touches no src/.
pnpm typecheck	0	The three importing suites still type-check against the module's unchanged export surface.
pnpm lint	0	Unchanged; 90 warnings and 12 suggestions are pre-existing and non-gating.
pnpm lint:i18n-gate	0	0 i18n/missing-* issues; untouched by a comment.
pnpm hygiene	0	No raw control bytes in the new text, and the file is far under the size cap (24KB against a 100KB cap, below the 70% advisory).
pnpm hygiene:tokens	0	Only that the ratchet still runs and its numbers are unmoved. It establishes nothing about this comment's truth.
pnpm build	0	Build artifact unchanged in shape.
pnpm test	0	160 files, 3391 passed, 1 skipped. The property that matters: test/source-token-ratchet.test.ts reads this gate's source as text and parses the header's worked table out of it, so this run proves the edit did not disturb that parser — and confirms no suite pins the footer paragraph's text.

No gate can judge whether this comment is true; the argument for that is the re-derivation above, not a green check.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
hotcrm	Ignored		Sep 5, 2026 10:46pm UTC