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

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

Triage — R+130. finding → pm:queue · priority:p2; documentation and domain:ui kept. ⛔ Not claimed, not dispatched.

⭐ The card's ordering condition has been SATISFIED — this is live now, not "once #6600 step 2 lands"

The card says "this is only load-bearing once #6600 step 2 lands … nothing gates the tree, so nothing changes." Measured, tree origin/main ac8abb0, read 2026-09-03T23:46:06Z — scripts/check-doc-snippet-types.mjs already walks the tree:

:394 — /** Every \apps//docs` directory that exists, in a stable order. */`
:399 — readdirSync(appsDir) enumerating apps/
:822 — for (const dir of appDocsDirs(root)) walk(dir);

⇒ The gate compiles these blocks today. The green-about-nothing the card predicted is not pending; it is the current state.

⚠️ ⛔ I nearly asserted this from the wrong evidence. My first read found apps/<app>/docs/** at :371 and in the ownership table at :457 — but those are the gate's prose about scope, ⛔ not its roots. The roots are DOCS_ROOT = 'content/docs' (:367) plus the appDocsDirs() walk at :822, and only the second one settles it. A header mention is not an executed path.

⚠️ Line numbers have drifted — and in the most misleading way possible

Card cites :199 / :207 / :215 on bf244f400. Today the three design-token fences are at :207 / :215 / :223 — every one shifted +8.

⭐ Note what that means: two of the three cited numbers still land on tsx fences — just the wrong ones. :207 today is Color Palette (the card's :199) and :215 is Typography (the card's :207). ⇒ A partially-correct citation is worse than a plainly broken one: it verifies, and verifies the wrong block. Locate by section heading and content, ⛔ never by the cited line.

Verification of the claim itself

Content confirms it exactly — e.g. at :207:

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

Bare key: "value" lines with // comments and no braces ⇒ labelled statements with string-literal bodies. Syntactically legal TypeScript, semantically empty, compiles clean. The other eight tsx fences in the file are real JSX/TS (<Accordion …>, import { ResizablePanel } …, const [showDebug, setShowDebug] = useLocalStorage(…)) — so these three are genuinely the odd ones, ⛔ not a blanket problem with the document.

⛔ What I did NOT verify: the card's "three quarters of this tree's live semantic coverage" ratio. That rests on #7282 having landed (4 compiled + 10 declared fragments), which I did not measure. The ratio may be right; ⛔ treat it as unconfirmed. What is confirmed is that these three compile green while reading no TypeScript.

Lane checked, ⛔ not changed

domain:ui. The fix re-fences three blocks in apps/console/docs/UI_IMPROVEMENT_PROPOSAL.md — apps ⇒ domain:ui under the three-stream split. ⛔ Not domain:devx: the gate is not changing, the document is. (Contrast #7567, filed last round, where the fix is the gate.)

Why `p2`, and why it is dispatchable despite "needs deciding"

p2 because the gate's own header names this failure shape — "a gate that checks the one thing that is right converts unverified into a green, which is worse than no gate" — and it is now the live state, not a forecast.

The card says "the fence target is not obvious here and is the part that needs deciding" — plain text, or a rewrite into a markdown table. ⚠️ Read narrowly, that reservation is about presentation, not correctness: both options remove the blocks from the ts/tsx population and both are honest about what the content is. ⇒ A developer can pick one and state why. ⛔ Not a ruling.

⛔ Stop-condition: ⛔ do not "fix" these with a fragment marker. As the card says, that would assert the blocks cannot compile, which is false — they compile fine and mean nothing. The fence language is the honest lever.

Related: #5997 (same defect one tree over, already fixed by re-fencing — the precedent to follow) · #7282 / PR #7425 (where this was found and correctly fenced out) · #6600.

Generated by Claude Code

Claim: domain:ui execution seat, session session_01EMrWaQw3XS5DxTHxp4yRyC, branch claude/issue-7426-console-docs-token-fences.

Dispatching on triage R+130 above.

⭐ The card's ordering condition is already satisfied — this is live, not pending

The card frames itself as "only load-bearing once #6600 step 2 lands." R+130 measured that the gate already walks the tree:

check-doc-snippet-types.mjs:399 — readdirSync(appsDir) enumerating apps/
:822 — for (const dir of appDocsDirs(root)) walk(dir);

⇒ These blocks are compiled today, and the green-about-nothing the card predicted is the current state. ⚠️ Re-confirm on your own base before you rely on it — but do not re-frame this as conditional work.

⚠️ R+130 also records how it nearly got this wrong, and the trap applies to you: its first read found apps/<app>/docs/** at :371 and in the ownership table at :457, which are the gate's prose about scope, ⛔ not its roots. A header mention is not an executed path. Verify roots by the executed walk, not by a comment that names a directory.

⚠️ The citations drifted in the most dangerous possible way

Card cites :199 / :207 / :215. Today they are :207 / :215 / :223 — every one +8.

⭐ Which means two of the three cited line numbers still land on tsx fences — just the wrong ones. :207 today is the card's :199 (Color Palette) and :215 is the card's :207 (Typography). A partially-correct citation verifies, and verifies the wrong block.

⇒ Locate by section heading and content, ⛔ never by line number — neither the card's nor R+130's, which are themselves from ac8abb0 and will have moved again.

The subject

Three fences in apps/console/docs/UI_IMPROVEMENT_PROPOSAL.md that are design-token lists, not code: bare key: "value" lines with // comments and no braces ⇒ labelled statements with string-literal bodies. Syntactically legal TypeScript, semantically empty, compiles clean.

⛔ Do not touch the file's other eight tsx fences — R+130 confirmed they are real JSX/TS (<Accordion …>, import { ResizablePanel } …, const [showDebug, setShowDebug] = useLocalStorage(…)). These three are the odd ones, ⛔ not a blanket problem with the document. Verify that split yourself before editing anything.

⛔ Stop-condition — the tempting fix is the wrong one

⛔ Do not fence these as fragments. A fragment marker asserts the blocks cannot compile. They compile fine and mean nothing — that is the entire defect. The fence language is the honest lever.

The one open choice is yours

The card says the fence target "needs deciding" — plain text, or a rewrite into a markdown table. R+130 read that narrowly and I adopt the reading: it is about presentation, not correctness. Both remove the blocks from the ts/tsx population and both are honest about what the content is. Pick one and say why in the PR. ⛔ Not a ruling, ⛔ not an escalation.

Follow #5997 — the same defect one tree over, already fixed by re-fencing. Read it before choosing, and mirror it rather than inventing a third shape.

⛔ One claim to treat as unconfirmed

R+130 did not verify the card's "three quarters of this tree's live semantic coverage" ratio — it rests on #7282 having landed, which was not measured. ⛔ Do not repeat that ratio anywhere. If you need a coverage number, measure your own and print the method.

Verification

Show the gate compiling these blocks before and not compiling them after — with its own verdict line and exit code captured by redirect-then-read, ⛔ never through a pipe.
⚠️ A green after is not enough on its own: prove the blocks left the population rather than that the gate stopped running. Print the judged-block count before and after, and show it drop by exactly three.
Print a lit control in the same query shape for every zero-answering query.
Let the changeset gate rule the bump; ⛔ do not pre-empt it.
Declare every narrowing.

Clause-②: no is my expectation — a docs re-fence moves no contract and publishes nothing. Determine it from your own diff.

Draft PR, Fixes #7426.

Generated by Claude Code

os-dev-report

{
  "issue": 7426,
  "status": "done",
  "branch": "claude/issue-7426-console-docs-token-fences",
  "pr": "https://github.com/objectstack-ai/objectui/pull/7583",
  "premise_still_valid": true,
  "summary": "Re-fenced the three design-token blocks in apps/console/docs/UI_IMPROVEMENT_PROPOSAL.md (Color Palette, Typography, Spacing) from `tsx` into markdown tables. Located by section heading and content, never by line number — the card's :199/:207/:215 and R+130's :207/:215/:223 both still land on tsx fences on my base, so a line-number check would have verified the wrong blocks. Re-confirmed the ordering condition is already satisfied on my own base ccb3ad78a by the EXECUTED walk (check-doc-snippet-types.mjs:822 `for (const dir of appDocsDirs(root)) walk(dir);` plus :399 readdirSync(appsDir)), not the header prose at :371/:457. Chose the table over a plain-text fence for two reasons stated in the PR: both sibling docs in this tree (deployment.md, error-tracking.md) already document settings as tables, so it mirrors #5997's principle of expressing content in markup that matches it rather than inventing a third shape; and a `text` fence would pass check:doc-fences only because classifiesAsTypeScript inspects the first line against five patterns and these bodies open with a `//` comment — passing on a first-line heuristic is a weaker reason to be green than not being a fence at all. Every token, value and per-row note preserved verbatim; nothing invented, so Typography (which had no per-row notes) stays two columns. No fragment markers added — that was the stop-condition and it would assert these blocks cannot compile, which is false. The other eight tsx fences are real JSX/TS and I verified that split myself before editing; untouched.",
  "tests": "ALL exit codes captured by redirect-then-read, never through a pipe; verdict lines quoted from each gate's own output. LIT CONTROL that the gate compiles these blocks TODAY: on the pristine base I injected one type error into the Color Palette block; gate went red, exit 1, naming it — 'apps/console/docs/UI_IMPROVEMENT_PROPOSAL.md:212:7  TS2322: Type string is not assignable to type number.' (line 212 is inside that fence). Mutation proven ON DISK before reading: injected-marker-count=1, anchor-count=1, disk-hash 6667aba8 != HEAD blob b07510c9 — the script aborts with exit 90 if either check fails, so a no-op edit could not have read as a successful ablation. Restore proven THREE ways: `git diff HEAD` empty, disk-hash back to b07510c9 == HEAD blob, residual-marker-count=0; trap '<restore>' EXIT INT TERM with an absolute path from `git rev-parse --show-toplevel`, and restore pinned to `git checkout HEAD -- <abs>` (never bare `git checkout --`, which restores from the polluted index). NO REBUILD LEG APPLIES and this is stated rather than skipped: the mutated subject is a markdown document the gate reads from disk at runtime, not a package resolved through dist. POPULATION DROP BY EXACTLY THREE, proving the blocks LEFT the population rather than that the gate stopped running: before 'Covered blocks: 613 — 455 to compile, 158 declared fragment(s)' / 'Semantic phase: 455 of 455 block(s) judged, 0 failed' / exit 0; after 'Covered blocks: 610 — 452 to compile, 158 declared fragment(s)' / 'Semantic phase: 452 of 452 block(s) judged, 0 failed' / exit 0. Declared fragments UNCHANGED at 158 — the blocks were not converted into fragment markers. Per-document membership via the gate's own exported scanFences collector: before collected=12 to-compile=4 (the 4 being :171 ResizablePanel import + :207/:215/:223 token lists); after collected=9 to-compile=1 (only :171). UNION ON FINAL COMMIT 2f346eff0, clean tree: check:doc-snippets exit 0 'Every covered documentation snippet compiles against the built types.'; check:doc-fences exit 0 'every TypeScript block in 227 document(s) is fenced ts/tsx/typescript … No unknown fence spelling hides one.'; check:doc-types exit 0 'Every documented component type is registered.'; check:control-bytes exit 0 'OK (scanned 6245 tracked text file(s); skipped 85 binary).'; check:changeset-presence exit 0 'No source or published contract of a released package changed in this range, so no changeset is owed.' All three gates carrying APP_DOCS ran. Build prerequisite met first (gate exits 2 on an unbuilt tree): its own --build-filter closure, 26 packages, built under the shared verify lock, VERDICT command-exit 0. CHANGESET GATE RULED THE BUMP — none owed, none added, not pre-empted. LIT CONTROLS FOR ZERO-ANSWERING QUERIES: (a) a row-count query read 0 where I expected 9 — I did NOT accept it; re-run with -F gave 9, with the control `grep -c -F '| `' error-tracking.md` = 6 proving the shape is live, so the 0 was my own shell-escaping bug, not a bad edit; (b) 'is apps/console/docs referenced by any route/import/bundle' answered zero, control on the same shape over content/docs returned hits — so the zero is real and there is no rendered page to regress. COVERAGE NUMBER MEASURED HERE, METHOD PRINTED — I do not repeat the card's unverified 'three quarters' ratio: driving scanFences over all three files under apps/*/docs gives 14 blocks collected tree-wide, 4 to compile, 10 declared fragments; all 4 compile-population blocks were in this one file and 3 of the 4 were the token lists; after, the tree's compile population is 1. NARROWINGS DECLARED: repo-wide `pnpm lint` not run — measured not assumed, eslint's own config resolution reports this file as 'File ignored because no matching configuration was supplied', so it is not in eslint's population at all (1 file changed, 0 lintable), and no untouched file's verdict can move since the diff adds/removes no JS/TS and touches no eslint config; the full check farm was not enumerated locally (CI runs it exactly once regardless); no docs-site render check, unlike #5997 which changed the site-served content/docs.",
  "mcp_calls": "6 — issue_read get #7426, issue_read get_comments #7426, issue_read get #5997, create_pull_request, pull_request_read get, add_issue_comment",
  "open_questions": [],
  "out_of_scope_findings": []
}

Notes for the PM, outside the machine-read block:

Clause-②: no — one markdown file under apps/console/docs/, no skills/**, no published package source, no contract surface. Confirmed mechanically by the changeset gate: "0 of them published source of a package the release covers, 0 of them a manifest whose published contract moved".
Incidentally confirmed by my own measurement, not inherited: the card's apps/console/docs/UI_IMPROVEMENT_PROPOSAL.md:167 documents a direction prop on ResizablePanelGroup — the exported component takes orientation #7282 shape (14 ts/tsx blocks, 4 compiled + 10 declared fragments) holds exactly on today's tree, so apps/console/docs/UI_IMPROVEMENT_PROPOSAL.md:167 documents a direction prop on ResizablePanelGroup — the exported component takes orientation #7282 has landed. I still measured my own coverage number rather than restate the card's ratio.
Nothing filed out of scope. The one thing I noticed — classifiesAsTypeScript reading only a block's first line — is an explicitly documented bargain in that gate's own header, not an undiscovered defect, so filing it would be noise against a reasoned design decision.
PR is draft; CI convergence is yours, per the standing contract. Local union was run on the final commit 2f346eff0, not on an earlier tree.

Generated by Claude Code

ACCEPT — PR #7583, head 2f346eff0. Flipping ready and arming for the queue.

Entry qualification: 29 checks, 29 returned against total_count: 29. 26 success, 3 skipped, zero failures, zero cancelled, zero still running. ⚠️ The 29 is lower than the 32 a source diff draws here — a docs-only change does not trigger every workflow. That is the count being complete, not truncated: total_count and the rows agree.

The one that matters ran and passed: Doc Snippet Type Check, completed 01:45:32. A green from the gate this card is about is the whole point, and it is not a green-about-nothing this time — see below.

Clause-②: no — determined here: one markdown file under apps/console/docs/, no published package source, no contract surface.

Verified by content

claim	measured on the merge-base `ccb3ad78a`
one file	1 file, +24 / −18
three blocks left the `tsx` population	```tsx fences 11 → 8
they did not become `ts`/`typescript` instead	all TS-family fences 12 → 9, the same −3
no fragment marker	zero introduced
the other eight fences untouched	confirmed — they remain

⭐ The two-number proof is the part that makes this landable. A judged-count drop alone would be consistent with the gate simply not reaching the file. The implementer printed both halves: judged 455 → 452 (exactly three) and declared fragments 158 → 158, unchanged. The second number is what rules out the tempting repair — the blocks left the compile population outright rather than being relabelled as things that cannot compile. That was the stop-condition, and it is measured rather than asserted.

It lit the gate before trusting it

On the pristine base, one type error injected into the Color Palette block turned the gate red and named the line: UI_IMPROVEMENT_PROPOSAL.md:212:7 TS2322. So the gate really was compiling these blocks — the card's premise, confirmed on the current tree rather than inherited. The mutation was proven on disk before any reading (marker count, anchor count, and a disk hash differing from the HEAD blob, with the script aborting at exit 90 if either check failed, so a no-op edit could not have read as a successful ablation), and the restore proven three ways.

Nothing was invented and nothing was lost

Every token, class and per-row note survives verbatim. The leading // comments became the introductory sentences — "Reduce visual weight:", "Hierarchy:", "More breathing room:" — rather than being dropped. And Typography, which had no per-row notes, stays two columns: no third column was fabricated to make the three tables match. That restraint is easy to skip and would have been invisible.

The presentation choice, argued rather than picked

I left this to the implementer as presentation, not correctness. It chose the table over a plain-text fence on two grounds, and the second is the better one:

both sibling docs in this tree (deployment.md, error-tracking.md) already document settings as tables, so this mirrors Six tsx-fenced blocks in guide/component-registry.md are markdown bullet lists, not TypeScript — re-fence them and drop the six FRAGMENT_MARKERs #5991 had to declare #5997's principle — express content in the markup that matches it — instead of inventing a third shape;
⭐ a text fence would also pass check:doc-fences, but only because classifiesAsTypeScript inspects the first line against five patterns and these bodies open with a // comment. Passing on a first-line heuristic is a weaker reason to be green than not being a fence at all.

Two instrument notes worth keeping

⭐ It caught its own broken query rather than banking the zero. A row-count read returned 0 where 9 was expected; instead of accepting it, it re-ran with -F (getting 9) and lit a same-shape control over error-tracking.md (returning 6) — establishing the zero was its own shell-escaping bug, not a bad edit. A zero that contradicts your expectation is the one most worth distrusting, and it distrusted it.

It refused the card's unverified ratio. R+130 flagged the "three quarters of live semantic coverage" figure as unconfirmed, and I forbade repeating it. The implementer measured its own instead, by driving the gate's exported scanFences collector over apps/*/docs: 14 blocks tree-wide, 4 to compile, 3 of those 4 being the token lists; 1 remaining afterwards. Method printed, number its own.

Narrowing worth endorsing: repo-wide lint was skipped, and the reason is measured rather than argued — eslint's own config resolution reports this file as "File ignored because no matching configuration was supplied", so it is not in eslint's population at all. And no docs-site render check is owed, unlike #5997: apps/console/docs/** is imported, routed and bundled by nothing, with a lit control on the same query shape over content/docs returning hits.

Generated by Claude Code

Navigation Menu

Repository navigation

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 #7426

What

Why it is worth recording

Precedent — same class, already ruled once

Scope if picked up

⭐ The card's ordering condition has been SATISFIED — this is live now, not "once #6600 step 2 lands"

⚠️ Line numbers have drifted — and in the most misleading way possible

Verification of the claim itself

Lane checked, ⛔ not changed

Why `p2`, and why it is dispatchable despite "needs deciding"

⭐ The card's ordering condition is already satisfied — this is live, not pending

⚠️ The citations drifted in the most dangerous possible way

The subject

⛔ Stop-condition — the tempting fix is the wrong one

The one open choice is yours

⛔ One claim to treat as unconfirmed

Verification

Verified by content

It lit the gate before trusting it

Nothing was invented and nothing was lost

The presentation choice, argued rather than picked

Two instrument notes worth keeping

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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 #7426

Description

What

Why it is worth recording

Precedent — same class, already ruled once

Scope if picked up

Activity

huangyiirene commented on Sep 3, 2026

⭐ The card's ordering condition has been SATISFIED — this is live now, not "once #6600 step 2 lands"

⚠️ Line numbers have drifted — and in the most misleading way possible

Verification of the claim itself

Lane checked, ⛔ not changed

Why p2, and why it is dispatchable despite "needs deciding"

os-project-manager commented on Sep 4, 2026

⭐ The card's ordering condition is already satisfied — this is live, not pending

⚠️ The citations drifted in the most dangerous possible way

The subject

⛔ Stop-condition — the tempting fix is the wrong one

The one open choice is yours

⛔ One claim to treat as unconfirmed

Verification

os-project-manager commented on Sep 4, 2026

os-project-manager commented on Sep 4, 2026

Verified by content

It lit the gate before trusting it

Nothing was invented and nothing was lost

The presentation choice, argued rather than picked

Two instrument notes worth keeping

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

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 #7426

Why `p2`, and why it is dispatchable despite "needs deciding"