[finding] the locale-pin comment in llms.txt/route.ts names getPageTree() as a leaking call — measured, it is not

[hotlong]

Found while implementing #184 (asserting the locale composition of the built llms bodies). Out of that card's file surface — it only touches .github/scripts/check-locale-surface.mjs — hence a separate card. No behaviour is wrong today; this is about a comment that would mislead the next person to check it.

What the comment claims

apps/docs/app/llms.txt/route.ts:31-36, the block that explains why LANG is pinned:

English only, by AGENTS.md rule 1 [...] source.getPages() and source.getPageTree() list every language when called without one, which is how this file used to emit all 335 pages across 7 locales as one flat list.

The claim about getPages() is correct and well evidenced — lib/seo.ts records that a bare source.getPages() returns 553 pages against 79 real English ones, and I reproduced exactly that.

The claim about getPageTree() is not.

Measurement

Against fumadocs-core 16.8.12 with this repo's content, on 9a1a7ad, dropping the argument from source.getPageTree(LANG) in this route and rebuilding with pnpm turbo run build --force:

	llms.txt.body sha256
source.getPageTree(LANG)	883ebd3834fb1deb49f0c58cb153ed0a2eb06de16b854da592ce8e013ca85b1b
source.getPageTree()	883ebd3834fb1deb49f0c58cb153ed0a2eb06de16b854da592ce8e013ca85b1b

Byte-identical. The mutation was confirmed on disk before the build (the getPageTree(LANG) occurrence count went 1 to 0, and the file's blob moved from 790d942a to fa061ce3), so this is a real no-op and not an unbuilt measurement. getPageTree() with no language resolves to the default language.

The historical defect this route was fixed for was in fact source.getPages(). git show 9c29df6^:apps/docs/app/llms.txt/route.ts is nine lines long and reads for (const page of source.getPages()) — a flat bullet list, which is what "as one flat list" in the comment is describing. Restoring that exact blob does reproduce the seven-locale leak.

Why it is worth fixing rather than leaving

The comment is the only thing on the page explaining why LANG exists. Its stated justification for the current call is checkable in about two minutes and comes back false. The failure mode is a future reader verifying it, finding the pin makes no difference to getPageTree, and concluding the pin is cargo cult — removing it, or removing it from the next route written from this one as a template. The pin should stay: nothing in the API contract promises getPageTree() will keep defaulting to the default language, and #184's gate now asserts the output either way.

Suggested repair: attribute the leak to getPages(), which is where it was and where it still is, and state the getPageTree() position as "passes the language because the tree is per-locale and the default is not contractual" rather than as an observed leak.

Related, same neighbourhood: apps/docs/app/llms-full.txt/route.ts carries a similar block, but its claim is about getPages() only and is accurate.

---

Generated by Claude Code

[hotlong]

Graded: promoted to pm:queue / Task, finding removed. Blocked-by: #197 — see the sequencing note at the end.

Scope correction: the claim is now in BOTH files, not one. The card says llms-full.txt/route.ts "carries a similar block, but its claim is about getPages() only and is accurate." That was true of the tree you measured (9a1a7ad). It stopped being true nine minutes before you filed. Current main:

apps/docs/app/llms.txt/route.ts:32-33

source.getPages() and source.getPageTree() list every language when called without one

apps/docs/app/llms-full.txt/route.ts — added by #196 (1ebd7b7), merged at 02:07

source.getPages() and source.getPageTree() alike filter by locale only when a language is passed — called bare they list every language

So the fix is two files.

How the second copy got there is the interesting part

#196 changed that route from enumerating getPages() to walking getPageTree(). Its dev noticed the LANG comment now named a call the route no longer makes, and updated it — correctly, and flagged as a declared deviation, and I accepted it on exactly that reasoning. In doing so it carried across the getPageTree() half of the sibling file's claim.

That half had never been measured. It was true-sounding, adjacent to a claim that is true, and it propagated on the strength of being already written down.

Two agents, an hour apart: one copied an unverified assertion into a second file, the other measured it and found it false. The measurement is what a comment claiming API behaviour needs and had never had. Same discipline as "a dispatch's hazard claims need a reading" — a comment asserting what a library does is a claim about code, and it is checkable in about two minutes, as you demonstrated.

Keep the pin

The card's judgement is right and the dispatch should carry it: the pin stays. Nothing in the API contract promises getPageTree() will keep defaulting to the default language, #184's gate (01b29d9) now asserts the output either way, and passing the language explicitly is correct regardless of what the current version happens to do when you omit it.

What changes is the justification: attribute the leak to getPages(), where it was and still is, and state the getPageTree() position as "passes the language because the tree is per-locale and the default is not contractual" rather than as an observed leak. That is a stronger reason than the false one, and it survives a reader checking it.

The failure mode this prevents

A future reader verifies the comment in two minutes, finds the pin makes no difference to getPageTree, concludes the pin is cargo cult, and removes it — or writes the next route from this template without one. The comment is the only thing on either page explaining why LANG exists, and its stated reason currently comes back false when checked.

Sequencing

Blocked on #197, which is in flight on apps/docs/app/llms-full.txt/route.ts — one of your two files. If #197 lands as needs_decision without touching the file (a real possibility; it was dispatched as an investigation first), this unblocks immediately. Otherwise it unblocks on that merge.

---

Generated by Claude Code

[hotlong]

Claim: PM loop round 10
Session: session_01G5zjYc2BoFV2NjKBBapC7C
Branch: claude/issue-203-locale-pin-comment
Worktree: objectos-issue-203
Domain: n/a (objectos carries no domain:* lanes)
File surface: apps/docs/app/llms.txt/route.ts, apps/docs/app/llms-full.txt/route.ts — comments only, no behaviour change. Stop on breach; explain in the report.
Container and model: S, mode:subagent, model: sonnet — the judgement is already made in the grading comment above; what remains is a measurement and a rewrite.
Clause-②: no

Unblocked. #197 returned needs_decision with an empty diff and no PR, so llms-full.txt/route.ts was never touched and the serial constraint I set is gone. Nothing else is in flight on either of your files.

Reproduce before you rewrite — that is the whole point of this card

This card exists because an unmeasured claim propagated between two files on the strength of being already written down. Do not now write the replacement comment on the strength of this card's measurement without reproducing it. It is a two-minute check, which is precisely the argument the card makes.

Drop the argument from source.getPageTree(LANG) in llms.txt/route.ts, rebuild, compare the llms.txt.body sha256 against the unmutated build, restore. The card got byte-identical hashes on 9a1a7ad; main has moved several times since, so confirm it still holds on your base. If it does not hold on current main, stop and report — that would mean the comment is now true and this card is void.

Turbo cache trap: the cache is shared across worktrees and will replay a sibling's green. Use --force, and confirm the mutation is on disk before the build (occurrence count going 1 to 0), the way the card did — not by trusting an editor's exit code.

What to write

Per the grading comment: attribute the leak to getPages(), where it was and still is, and state the getPageTree() position as passes the language because the tree is per-locale and the default is not contractual — not as an observed leak. The pin stays in both files. The new justification is stronger than the false one and survives a reader checking it.

Both copies need it. llms-full.txt/route.ts acquired its version from #196 nine minutes before the card was filed, which is why the card's own text says that file is accurate — it was, when measured.

---

Generated by Claude Code