docs(check-links): state the scan populations instead of copying their counts

[claude]

Fixes #7825

check-links.yml's header stated two document counts as literals, and both had
drifted with nothing red over the whole distance. Per the ruling on the card, the
numbers are not re-aligned — they are removed, and the header states its
populations and points at the readings instead, so the drift becomes structurally
impossible rather than merely correct today.

Fresh readings, re-measured on current main (83fe6e741, this branch's base)

The card measured 17 / 184 at 900f8d995. Today, with the same walk the
workflow's own args block declares:

reading	header used to say	measured on 83fe6e741
find docs -type f \( -name '*.md' -o -name '*.mdx' \) | wc -l	15	17
find content/docs -type f \( -name '*.md' -o -name '*.mdx' \) | wc -l	183	184

Split, for the record: content/docs is 144 .mdx + 40 .md; the repo-root
docs/ tree is all .md. Independently corroborated in the same session by
check:shell-escape-residue's own verdict line, which walks the same tree and
reports content/docs: 184 file(s).

Both figures are unchanged from the card's, so the surrounding prose still
describes the same scan scope — the scope statement was accurate, only its two
sizes were not. That is what made the rewrite a prose fix and not a scope change.

What changed

1. .github/workflows/check-links.yml — the header. Both sentences the card
flagged are rewritten, per ruling ②, because both read present tense:

• The live claim now names the populations — which trees, which extensions,
  and the apps/site/source.config.ts declaration the content tree comes from —
  and points at the two readings that produce the live figures (a find in any
  checkout, and Lychee's own run summary). No numeral qualifies a document
  population anywhere in the header any more.
• The historical claim is rewritten as explicit past tense, PR-numbered, and
  carries no live numeral: "Until PR check-links.yml(Lychee)扫的是 docs/**(15 个文件),不是站点文档 content/docs/**(183 个文件) #3449 the args list named only the
  repo-root docs/**, so not one published page had ever been scanned".

2. scripts/__tests__/check-links-workflow.test.ts — the third copy of
#7448's pin, in the home the card named, plus a fixture-backed control.

3. The same two counts, in the pin's own file header (in surface). The test
file's header carried the drifted counts word for word — "docs/ is 15 files of
INTERNAL material" and "the 183 files under content/docs/**". Both are in this
PR's binding file surface, both are the same defect class, and leaving one of the
two copies guarded while the stale twin sat in the file that guards it is how the
guarded one gets "corrected" back from the twin later. Both sentences are
rewritten to name the trees without sizing them, and the pin reads that header as
a second surface.

The pin, and why it is not a verbatim copy of its twins

The two #7448 twins (check-doc-fence-languages.test.ts,
check-doc-component-types.test.ts) match a numeral immediately adjacent to a
population noun. Run verbatim over this header before the fix, that pattern
reports one of the two live counts:

PRE-FIX check-links.yml header (origin/main 83fe6e741):
  twin  regex => ["183 files"]
  #7825 regex => ["15 INTERNAL documents","183 files"]
POST-FIX check-links.yml header:
  #7825 regex => []

"holds 15 INTERNAL documents" is a document count by any reading, and the
adjective between the numeral and the noun is all it took to score clean. The
twins' own docstrings state the intent as "a numeral DIRECTLY qualifying a
document-population noun", so the third copy implements that stated intent rather
than a new rule: up to two intervening words are allowed, and an issue reference
is excluded at the pattern level instead of by luck. The noun set is unchanged
from the twins.

Both twin workflow headers are clean today under both patterns, so this is a
latent gap in those two instruments, not a live falsehood on their headers. Filed
separately rather than fixed here — see below.

Positive control — the pin fails, then passes, on both surfaces

Ruling ③: a pin that cannot fail is not a pin. Four legs, one script, mutation
proved on disk before each reading and the restore proved against the HEAD blob
(script: an EXIT INT TERM trap restoring both files by absolute path).

leg	tree	vitest exit	result
0	as committed	0	9 passed
A	a count written back into check-links.yml's header	1	1 failed, 8 passed
A'	restored	0	9 passed
B	a count written back into the test file's own header	1	1 failed, 8 passed
B'	restored	0	9 passed

Leg A, the pin naming itself:

injected text hits: 1   (expect 1)
deleted anchor hits: 0  (expect 0)
blob now 8f01928f0f4987f010511c2da22622afa93ed5c1 vs HEAD b43e568fc4ec3d9253d04bbcb975958308dcfce2
AssertionError: check-links.yml states a document count (17 INTERNAL documents).
  Nothing fails when it drifts, so it will. ... : expected [ '17 INTERNAL documents' ] to deeply equal []

Leg B, the second surface:

injected text hits: 1   (expect 1)
AssertionError: this test file's own header states a document count (184 files).
  ... : expected [ '184 files' ] to deeply equal []

Restore legs, proved rather than assumed:

RESTORE PROVEN: .github/workflows/check-links.yml == HEAD blob b43e568fc4ec3d9253d04bbcb975958308dcfce2; git diff HEAD empty
RESTORE PROVEN: scripts/__tests__/check-links-workflow.test.ts == HEAD blob 27d7777c99124084108a2e8c0f43b24e0b5dc30f; git diff HEAD empty

The pin's fixture table asserts the same power without a mutation: the two
pre-fix sentences of this header and the two the #7448 twins' headers carried are
fixtured as positives; the negatives are every number a workflow header
legitimately keeps — an issue reference, 04:17 UTC, one 502, node-version: 22, timeout-minutes: 10, "the third instance of the same shape", and
~297 site-absolute links, which is the near miss that decides how far the
pattern may reach past the numeral.

Confirmations the ruling asked for, quoted verbatim

Governed surface (⑤). .github/workflows/ is not governed; run anyway:

$ node scripts/check-governed-queue-guard.mjs --test .github/workflows/check-links.yml scripts/__tests__/check-links-workflow.test.ts
✅ NOT GOVERNED — 2 path(s) checked against 5 governed surface(s); none matched.
   An ordinary pull request: the normal review and merge-queue route applies.

#3653's by-command doc pin (⑤). Confirmed, not assumed. The pin in
ci-cd-pipeline-doc.test.ts compares the first-party commands in ci.yml's
run: steps against the page's job table. check-links.yml is a separate
workflow that runs no command at all — its single step is
uses: lycheeverse/lychee-action@v2 — and this PR adds and removes no ci
command, so no doc row is owed. ci-cd-pipeline-doc.test.ts is green in the run
below.

Changeset (⑥). Its verdict, obeyed verbatim, measured on this branch's final
tree:

$ node scripts/check-changeset-presence.mjs
Compared the working tree with 83fe6e741 (merge-base with origin/main): 2 file(s) changed,
0 of them published source of a package the release covers, 0 of them a manifest whose
published contract moved, 0 under a package changesets ignores, 0 changeset(s) added.
✅  No source or published contract of a released package changed in this range, so no changeset is owed.

Nothing owed, so nothing added — and per this repo's rule the skip-changeset
label is NOT applied here: it reads as a mechanism and is not one in objectui.

Clause-② stays no (⑦). Prose and tests only. The scan scope is decided by
the args glob list, which is byte-identical to origin/main; the three
pre-existing scope assertions are untouched and still green.

Verification

Run after the final commit a5b52c4fa, with git diff HEAD empty.

pnpm exec vitest run --project unit scripts/__tests__/ --maxWorkers=2
  Test Files  104 passed (104)
       Tests  3089 passed (3089)

pnpm run type-check:scripts                     exit 0, no diagnostics
  (--listFiles confirms check-links-workflow.test.ts IS in the program: 1 hit)
pnpm run lint:root                              exit 0 — 0 errors, 33 pre-existing
                                                warnings, none in a file this PR touches
pnpm run check:control-bytes                    ✅ OK (6380 tracked text file(s))
pnpm run check:shell-escape-residue             ✅ OK (206 file(s), 1309 fenced block(s))
pnpm run check:governed-queue-guard             OK self-test: 132 cases pass

scripts/__tests__/ is the union that owns every workflow and prose pin in this
repo, so it is the union this diff can move; the per-package turbo run lint /
turbo run type-check farm is untouched by a comment and a script test, and CI
runs it regardless.

Filed separately, not fixed here

• The same two counts, present tense, on a published page:
  content/docs/guide/ci-cd-pipeline.md says Lychee sweeps "content/docs/ (the
  183 pages the site publishes) and the repo-root docs/ (15 files of internal
  material)". Outside this PR's binding file surface, and editing a published
  page pulls in the whole doc-gate family.
• The latent adjective gap in the two finding(gate): two doc-gate workflow headers carry hand-copied document counts that have drifted from what the gates report #7448 twins, measured above.

---

Generated by Claude Code