finding(docs): three `tsx` fences in apps/console/docs are design-token lists that compile only as labelled statements — the snippet gate will be green about nothing once #6600 moves its roots

[os-project-manager]

Found while implementing #7282 (step 1 of ruling D on #6600). Recording only — #7282's file surface is the defect and the fragment markers, and re-fencing is a document-shape change of a different class. Not addressed in PR #7425.

What

apps/console/docs/UI_IMPROVEMENT_PROPOSAL.md has three tsx-fenced blocks under "Visual Design Specs" — sections "Color Palette" (:199), "Typography" (:207) and "Spacing" (:215) as numbered on bf244f400. Each is a list of design tokens:

// Reduce visual weight
background: "bg-background" // Instead of "bg-muted/30"
border: "border-border/50" // Subtle
header: "bg-muted/5" // Barely visible

That is not TypeScript. It parses as three labelled statements whose bodies are string-literal expressions, which is syntactically legal and semantically empty. So check-doc-snippet-types.mjs compiles all three clean.

Why it is worth recording

These three are the only blocks in apps/console/docs/** that are green on their own — the measurement for #7282 found 14 ts/tsx blocks, 11 red, and after that card lands the population is 4 compiled + 10 declared fragments. Three of those four "compiled" blocks are these. So the moment #6600's step 2 points the gate roots at apps/*/docs/** for real, three quarters of this tree's live semantic coverage is a check that cannot fail and is not reading TypeScript.

This is the failure shape the gate's own header names: "a gate that checks the one thing that is right converts unverified into a green, which is worse than no gate." A fragment marker is the wrong repair — it would assert the blocks cannot compile, which is false. The fence language is the honest one.

Precedent — same class, already ruled once

#5997 is exactly this defect one tree over: six tsx-fenced blocks in content/docs/guide/component-registry.md that were markdown bullet lists. It was fixed by re-fencing, which took those blocks out of the ts/tsx population the gate collects, and let the six fragment markers #5991 had declared come out with them. apps/console/docs was never in that card's scope because no documentation gate has ever walked it — the blind spot #6600 records.

Note the fence target is not obvious here and is the part that needs deciding: the blocks are neither valid JSON (background: "bg-background" has no braces and carries // comments) nor a bullet list as #5997's were. Plain text, or a rewrite into a markdown table, are both live options.

Scope if picked up

• apps/console/docs/UI_IMPROVEMENT_PROPOSAL.md, three fences.
• pnpm check:doc-fences is currently green on them and stays green either way — its root is content/docs, so it does not read this file at all today.
• Ordering: this is only load-bearing once finding(gate): apps/console/docs/** is outside every documentation gate's scan surface — the console's operator guides are checked by nothing but check:control-bytes #6600 step 2 lands. Before that, nothing gates the tree, so nothing changes.

Filed unassigned. Back-link: #7282, PR #7425.

Generated by Claude Code