[finding] the locale pin on llms.txt / llms-full.txt is unasserted — the same missing-argument defect would land green again

[hotlong]

Blocked-by: #175

Found while implementing #177 (the llms-full.txt locale pin). Out of that card's file surface, hence a separate card.

What is unasserted

source.getPages() filters by locale only when a language is passed. That one call signature has now been got wrong in three files and fixed in three separate PRs:

file	fixed by
apps/docs/app/sitemap.ts	#176 (issue #169)
apps/docs/app/llms.txt/route.ts	#179 (issue #170)
apps/docs/app/llms-full.txt/route.ts	#183 (issue #177)

Nothing in the repo asserts the locale composition of any of the three built outputs. Every gate — type-check, build, test, the translation gates — was green on all three defects for their whole lifetime, and would be green again the moment someone drops the argument. On #177 that meant a 4.6 MB seven-locale payload served under a robots.txt that had just been opened to crawlers.

#175 proposes the fix for the sitemap. It is scoped to the sitemap: "count .mdx files under content/docs per locale and assert the built sitemap's per-locale entry counts match". The two llms endpoints need the same treatment and are not in that scope, which is what this card records.

Concrete assertion shape, already measured

The gate does not need to count anything as elaborate as the sitemap's per-locale entries. For the llms bodies a locale-exclusive title check is enough and is cheap to compute:

• Collect the frontmatter title: of every content/docs/**/*.mdx, bucketed by locale (untagged = en).
• A title is locale-exclusive if no other locale's bucket contains it.
• Assert the built /llms-full.txt body contains every en-exclusive title as a # line, and zero exclusive titles from the other six locales.

Measured on the #177 tree through a production build (next build then next start, body fetched over HTTP):

locale	files	exclusive titles in body, pre-fix	post-fix
en	79	63	63
zh-Hans	62	53	0
ja	39	31	0
de	38	25	0
es	39	32	0
fr	39	28	0
ko	39	31	0

Both directions are real defects, same as #175 argues for the sitemap: a non-en exclusive title reappearing means the locale pin was dropped again; an en exclusive title going missing means English pages stopped being served.

A cruder byte-size guard would also have caught this instance (4,608,768 → 671,413 bytes) but not the class — it says nothing about which pages are in the body, and it needs a threshold that has to be retuned every time the docs grow.

Design note

Same constraint #175 already prices: the check needs the built output, so it is a post-build step rather than a standalone --self-test under tools/ci-scripts/run-self-tests.mjs. Importing the route module directly pulls in the whole MDX collection and the @/ alias. Whatever harness #175 settles on for the sitemap should carry these two endpoints too — which is why this is filed as blocked by it rather than as an independent gate.

[hotlong]

Graded: promoted to pm:queue + pm:blocked / Task. finding removed. Blocked-by: #175 was already on the body and stands — #175 is now graded and queued too.

Promoted on the strength of the assertion shape, which is the part that makes this dispatchable rather than aspirational. The locale-exclusive-title check is cheap, computable from the content tree without going through app code, and already measured on a real before/after — 63/53/31/25/32/28/31 collapsing to 63/0/0/0/0/0/0. That is a gate someone can write from this card without rediscovering anything.

The reasoning for asserting in both directions is right and worth keeping: a non-en exclusive title reappearing means the locale pin was dropped again; an en exclusive title going missing means English pages stopped being served. A gate that only catches one direction would have passed the day a translation silently vanished.

Also right to reject the byte-size guard. It would have caught this instance (4,608,768 → 671,413) and not the class — it says nothing about which pages are in the body, and its threshold needs retuning every time the docs grow. Catching an instance is not the same as catching the defect.

Correctly blocked rather than independent. The card's own reasoning — whatever harness #175 settles on should carry these two endpoints, since both need the built output for the same reason — is why this waits. Do not dispatch it before #175 lands; the harness is the load-bearing decision and this is the increment on top of it.

---

Generated by Claude Code