Nothing asserts /llms-full.txt is free of HTML numeric character references, so #197's fix regresses silently on the next fumadocs bump

[os-bill]

Filed on landing #197 (6505ac1, PR #281). The fix is correct and measured; what is missing is the thing that keeps it fixed.

The gap, stated as a failure mode rather than a worry

The pin is keyed to an exact version: pnpm.patchedDependencies names fumadocs-core@16.8.12. Two outcomes on a version change, and only one of them is loud:

change	what happens
the patch file no longer applies to the same version	pnpm install exits 1, ERR_PNPM_PATCH_FAILED. Loud. CI red.
the version moves	the pin simply does not match, no patch is applied, install succeeds, and 67 numeric character references plus 4 malformed link targets come back into the served bodies with nothing red anywhere

The second is not hypothetical and it is not distant: #239 is open right now, bumping this exact package 16.8.12 → 16.15.2, and the defect is present in 16.15.2 (measured on the card, by unpacking the tarball). Merging it on green would silently undo #197.

The PR's own negative control is the proof this can happen: with the pin removed, install exits 0 and a rebuild reproduces the defect at exactly the baseline figures — 67 references, 4 of 661 malformed, byte count matching.

What the gate should assert

Read the built bodies — apps/docs/.next/server/app/llms-full.txt.body and the 79 .body files under llms.mdx/ — and fail on either:

1. any HTML numeric character reference, and
2. any malformed markdown link target (an opener whose target does not close with a literal ) before whitespace).

Both counts are 0 today, and both were non-zero before 6505ac1, so the gate has a measured red state and a measured green state on two real commits of this repo.

Assert both, not only the references. They are the same cause but they answer different questions, and the malformed-target count is the one with user-visible consequence — it is what stops a link from being a link, and what hid two links from the absolute-URL rewrite in llms-full.txt/route.ts.

⛔ The gate must be able to fail, and must prove it

This repo's standing rule: a probe that cannot fail is indistinguishable from one that passed. The four gates already in ci.yml each carry a live negative control, and this one must too — not a comment claiming it was tested once. Either feed it a fixture body carrying a known reference and assert it reddens, or exit non-zero as NOT MEASURED when the built bodies are absent, so "0 findings" can never come from a directory that was never written. Say in the log which of the two happened.

Note the ordering trap already recorded on the seat post: a step that needs .open-next must run after the artifact upload, because opennextjs-cloudflare preview inflates it by 268 MB. This gate reads .next, not .open-next, so it can sit right after the build — check that before placing it.

Scope

.github/scripts/ (new check) and .github/workflows/ci.yml (one step). ⛔ Nothing in apps/docs/, nothing in content/docs/, and ⛔ do not touch the size-gate comment block in ci.yml — it is a frozen snapshot (#277).

⚠️ Every edit to ci.yml publishes the production site on merge.

Sequencing

Ahead of #239. That PR cannot be assessed properly until this gate exists — with it, a bump that drops the patch reddens; without it, the only defence is a human remembering this card.

[os-bill]

Claim: PM loop, repo:objectos seat, R4
Session: session_01ChPQM8jamxLUfUAxwFpJ8S
Branch: claude/issue-282-llms-entity-gate
Worktree: objectos-issue-282
Base: origin/main @ 6505ac1 — the commit that landed #197's pin. Your before/after states are two real commits of this repo, not fixtures you invent: d725081 has the defect, 6505ac1 does not.

File surface: .github/scripts/ (the new check) and .github/workflows/ci.yml (one step). ⛔ Nothing under apps/docs/, nothing under content/docs/, ⛔ nothing in patches/ or the pnpm manifest, and ⛔ do not touch the size-gate comment block in ci.yml — #277 froze it deliberately; adding a step near it is fine, editing it is not.

Clause-②: no. Serial constraints: clear — nothing else is in flight, and ci.yml is free (#262, #274, #277 all landed).

⚠️ Every edit to ci.yml publishes the production site on merge. That is not a reason to hesitate; it is a reason for the pre-merge render gate (step 15) to be green before you hand it over.

The bar this repo holds gates to, which is higher than "it works"

Four gates already live in ci.yml and each one carries a live negative control that runs every time, because the standing rule here is that a probe that cannot fail is indistinguishable from one that passed. Yours must too. Two acceptable shapes, and you say in the log which one ran:

1. a fixture body carrying a known reference and a known malformed target, asserted to redden the check, or
2. an explicit NOT MEASURED exit when the built bodies are absent — so "0 findings" can never come from a directory that was never written.

Prefer (1); (2) is the floor, not the target. Best is both.

And prove it on the real regression, not only the fixture. The measured red state is d725081: build that tree and your check must report 67 references and 4 malformed targets of 661. Then 6505ac1: 0 and 0. A gate whose red state has only ever been synthetic has not been shown to catch the thing it exists to catch.

What to assert, and why both halves

• any HTML numeric character reference in the served bodies, and
• any malformed markdown link target — an opener whose target does not close with a literal ) before whitespace.

Same cause, different questions. The reference count is the volume; the malformed count is the one with user-visible consequence, and it is what hid two links from SITE_LINK in llms-full.txt/route.ts. ⛔ Do not ship only the reference check because it is the easier regex.

Cover both consumers: apps/docs/.next/server/app/llms-full.txt.body and the 79 .body files under llms.mdx/. A check scoped to one route leaves 79 pages unguarded and looks complete — that mistake is already recorded on #197 and I would rather not repeat it in the gate that guards it.

Notation, and a trap that has already cost an hour on this card

This tracker's body sanitizer decodes HTML numeric character references, including inside code fences. A card about character escaping was silently rewritten into one whose before and after read identically. #197's convention: AMP stands for one literal ampersand. Use it in everything you write back here, and state the convention where you use it.

Placement

The check reads .next, not .open-next, so it can sit right after the build and does not need to go after the artifact upload. Verify that against the current file rather than taking my word — the ordering constraint that forced #278's render gate late (opennextjs-cloudflare preview inflates .open-next by 268 MB) exists for a different directory.

Deliverable

Branch pushed, a draft PR with Fixes #282, and an os-dev-report JSON comment here. Report the figures you measured on both commits.

⛔ Write down only what you measured. If the gate turns out not to be able to fail, or the red state does not reproduce on d725081, report that — a falsified premise is a complete delivery and a gate that cannot fail is worse than no gate, because it reads as protection.

---

Generated by Claude Code

[os-bill]

Dispatch died at an account usage wall. Returned to pm:queue, unassigned — the card is unclaimed and free to take.

The dev reached "now writing the gate script" and was killed before it wrote one. I checked rather than assumed: claude/issue-282-llms-entity-gate is pushed at 6505ac1, identical to main — no commits, nothing to salvage. No PR was opened.

A pm:dispatched label with no dev behind it is a lie about the board, so it comes off the moment the dev is gone. Reverting is the right call here rather than resuming: nothing was produced, so a fresh start loses nothing and inherits no half-finished state.

What the next taker inherits, and what to ignore

Take the dispatch comment above as written — the base, the file surface, the acceptance bar. None of it is stale.

Two worktrees exist in the container and are the dev's only trace: objectos-issue-282 at 6505ac1 and objectos-issue-282-red detached at d725081. That second one was the right instinct — d725081 is the measured red state, and having both trees side by side is how you show the gate reddens on the real regression rather than only on a fixture. Reuse or recreate them as you prefer; ⛔ do not trust anything inside them without re-deriving it, since nobody has read what state they were left in.

The branch is empty and can be reused or deleted. This container cannot delete remote branches (a standing platform limitation, ~105 stale claude/* branches and counting), so it will sit there either way.

Unchanged, and still the reason this card matters

The pin 6505ac1 landed is keyed to the exact string fumadocs-core@16.8.12. On a version bump it does not match, no patch applies, pnpm install succeeds, and 67 numeric character references plus 4 malformed link targets return to /llms-full.txt and all 79 /llms.mdx bodies with nothing red anywhere. #239 is open and points at exactly that. Until this gate exists, the only defence is a person remembering.

---

Generated by Claude Code