tooling: compile `@example` blocks in `.ts` sources (and code inside template literals) under the doc-snippet gate — three measured instances (#7974 `useSpecGesture`, #7976 DESIGN.md, #7977 mdx Output Example) share the blind spot

[os-zhuang]

Filed by the director seat under the #7974 ruling (decision batch #70, 2026-09-07). Triage named this as a separate gate question with its own population; that population is now three cards.

The blind spot

check-doc-snippet-types.mjs compiles fenced blocks in Markdown documents. It does not read:

• JSDoc @example blocks in .ts / .tsx sources — finding(mobile): useSpecGesture's own @example passes a scalar swipe.direction, which its declared SpecSwipeDirection[] rejects — and the implementation carries the lenient cast that hides it #7974: packages/mobile/src/useSpecGesture.ts:72 shipped an example that fails TS2322 and was never compiled by anything;
• code inside template literals — finding(vscode-extension): nothing binds DESIGN.md's hand-copied Export-to-React preamble to the generator it mirrors #7976 (DESIGN.md) and docs(vscode-extension): the Export to React page documents a clipboard the command never writes, and an example missing the side-effect import #7977 (mdx "Output Example"): tsc sees a string, not code.

Scope

• Extend the gate (or add a sibling) to extract @example blocks from exported symbols' JSDoc under packages/*/src/** and compile them against the built types, with the same ledger / exemption discipline the Markdown gate uses (UNGATED_DOCS-style burn-down if the first run is large).
• Template-literal code: decide per case whether to extract (a fenced marker inside the literal) or to exempt with a reason; do not attempt to parse arbitrary strings.
• First run: report the count of failing examples on this card before enforcing; enforce with a ledger that only shrinks.

Acceptance

• finding(mobile): useSpecGesture's own @example passes a scalar swipe.direction, which its declared SpecSwipeDirection[] rejects — and the implementation carries the lenient cast that hides it #7974's example (post-fix) is compiled by the gate and a planted scalar direction fails it
• ledger and count recorded
• gate documented next to the Markdown gate

Refs #7974, #7976, #7977, #5174.

[claude]

Deferred at candidate selection, with the known pit recorded so the next dispatcher does not re-derive it — domain:devx @ objectui execution seat, PM session session_01FhBNJcLRZLe8M87VcUgpKr, 2026-09-07T07:44Z. Labels untouched; this stays pm:queue.

Why not now. The gate this card extends, scripts/check-doc-snippet-types.mjs, is the hot file of the #5174 burn-down (batches 35–37: PR #8271 in the merge queue, packages/fields/README.md and the root README.md still to go), under a strictness-region licence whose hash (2749d53ae3a8df033a53b8d7a354fa7e22ee2d1a17f6ad0c3d61122e904e084b, the ── Fence scanning banner to EOF) every batch must leave byte-identical. An @example extractor that touches the compile harness moves that region; a sibling script that imports the harness's exports (scanFences, compileSnippets are already exported and were used as the batch-35 census instrument) does not. Same-file serial: this card waits until batch 37 lands.

Dispatch shape when it comes up: a SIBLING script (scripts/check-doc-example-types.mjs or similar) that extracts @example fences from exported symbols' JSDoc under packages/*/src/** and feeds them to the exported compile harness — ⛔ not an edit inside the licensed region; first run reports the count on this card before enforcing; ledger that only shrinks; #7974's post-fix example is the positive control (a planted scalar direction must fail). Template-literal code (#7976, #7977) is a per-case exemption with a reason, not a parser.

---

Generated by Claude Code

[claude]

Claim: PM loop round R46 — domain:devx @ objectui execution seat.
Session: session_01FhBNJcLRZLe8M87VcUgpKr
Branch: claude/issue-8258-jsdoc-example-gate
Worktree: /home/user/objectui-issue-8258
Domain: domain:devx
File surface: a new scripts/check-doc-example-types.mjs (a SIBLING importing scripts/check-doc-snippet-types.mjs's exported harness — scanFences, compileSnippets, analyze), its test under scripts/__tests__/, and one check:* line in the root package.json. ⛔ No edit inside check-doc-snippet-types.mjs's licensed strictness region (the ── Fence scanning banner to EOF, hash 2749d53ae3a8df033a53b8d7a354fa7e22ee2d1a17f6ad0c3d61122e904e084b); ⛔ not .github/workflows/**; ⛔ no packages/*/src/** edit except a JSDoc @example this gate's own first run proves broken AND whose package is domain:devx — anything else is a filed finding.
Dispatch: one os-dev subagent of this session (mode:subagent, model: opus); dispatch note follows. Same-file family serial cleared: #5174's batch 37 (PR #8312) merged at 11:32:20Z and that card is closed. Labels pm:queue → pm:dispatched and assignee set in one write, read back at 2026-09-07T11:34Z.

---

Generated by Claude Code

[claude]

Dispatched — domain:devx @ objectui execution seat, PM session session_01FhBNJcLRZLe8M87VcUgpKr, R46, 2026-09-07T11:35Z. The only dev in flight; #5174 closed at 11:33Z, which released this card's same-file-family serial.

Dev. One os-dev subagent of this session on branch claude/issue-8258-jsdoc-example-gate, worktree /home/user/objectui-issue-8258, base origin/main at c84259489 or newer. Race re-read at 11:34Z: the newest Claim: on this card is 5570009153, naming that branch.

Brief, in one paragraph. Measurement first, as the card orders: a census funnel over @example in packages/*/src/** (upper bound measured on main: 156 files, 334 occurrences) narrowed step by step — exported vs local symbol, source vs __tests__, fenced vs bare-indented, code vs prose — so the enforced population is derived rather than asserted; the count goes on this card before anything is enforced. Then the gate as a SIBLING script (scripts/check-doc-example-types.mjs) importing the Markdown gate's exported harness (scanFences, compileSnippets, analyze), ⛔ never an edit inside its licensed strictness region (hash 2749d53ae3a8df033a53b8d7a354fa7e22ee2d1a17f6ad0c3d61122e904e084b, verified on base and head). Shrink-only ledger in the UNGATED_DOCS idiom, one row per failing example naming the card that owns it; the negative control asks whether a PASSING example is actually BOUND (an example that compiles because nothing checks it is the defect this gate exists to prevent); the positive controls are four legs on the committed tree — planted scalar RED, deleted live ledger row RED, stale ledger row RED, unmodified GREEN. Template-literal code (#7976, #7977) is decided per case under the four axes, and "no rule, exempt with a reason" is an acceptable measured answer — ⛔ no parsing of arbitrary strings.

Premise the seat measured, which changes the card's acceptance criterion: #7974 is still OPEN and its defect is still on main (packages/mobile/src/useSpecGesture.ts:69–75, the scalar direction inside swipe), and it is labelled domain:ui — another lane's card, ⛔ not this dev's to fix. So the card's "post-fix" phrasing cannot be met as written: the gate reds on day one over a live filed defect, which is precisely what its own ledger clause is for. That example becomes ledger row one, naming #7974; when that fix lands, the row's removal is that card's business and this gate reds if the row outlives the defect. #7977 is CLOSED (completed) — its outcome is read before the template-literal call is made; #7976 is open in this lane.

Also declared: ⛔ no packages/*/src/** edit except an @example this gate's own first run proves broken AND whose package is domain:devx; anything else is a filed finding. pnpm check:doc-snippets must stay green with its numbers unchanged (229 scanned / 229 covered / 0 ungated / 631 of 631 judged) — the sibling may not perturb the gate it borrows from.

---

Generated by Claude Code