cursedbelt 0.0.0 → 2.3.0

package/scripts/guardrailsEnforce.ts

@@ -0,0 +1,1741 @@
+#!/usr/bin/env bun
+// fu-guardrails-enforce: mechanical STANDARDS.md rules checked by script instead of by
+// review. `cursedbelt/STANDARDS.md` §4/§4a documents several rules (`no-raw-overflow`,
+// `no-raw-inputs`, `no-hardcoded-colors`, `no-raw-action-button`) as "rules today,
+// automated by fu-guardrails-enforce" — this script IS that enforcement. Biome has no
+// custom-rule/plugin wired up for these yet, so a standalone scan is the pragmatic
+// mechanism (same pattern as `cursedshell/scripts/buildCheck.ts`: a small Bun script
+// invoked from each package's `lint`/`done` script, exiting non-zero on violation).
+//
+// Usage:
+//   bun run ../cursedbelt/scripts/guardrailsEnforce.ts <rule>[,<rule>...] [--scope <name>]
+//     [--reimplements <Name,Name,…>] [root...]
+//
+// `--scope <name>` selects the ratchet baseline row (see "Ratchet baseline" below) for
+// the calling package — `cursedbelt` and `cursedshell` each pass their own scope name
+// from their `lint` script. Omitting `--scope` defaults every rule's baseline to 0.
+//
+// Currently implemented rules:
+//   no-raw-action-button — STANDARDS.md §4a: "a plugin or generated app must not render
+//     a raw <button> for an action (a raw <button> is acceptable only for a purely
+//     presentational toggle/tab that carries no destructive or data-mutating intent)."
+//   no-raw-overflow — STANDARDS.md §4: don't hand-write `overflow(-x|-y): auto|scroll`
+//     (inline style or Tailwind `overflow(-x|-y)-auto|scroll` className) on a scroll
+//     container; use the cursedbelt `ScrollArea` primitive.
+//   no-raw-inputs — STANDARDS.md §4: don't drop a bare <input>/<select>/<textarea> into a
+//     page; use the cursedbelt `Field` layer / specialized inputs.
+//   no-hardcoded-colors — STANDARDS.md §4: don't write a hex or literal-argument
+//     rgb()/rgba()/hsl()/hsla() color in component source; use the theme tokens in
+//     `cursedbelt/theme.css` (`var(--token)`, or `color-mix(in srgb, var(--token) NN%,
+//     transparent)` for alpha).
+//   no-raw-modal-footer — STANDARDS.md §4: a `Modal`/`Drawer`'s `footer` prop must be an
+//     `ActionBar` — their footer slot is unpadded by design, ActionBar owns footer chrome
+//     (padding, border-t, mobile keyboard/safe-area). Scoped to `<Modal`/`<Drawer` tags
+//     only — other components with an unrelated `footer` prop (AuthCard, VirtualList, …)
+//     are not this convention and are not scanned.
+//   control-height-tokens — STANDARDS.md task cbux-41: a control-class primitive's
+//     footprint comes from the `--control-h-*` token (theme.css), never a literal
+//     Tailwind height step (`h-8`/`h-9`/`h-10`/`h-11`/`h-12` — the exact hardcoded
+//     pixel-scale steps the token replaced) or an arbitrary literal pixel height
+//     (`h-[42px]`), and padding is horizontal-only — never a raw `py-*` on the same
+//     line as a field-style marker (`rounded-field`/`border-field-border`/
+//     `bg-field-bg`/`--control-h-`). Scoped to a small, explicit list of cursedbelt's
+//     own control-class component files (see `CONTROL_HEIGHT_FILES` below) — NOT the
+//     whole `src/react` tree — so an unrelated element (a sparkline `<svg
+//     className="h-8">`, a Progress bar's `h-1.5` track) in some other file never
+//     false-positives.
+//
+//   no-raw-data-table — all-apps-tables.md (owner, 2026-08-14): no hand-rolled `<table>` —
+//     use `cursedbelt/react/data-table`'s `DataTable`, which carries sorting, a global
+//     filter, column visibility, pagination and the phone card tier. The rule is on the
+//     ELEMENT rather than on "did it remember to sort", because a scanner cannot decide the
+//     latter and a rule that guesses is one people route around. cursedbelt's own DataTable
+//     subtree, the markdown/rich-text/spreadsheet renderers and `*.spec|test.*` fixtures are
+//     exempt by construction; a genuine exception (a diff, an editable grid) takes an
+//     opt-out with a reason, which is checked over the whole contiguous comment block above.
+//
+//   no-tailwind-palette — DESIGN.md §3 / UX_STANDARDS.md §6.6: no raw Tailwind palette
+//     class (`bg-slate-800`, `hover:text-red-500`, `dark:border-zinc-700/40`). Those are
+//     Tailwind's own colours, not the theme's tokens: they do not move when the theme
+//     moves, so an app painted in them has silently opted out of every future design fix.
+//     `no-hardcoded-colors` catches the hex/rgb half of this; this catches the half a
+//     Tailwind codebase actually writes. Semantic classes (`bg-card`,
+//     `text-muted-foreground`), arbitrary token values (`bg-[var(--surface-2)]`) and
+//     `white`/`black`/`transparent`/`current` are not matched.
+//
+//   no-raw-title-attr — DESIGN.md §4 ("Help Context Disclosing"): no native `title=""`
+//     on a DOM element. It does not exist on a touch device, waits ~500ms, cannot be
+//     themed, and reads inconsistently to a screen reader. Use cursedbelt's `Tooltip`,
+//     or `InfoHint` for the `(i)` beside a heading. Only LOWERCASE (DOM) tags are
+//     scanned — `title` on a component is that component's own prop, `<title>`
+//     inside an SVG is the correct accessible name for a graphic, and `title` on an
+//     `<iframe>` is the frame's required accessible name (WCAG 4.1.2), not a hint.
+//
+//   micro-typography-floor — DESIGN.md §4: no explicit text size below 12px
+//     (`text-[11px]`, `fontSize: 10`, `font-size: 0.625rem`). The theme scale already
+//     carries the floor; what it cannot carry is how easy the literal is to write.
+//     Semantic classes are never matched — `text-xs` IS 12px. A non-text glyph takes
+//     the per-line opt-out.
+//
+//   no-native-dialog — DESIGN.md core mandate: no `window.confirm` / `window.prompt` /
+//     `window.alert`. The browser draws them outside the page, so no stylesheet reaches
+//     them; they block the main thread; a browser can SUPPRESS a repeat dialog, after
+//     which the guard returns false and a destructive action is silently refused (or a
+//     `prompt` returns null and the rename quietly does nothing); and a smoke cannot
+//     assert one, because it never enters the DOM. cursedbelt has shipped the styled,
+//     awaitable replacements the whole time — `confirm`, `guardWithConfirm`, `prompt`,
+//     or `ConfirmDialog` in-tree. A bare `confirm(` in a file that IMPORTS the belt one
+//     is the belt one and is not matched; `*.spec|test.tsx` fixtures and cursedbelt's
+//     own `react/confirm.tsx` / `react/prompt.tsx` are exempt by construction.
+//
+//   no-fast-tooltip — owner, 2026-09-08: a hover-only hint must REST before it opens.
+//     Flags a hover delay written as a numeric literal below 500ms (`delayDuration={120}`,
+//     `openDelay={300}`, `delay: { open: 0 }`) and a direct `@radix-ui/react-tooltip` /
+//     `react-hover-card` import outside cursedbelt's own wrappers. Import
+//     `HOVER_HINT_DELAY_MS` (or `HOVER_HINT_INSTANT_MS` for a tap-to-open disclosure,
+//     which is a request rather than an accident) instead of a literal. The WHY is
+//     `src/react/lib/hoverIntent.ts`.
+//
+//   no-local-reimplementation — all-apps-ux.md (owner, 2026-08-13): an app must not
+//     declare its own component under a name cursedbelt already exports. A local
+//     `EmptyState`/`Modal`/`Badge` compiles, typechecks and looks approximately right,
+//     so nothing reports it — and it is precisely why a fix that landed in the design
+//     system never reached the screen. The name list is passed in with
+//     `--reimplements <Name,…>` from `fleet/standards/CURSEDBELT_INVENTORY.md`; with no
+//     list the rule is inert rather than guessing.
+//
+// Opt-out (mirrors this repo's existing `biome-ignore lint/<rule>: <reason>` convention —
+// see e.g. packages/cursedbelt/src/react/components/ButtonGroup.tsx): put a same-shaped
+// line comment as the FIRST thing inside the tag's attribute list (for `no-raw-action-button`
+// and `no-raw-inputs`) or on the line immediately above/on the offending value (for
+// `no-raw-overflow`, `no-hardcoded-colors`, and `no-raw-modal-footer`, which flag values
+// rather than whole tags):
+//
+//   <button
+//     // guardrails-ignore no-raw-action-button: presentational view switcher, not an action
+//     type="button"
+//     ...
+//
+//   // guardrails-ignore no-hardcoded-colors: SVG data-URI icon, not a themeable surface
+//   const icon = "data:image/svg+xml,...#ff0000...";
+//
+// A recognized presentational ARIA role/attribute on the tag (role="tab" | "switch" |
+// "radio" | "menuitemradio" | "presentation", or aria-selected) also counts as an
+// opt-out for `no-raw-action-button` — these are the standard markers for a
+// presentational toggle/tab widget.
+//
+// File-scoped opt-out — `guardrails-file-allow <rule>[,<rule>...]: <category> — <reason>`:
+// A handful of files legitimately violate several of these rules PERVASIVELY, not at a
+// few spots, because the rule's premise (this is ordinary themeable layout/form UI built
+// from cursedbelt primitives) simply doesn't hold for them — e.g. a WebGL/canvas art
+// surface with bespoke on-canvas controls and generative colors, or an intentionally
+// design-system-agnostic embeddable component that CANNOT import cursedbelt (barrel
+// breaks a consumer's bundler; no per-component subpath export exists). For those,
+// sprinkling dozens of per-line `guardrails-ignore`s is pure noise. Such a file may
+// declare ONE header directive instead:
+//
+//   // guardrails-file-allow no-raw-inputs,no-raw-action-button,no-hardcoded-colors:
+//   //   embeddable-primitive — dependency-free canvas studio, cannot import cursedbelt
+//
+// It is honored ONLY when it is (a) within the first 40 lines (a deliberate, reviewable
+// declaration, not buried), (b) naming known rules explicitly (never a wildcard), and
+// (c) tagged with a RECOGNIZED category — `canvas-art` (a <canvas>/WebGL rendering surface
+// whose pixels + on-surface controls are not themeable chrome) or `embeddable-primitive`
+// (a framework/design-system-agnostic component meant to drop into non-cursedbelt hosts).
+// Ordinary layout/form UI fits NEITHER category, so misuse is self-evident in review. And
+// crucially it is NOT silent: every honored file-allow is printed as an audit line each
+// run, so these stay few and visible. A malformed/unrecognized-category directive is
+// ignored (its violations still fire) and a warning is printed.
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, join, relative } from "node:path";
+
+const IGNORE_DIR_NAMES = new Set(["node_modules", "dist", "dist-deploy", ".git", "build", "coverage"]);
+const SOURCE_EXTENSIONS = new Set([".tsx", ".jsx", ".css"]);
+
+/** UI authored in a plain `.ts` file (via `React.createElement`) is still UI — it must
+ *  not evade the scanner just by dodging the `.tsx` extension (the studio component
+ *  palette shipped hardcoded hex exactly this way). A `.ts` file counts as a UI source
+ *  when it actually creates elements; pure logic modules stay unscanned. */
+const isCreateElementUi = (file: string): boolean => {
+	if (extname(file) !== ".ts") return false;
+	try {
+		return /\bcreateElement\s*\(/.test(readFileSync(file, "utf8"));
+	} catch {
+		return false;
+	}
+};
+
+interface Violation {
+	file: string;
+	line: number;
+	snippet: string;
+}
+
+interface Rule {
+	name: string;
+	description: string;
+	check: (filePath: string, source: string) => Violation[];
+}
+
+export function walk(dir: string, out: string[] = []): string[] {
+	let entries: ReturnType<typeof readdirSync>;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return out;
+	}
+	for (const entry of entries) {
+		if (IGNORE_DIR_NAMES.has(entry.name)) continue;
+		// Throwaway/private-by-convention paths (see ~/.claude/CLAUDE.md): "___*" scratch
+		// dirs/files and "*.ignore.*" files are gitignored and often hold generated build
+		// output (e.g. a demo app's Tailwind CSS build) that shouldn't be lint-scanned.
+		if (entry.name.startsWith("___") || entry.name.includes(".ignore.")) continue;
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			walk(full, out);
+		} else if (SOURCE_EXTENSIONS.has(extname(entry.name)) || isCreateElementUi(full)) {
+			out.push(full);
+		}
+	}
+	return out;
+}
+
+/** Slice from a `<button` (or similar) match to the end of its opening tag, tolerating
+ *  `{...}` JS expressions in attribute values that may themselves contain `>`. */
+function extractOpeningTag(source: string, startIndex: number): string {
+	let i = startIndex;
+	let braceDepth = 0;
+	while (i < source.length) {
+		const ch = source[i];
+		if (ch === "{") braceDepth++;
+		else if (ch === "}") braceDepth--;
+		else if (ch === ">" && braceDepth <= 0) {
+			i++;
+			break;
+		}
+		i++;
+	}
+	return source.slice(startIndex, i);
+}
+
+function lineOf(source: string, index: number): number {
+	return source.slice(0, index).split("\n").length;
+}
+
+// Blank out line and block comment bodies (keep newlines/length so indices/line numbers
+// stay valid) so a rule can't false-positive on a <button> mentioned only in prose inside
+// a comment. Deliberately naive about strings containing comment-like sequences — same
+// pragmatic tradeoff as the rest of this regex-based scan.
+function blankComments(source: string): string {
+	let out = "";
+	let i = 0;
+	while (i < source.length) {
+		const two = source.slice(i, i + 2);
+		if (two === "//") {
+			const end = source.indexOf("\n", i);
+			const stop = end === -1 ? source.length : end;
+			out += " ".repeat(stop - i);
+			i = stop;
+		} else if (two === "/*") {
+			const end = source.indexOf("*/", i + 2);
+			const stop = end === -1 ? source.length : end + 2;
+			out += source
+				.slice(i, stop)
+				.replace(/[^\n]/g, " ");
+			i = stop;
+		} else {
+			out += source[i];
+			i++;
+		}
+	}
+	return out;
+}
+
+/** Last non-whitespace char emitted so far determines whether a `/` starts a regex
+ *  literal (vs. division) — the standard "preceded by an operator/keyword, not a
+ *  value" heuristic used by lightweight tokenizers. */
+function isRegexStart(outSoFar: string): boolean {
+	let k = outSoFar.length - 1;
+	while (k >= 0 && /\s/.test(outSoFar[k])) k--;
+	if (k < 0) return true;
+	const c = outSoFar[k];
+	if ("([{,;:=&|!?+-*%^~<>".includes(c)) return true;
+	const word = outSoFar.slice(0, k + 1).match(/([A-Za-z_$][A-Za-z0-9_$]*)$/);
+	if (word) {
+		return [
+			"return", "typeof", "instanceof", "in", "of", "new", "void", "delete",
+			"throw", "case", "yield", "do", "else",
+		].includes(word[1]);
+	}
+	return false;
+}
+
+// Extends blankComments to also blank string/template-literal/regex-literal bodies, so a
+// tag-matching rule (no-raw-action-button, no-raw-inputs) can't false-positive on a
+// JSX-like substring that only exists inside a test-description string or a regex
+// assertion — e.g. `it('never a <button>', ...)`, `expect(x).toMatch(/^<button/)`. A real
+// JSX element is never written as string/regex-literal content, so this can't hide an
+// actual violation for these two rules. NOT used by the value-matching rules
+// (no-raw-overflow, no-hardcoded-colors) — those legitimately need to see inside
+// string/template literals, since that's where Tailwind classNames and inline style
+// values actually live.
+function blankNonMarkupText(source: string): string {
+	const noComments = blankComments(source);
+	let out = "";
+	let i = 0;
+	while (i < noComments.length) {
+		const ch = noComments[i];
+		if (ch === "'" || ch === '"') {
+			let j = i + 1;
+			while (j < noComments.length && noComments[j] !== ch && noComments[j] !== "\n") {
+				j += noComments[j] === "\\" ? 2 : 1;
+			}
+			const stop = Math.min(j + 1, noComments.length);
+			out += noComments.slice(i, stop).replace(/[^\n]/g, " ");
+			i = stop;
+		} else if (ch === "`") {
+			let j = i + 1;
+			let depth = 0;
+			while (j < noComments.length) {
+				if (noComments[j] === "\\") {
+					j += 2;
+					continue;
+				}
+				if (depth === 0 && noComments[j] === "`") {
+					j++;
+					break;
+				}
+				if (noComments.slice(j, j + 2) === "${") {
+					depth++;
+					j += 2;
+					continue;
+				}
+				if (depth > 0 && noComments[j] === "}") {
+					depth--;
+					j++;
+					continue;
+				}
+				j++;
+			}
+			out += noComments.slice(i, j).replace(/[^\n]/g, " ");
+			i = j;
+		} else if (ch === "/" && isRegexStart(out)) {
+			let j = i + 1;
+			let inClass = false;
+			while (j < noComments.length) {
+				const c = noComments[j];
+				if (c === "\\") {
+					j += 2;
+					continue;
+				}
+				if (c === "\n") break; // unterminated on this line — bail, don't over-blank
+				if (c === "[") inClass = true;
+				else if (c === "]") inClass = false;
+				else if (c === "/" && !inClass) {
+					j++;
+					break;
+				}
+				j++;
+			}
+			while (j < noComments.length && /[a-z]/i.test(noComments[j])) j++;
+			out += noComments.slice(i, j).replace(/[^\n]/g, " ");
+			i = j;
+		} else {
+			out += ch;
+			i++;
+		}
+	}
+	return out;
+}
+
+const RAW_BUTTON_RE = /<button\b/g;
+const IGNORE_COMMENT_RE = /guardrails-ignore\s+no-raw-action-button\s*:/;
+const PRESENTATIONAL_MARKER_RE =
+	/role\s*=\s*["'](tab|switch|radio|menuitemradio|presentation)["']|aria-selected\s*=/;
+
+const noRawActionButton: Rule = {
+	name: "no-raw-action-button",
+	description:
+		'STANDARDS.md §4a: no hand-rolled <button> for actions — use the cursedbelt Button family.',
+	check(filePath, source) {
+		const violations: Violation[] = [];
+		const scannable = blankNonMarkupText(source);
+		RAW_BUTTON_RE.lastIndex = 0;
+		for (const match of scannable.matchAll(RAW_BUTTON_RE)) {
+			// Re-extract the tag from the ORIGINAL source so opt-out comments (which were
+			// just blanked out of `scannable`) are still visible to the ignore checks.
+			const tag = extractOpeningTag(source, match.index);
+			if (IGNORE_COMMENT_RE.test(tag) || PRESENTATIONAL_MARKER_RE.test(tag)) continue;
+			const line = lineOf(source, match.index);
+			violations.push({
+				file: filePath,
+				line,
+				snippet: source.split("\n")[line - 1]?.trim() ?? "",
+			});
+		}
+		return violations;
+	},
+};
+
+/** Build a violation-scan for a value-based (non-tag) rule: a regex that matches the
+ *  offending value, an opt-out comment recognized on the match's own line or either of
+ *  the two lines immediately above it (covers both an inline trailing comment and a
+ *  comment placed on its own line before the offending statement). */
+function makeValueRule(name: string, description: string, valueRe: RegExp): Rule {
+	const ignoreRe = new RegExp(`guardrails-ignore\\s+${name}\\s*:`);
+	return {
+		name,
+		description,
+		check(filePath, source) {
+			const violations: Violation[] = [];
+			const scannable = blankComments(source);
+			const lines = source.split("\n");
+			const re = new RegExp(valueRe.source, valueRe.flags.includes("g") ? valueRe.flags : `${valueRe.flags}g`);
+			re.lastIndex = 0;
+			for (const match of scannable.matchAll(re)) {
+				const line = lineOf(source, match.index ?? 0);
+				const windowStart = Math.max(0, line - 3);
+				const context = lines.slice(windowStart, line).join("\n");
+				if (ignoreRe.test(context)) continue;
+				violations.push({
+					file: filePath,
+					line,
+					snippet: lines[line - 1]?.trim() ?? "",
+				});
+			}
+			return violations;
+		},
+	};
+}
+
+const OVERFLOW_VALUE_RE =
+	/overflow(?:-?[xy])?\s*:\s*['"`]?\s*(?:auto|scroll)\b|\boverflow(?:-[xy])?-(?:auto|scroll)\b/gi;
+
+const noRawOverflow: Rule = makeValueRule(
+	"no-raw-overflow",
+	"STANDARDS.md §4: no hand-written overflow:auto|scroll (inline style or Tailwind utility) — use the cursedbelt ScrollArea primitive.",
+	OVERFLOW_VALUE_RE,
+);
+
+const RAW_INPUT_RE = /<input\b|<select\b|<textarea\b/g;
+const noRawInputs: Rule = {
+	name: "no-raw-inputs",
+	description:
+		"STANDARDS.md §4: no bare <input>/<select>/<textarea> — use the cursedbelt Field layer / specialized inputs.",
+	check(filePath, source) {
+		const violations: Violation[] = [];
+		const scannable = blankNonMarkupText(source);
+		RAW_INPUT_RE.lastIndex = 0;
+		for (const match of scannable.matchAll(RAW_INPUT_RE)) {
+			const tag = extractOpeningTag(source, match.index);
+			const ignoreRe = /guardrails-ignore\s+no-raw-inputs\s*:/;
+			if (ignoreRe.test(tag)) continue;
+			const line = lineOf(source, match.index);
+			violations.push({
+				file: filePath,
+				line,
+				snippet: source.split("\n")[line - 1]?.trim() ?? "",
+			});
+		}
+		return violations;
+	},
+};
+
+// Hex colors, and literal-numeric-argument rgb()/rgba()/hsl()/hsla() (a leading digit
+// after the paren excludes the compliant `rgba(var(--token), 0.5)` pattern, whose first
+// argument is a CSS variable, not a literal channel value).
+const HARDCODED_COLOR_RE = /#[0-9a-fA-F]{3,8}\b|\b(?:rgb|rgba|hsl|hsla)\(\s*\d/g;
+
+const noHardcodedColors: Rule = makeValueRule(
+	"no-hardcoded-colors",
+	"STANDARDS.md §4: no hardcoded hex/rgb()/rgba()/hsl()/hsla() color — use the cursedbelt theme tokens (theme.css).",
+	HARDCODED_COLOR_RE,
+);
+
+const MODAL_OR_DRAWER_OPEN_RE = /<(?:Modal|Drawer)\b/g;
+const FOOTER_PROP_RE = /\bfooter\s*=\s*\{/g;
+const ACTIONBAR_FIRST_RE = /^\s*\(?\s*<ActionBar\b/;
+const MODAL_FOOTER_IGNORE_RE = /guardrails-ignore\s+no-raw-modal-footer\s*:/;
+
+/** Whether `footerIndex` (the start of a `footer={` match) sits inside the still-open
+ *  attribute list of the nearest preceding `<Modal`/`<Drawer` tag — i.e. no top-level
+ *  (brace-depth-0) `>` closes that tag before we reach the footer prop. */
+function isInsideModalOrDrawerTag(source: string, footerIndex: number): boolean {
+	MODAL_OR_DRAWER_OPEN_RE.lastIndex = 0;
+	let tagStart = -1;
+	for (const m of source.matchAll(MODAL_OR_DRAWER_OPEN_RE)) {
+		if (m.index >= footerIndex) break;
+		tagStart = m.index;
+	}
+	if (tagStart === -1) return false;
+	let braceDepth = 0;
+	for (let i = tagStart; i < footerIndex; i++) {
+		const ch = source[i];
+		if (ch === "{") braceDepth++;
+		else if (ch === "}") braceDepth--;
+		else if (ch === ">" && braceDepth <= 0) return false;
+	}
+	return true;
+}
+
+/** Extract the balanced `{...}` expression starting at `openBraceIndex` (the `{`
+ *  immediately after `footer=`), tolerating nested braces (style objects, etc.). */
+function extractBraceValue(source: string, openBraceIndex: number): string {
+	let depth = 0;
+	let i = openBraceIndex;
+	for (; i < source.length; i++) {
+		if (source[i] === "{") depth++;
+		else if (source[i] === "}") {
+			depth--;
+			if (depth === 0) {
+				i++;
+				break;
+			}
+		}
+	}
+	return source.slice(openBraceIndex + 1, i - 1);
+}
+
+const noRawModalFooter: Rule = {
+	name: "no-raw-modal-footer",
+	description:
+		"STANDARDS.md §4: a Modal/Drawer's footer must be an ActionBar — their footer slot is unpadded by design, ActionBar owns footer chrome.",
+	check(filePath, source) {
+		const violations: Violation[] = [];
+		const scannable = blankComments(source);
+		FOOTER_PROP_RE.lastIndex = 0;
+		for (const match of scannable.matchAll(FOOTER_PROP_RE)) {
+			const footerIndex = match.index;
+			if (!isInsideModalOrDrawerTag(scannable, footerIndex)) continue;
+			const openBraceIndex = footerIndex + match[0].length - 1;
+			const value = extractBraceValue(source, openBraceIndex);
+			if (ACTIONBAR_FIRST_RE.test(value)) continue;
+			const line = lineOf(source, footerIndex);
+			const lines = source.split("\n");
+			const windowStart = Math.max(0, line - 3);
+			const context = lines.slice(windowStart, line).join("\n");
+			if (MODAL_FOOTER_IGNORE_RE.test(context) || MODAL_FOOTER_IGNORE_RE.test(value)) continue;
+			violations.push({
+				file: filePath,
+				line,
+				snippet: lines[line - 1]?.trim() ?? "",
+			});
+		}
+		return violations;
+	},
+};
+
+// ── control-height-tokens (task cbux-41) ────────────────────────────────────────
+// The exact, explicit, reviewable list of cursedbelt's own control-class component
+// files this rule scans (matched by basename, wherever they live under the scan
+// root) — every primitive named in task cbux-41's spec that renders a fixed-height
+// interactive control row. Deliberately NOT the whole `src/react` tree: an
+// unrelated component's own `h-*`/`py-*` (a sparkline, a progress track, a modal's
+// header padding) is not this convention and must never be scanned. `lib/field.ts`
+// (the token/class SOURCE of truth — `fieldControlClass`, `CONTROL_HEIGHT_CLASS`)
+// is intentionally excluded, same reasoning theme.css exempts itself from
+// `no-hardcoded-colors`.
+const CONTROL_HEIGHT_FILES = new Set([
+	"Button.tsx",
+	"IconButton.tsx",
+	"Input.tsx",
+	"SelectField.tsx",
+	"ComboboxField.tsx",
+	"Autocomplete.tsx",
+	"TagsInput.tsx",
+	"DatePicker.tsx",
+	"DateRangePicker.tsx",
+	"DateTimeField.tsx",
+	"SecretInput.tsx",
+	"SegmentedControl.tsx",
+	"ColorField.tsx",
+	"MultiSelectField.tsx",
+	// cbux-42: the widget/card header row locks its height to --control-h-lg — a
+	// reintroduced literal h-10/h-[40px] here would silently detach every card
+	// header from the shared scale.
+	"WidgetHeader.tsx",
+]);
+
+// The deprecated literal Tailwind height steps the `--control-h-*` token scale
+// replaced (32/36/40/44/48px) — never preceded by a `min-`/`max-` prefix (the
+// negative lookbehind excludes `min-h-11`/`max-h-64`, which are unrelated bounds,
+// not a control's own locked footprint).
+const BANNED_HEIGHT_STEP_RE = /(?<![\w-])h-(?:8|9|10|11|12)\b/g;
+// An arbitrary literal pixel height (`h-[42px]`) — the token form is always
+// `h-[var(--control-h-*)]`, which never ends in `px]`.
+const BANNED_HEIGHT_PX_RE = /(?<![\w-])h-\[[0-9.]+px\]/g;
+// Marks a line as a field-style control's OWN row (not unrelated dropdown/list
+// padding elsewhere in the same file — e.g. a Select's portal menu item keeps its
+// own legitimate `py-*` and is never marked with any of these).
+const FIELD_MARKER_RE = /rounded-field|border-field-border|bg-field-bg|--control-h-/;
+const RAW_PY_RE = /(?<![\w-])py-[a-z0-9.[\]/]+/gi;
+const CONTROL_HEIGHT_IGNORE_RE = /guardrails-ignore\s+control-height-tokens\s*:/;
+
+const controlHeightTokens: Rule = {
+	name: "control-height-tokens",
+	description:
+		"STANDARDS.md task cbux-41: a control-class primitive's footprint comes from the --control-h-* token, never a literal h-8/h-9/h-10/h-11/h-12 or h-[Npx] height, and padding is horizontal-only — never raw py-* on the same line as a field-style marker.",
+	check(filePath, source) {
+		if (!CONTROL_HEIGHT_FILES.has(basename(filePath))) return [];
+		const violations: Violation[] = [];
+		const scannable = blankComments(source);
+		const lines = source.split("\n");
+
+		const flag = (index: number) => {
+			const line = lineOf(source, index);
+			const windowStart = Math.max(0, line - 3);
+			const context = lines.slice(windowStart, line).join("\n");
+			if (CONTROL_HEIGHT_IGNORE_RE.test(context)) return;
+			violations.push({ file: filePath, line, snippet: lines[line - 1]?.trim() ?? "" });
+		};
+
+		for (const re of [BANNED_HEIGHT_STEP_RE, BANNED_HEIGHT_PX_RE]) {
+			re.lastIndex = 0;
+			for (const m of scannable.matchAll(re)) flag(m.index ?? 0);
+		}
+
+		RAW_PY_RE.lastIndex = 0;
+		for (const m of scannable.matchAll(RAW_PY_RE)) {
+			const idx = m.index ?? 0;
+			const lineNum = lineOf(source, idx);
+			const lineText = lines[lineNum - 1] ?? "";
+			if (!FIELD_MARKER_RE.test(lineText)) continue;
+			flag(idx);
+		}
+
+		return violations;
+	},
+};
+
+// ── no-raw-zindex (02 §6.2 / 06 §1) ─────────────────────────────────────────
+// The six z-bands live in `core/slots.ts` (`Z_BANDS`, the JS source of truth)
+// and `theme.css` (`--z-*`, its CSS mirror); `portal/CCPortalProvider.tsx`
+// assigns `bandBase + stackDepth` within a band. A raw numeric z-index ANYWHERE
+// else is banned — a stray high z that paints over the `critical` band buries
+// the GuardEngine lock screen, a private-mode reveal bypass through CSS, not a
+// style nit (02 §6.2 already declared this "a lint error"; this rule is that
+// lint). Reach for `Z_BANDS.<band>` (TSX inline style) or `var(--z-<band>)`
+// (component CSS) instead.
+//
+// Matches `zIndex:`/`z-index:` immediately followed by a numeric literal (a
+// leading digit, optionally quoted). `zIndex: Z_BANDS.popover`, `z-index:
+// var(--z-sticky)`, and the CSS token definitions `--z-content: 0` all begin
+// with a letter, so none of them match.
+const RAW_ZINDEX_RE = /(?:zIndex|z-index)\s*:\s*['"`]?\d/g;
+// The band-definition sources are exempt — they necessarily hold the literals.
+// Matched by path suffix so they stay exempt wherever the scan root is set.
+const ZINDEX_EXEMPT_SUFFIXES = ["core/slots.ts", "react/portal/CCPortalProvider.tsx", "theme.css"];
+const ZINDEX_IGNORE_RE = /guardrails-ignore\s+no-raw-zindex\s*:/;
+
+const noRawZindex: Rule = {
+	name: "no-raw-zindex",
+	description:
+		"02 §6.2 / 06 §1: no raw numeric z-index — use the fixed bands (Z_BANDS.<band> in TSX inline styles, var(--z-<band>) in component CSS). The band-definition sources (core/slots.ts, portal/CCPortalProvider.tsx, theme.css) are exempt.",
+	check(filePath, source) {
+		const normalized = filePath.replace(/\\/g, "/");
+		if (ZINDEX_EXEMPT_SUFFIXES.some((suffix) => normalized.endsWith(suffix))) return [];
+		const violations: Violation[] = [];
+		const scannable = blankComments(source);
+		const lines = source.split("\n");
+		RAW_ZINDEX_RE.lastIndex = 0;
+		for (const match of scannable.matchAll(RAW_ZINDEX_RE)) {
+			const line = lineOf(source, match.index ?? 0);
+			const windowStart = Math.max(0, line - 3);
+			const context = lines.slice(windowStart, line).join("\n");
+			if (ZINDEX_IGNORE_RE.test(context)) continue;
+			violations.push({ file: filePath, line, snippet: lines[line - 1]?.trim() ?? "" });
+		}
+		return violations;
+	},
+};
+
+// ── no-raw-data-table ───────────────────────────────────────────────────────
+// The owner, 2026-08-14 (___Unsent-Todos/all-apps-tables.md):
+//
+//   *"find tables of data that are not using standardized cb filters and sorting and make
+//   them use it. I want filters and sorting on all tables in all apps and a single
+//   standardized table in cb for it that allows custom theming if ever needed but makes it
+//   IMPOSSIBLE to have tables that forgot to add sorting and filtering and bug fixes that
+//   we standardize in cb."*
+//
+// The single standardized table exists — `cursedbelt/react/data-table`'s `DataTable`, which
+// carries sorting, a global filter, column visibility, pagination, row menus, a card tier
+// for phones and a sticky header. The thing that did not exist is the "impossible" half: a
+// raw `<table>` is four keystrokes and every one of them ships a grid with no sort and no
+// filter, which is how twenty-one of them accumulated across ten apps.
+//
+// So the rule is on the ELEMENT, not on the feature: a `<table>` in app source is a
+// violation. That is deliberately blunt — "did this hand-rolled table remember to sort?" is
+// not decidable by a scanner, and a rule that guesses is a rule people learn to route
+// around. `<table>` also has no non-data uses left worth protecting: layout tables died with
+// the 90s, and the genuine exceptions (rendering a markdown document that CONTAINS a table,
+// a CSV import preview whose whole job is to look like the file) take an opt-out with a
+// reason, which is a sentence someone had to think about.
+//
+// Exempt by construction: cursedbelt's own DataTable subtree, which necessarily emits the
+// element, and any `.md`/markdown renderer path.
+const RAW_TABLE_RE = /<table\b/g;
+const RAW_TABLE_IGNORE_RE = /guardrails-ignore\s+no-raw-data-table\s*:/;
+// Matched by path suffix so they stay exempt wherever the scan root is set.
+const RAW_TABLE_EXEMPT_FRAGMENTS = [
+	"react/components/DataTable/",
+	"react/markdown/",
+	"react/rich-text/",
+	"react/spreadsheet/",
+	"react/workbook-viewer/",
+];
+
+const noRawDataTable: Rule = {
+	name: "no-raw-data-table",
+	description:
+		"all-apps-tables.md: no hand-rolled <table> — use cursedbelt's DataTable (cursedbelt/react/data-table), which carries sorting, filtering, column visibility and the phone card tier. A hand-rolled table is how a grid ships with no sort and no filter.",
+	check(filePath, source) {
+		const normalized = filePath.replace(/\\/g, "/");
+		if (RAW_TABLE_EXEMPT_FRAGMENTS.some((fragment) => normalized.includes(fragment))) return [];
+		// A spec's `<table>` is a FIXTURE, not a shipped grid — `<table />` handed to a
+		// component under test, or a markup string fed to an HTML→markdown converter. Sorting
+		// and filtering are meaningless there, and flagging them teaches people that this rule
+		// fires on things it should not, which is how a rule gets deleted.
+		if (/\.(?:spec|test)\.[tj]sx?$/.test(normalized)) return [];
+		const violations: Violation[] = [];
+		const scannable = blankComments(source);
+		const lines = source.split("\n");
+		RAW_TABLE_RE.lastIndex = 0;
+		for (const match of scannable.matchAll(RAW_TABLE_RE)) {
+			const line = lineOf(source, match.index ?? 0);
+			// The CONTIGUOUS non-blank block above, not a fixed window. Every real opt-out for
+			// this rule is a JSX comment explaining why a hand-rolled table is right here, and
+			// those run to four or five lines — a fixed 3-line window silently ignores the
+			// marker on the block's FIRST line, which is where a reader writes it. Same reason
+			// no-unguarded-editing-modal scans a block.
+			const block: string[] = [];
+			for (let i = line - 2; i >= 0 && block.length < 12; i--) {
+				const raw = lines[i] ?? "";
+				if (raw.trim() === "") break;
+				block.push(raw);
+			}
+			if (RAW_TABLE_IGNORE_RE.test(block.join("\n"))) continue;
+			violations.push({ file: filePath, line, snippet: lines[line - 1]?.trim() ?? "" });
+		}
+		return violations;
+	},
+};
+
+// ── no-unguarded-editing-modal ──────────────────────────────────────────────
+// The owner lost a half-typed password by clicking outside an editing modal,
+// which dismissed it and threw the form away with no confirmation. `Modal`/
+// `Drawer` + `isDirty` + `useDiscardGuard` fix that — but only for the modals
+// that actually opt in, and a rule nobody enforces is re-broken by the next new
+// modal without anyone noticing. This is that enforcement, in two halves:
+//
+//   (a) A `<Modal>`/`<Drawer>` whose body holds an EDITING control (a cursedbelt
+//       Field/Input/Textarea/Select/Checkbox/Switch/RichText/CodeEditor, or a raw
+//       <input>/<textarea>/<select>) must pass `isDirty`. Read-only and
+//       confirmation-only dialogs hold no such control, are not matched, and keep
+//       dismissing freely — the guard is about UNSAVED INPUT, not about modals in
+//       general, and prompting on an untouched dialog is the surest way to get the
+//       feature turned off.
+//
+//   (b) A HAND-ROLLED dialog — `role="dialog"` on an element in app source, or a
+//       Radix `<DialogContent>` outside cursedbelt's own dialog implementation —
+//       is flagged regardless of what it contains, because it bypasses the guard
+//       entirely. `apps/hobbies`' `ModalShell` was exactly this (that app was
+//       RETIRED 2026-08-25 — kept as the case that produced the rule): a backdrop
+//       `<button onClick={onClose}>` behind six dialogs, three of them forms.
+//
+// Opt-out, same shape as the other rules — on or within 3 lines above the offense:
+//   // guardrails-ignore no-unguarded-editing-modal: read-only preview, no form state
+const MODAL_TAG_OPEN_RE = /<(Modal|Drawer)\b/g;
+/** Editing controls. A dialog containing one of these can hold unsaved input. */
+const EDITING_CONTROL_RE =
+	/<(?:Field|Input|TextInput|PasswordInput|NumberInput|Textarea|TextArea|Select|MultiSelect|Combobox|Checkbox|Switch|Toggle|RadioGroup|Slider|DatePicker|ColorPicker|RichTextEditor|CodeEditor|TagInput|input|textarea|select)\b/;
+const ISDIRTY_PROP_RE = /\bisDirty\s*=/;
+/**
+ * A hand-rolled dialog: the ARIA role as a JSX ATTRIBUTE, or Radix's content
+ * primitive. The `(?<!\[)` matters — `body().querySelector('[role="dialog"]')`
+ * contains the same characters and is a test READING a dialog, not declaring one;
+ * without it every dialog spec in the fleet is a violation.
+ */
+const HANDROLLED_DIALOG_RE =
+	/(?<!\[)\brole\s*=\s*(?:['"]dialog['"]|\{\s*['"]dialog['"]\s*\})|<DialogContent\b/g;
+const EDITING_MODAL_IGNORE_RE = /guardrails-ignore\s+no-unguarded-editing-modal\s*:/;
+/**
+ * Part (b) — "don't hand-roll a dialog" — is a rule about CONSUMERS. Two trees are
+ * exempt from it, for opposite reasons:
+ *
+ *  - cursedbelt's own `src/react` IS the dialog implementation. Modal, Drawer,
+ *    Lightbox, LayoutConfigDialog and the rich-text popovers are supposed to carry
+ *    `role="dialog"` and `<DialogContent>`; that is the primitive the rule points
+ *    everyone else at. (Part (a) still applies here — a cursedbelt component that
+ *    renders a Modal full of fields must pass `isDirty` like anyone else.)
+ *  - a spec/test file renders and inspects dialogs by definition, including
+ *    deliberately-bad ones written to prove the guard fires.
+ */
+const isDialogLibrarySource = (path: string): boolean =>
+	/(^|\/)packages\/cursedbelt\/src\/react\//.test(path) ||
+	/(^|\/)src\/react\/(components|layoutEngine|rich-text|portal)\//.test(path);
+const isTestSource = (path: string): boolean => /\.(spec|test)\.[jt]sx?$/.test(path);
+
+/** The source span of one `<Modal …>…</Modal>` element, open tag included. Depth-counted
+ *  so a Modal nested inside another Modal's body does not swallow its parent's close tag. */
+function modalElementSpan(source: string, tagStart: number, tag: string): string {
+	const openRe = new RegExp(`<${tag}\\b`, "g");
+	const closeRe = new RegExp(`</${tag}\\s*>`, "g");
+	closeRe.lastIndex = tagStart;
+	let depth = 0;
+	let cursor = tagStart;
+	while (cursor < source.length) {
+		openRe.lastIndex = cursor + 1;
+		closeRe.lastIndex = cursor + 1;
+		const nextOpen = openRe.exec(source);
+		const nextClose = closeRe.exec(source);
+		if (!nextClose) return source.slice(tagStart);
+		if (nextOpen && nextOpen.index < nextClose.index) {
+			depth++;
+			cursor = nextOpen.index;
+			continue;
+		}
+		if (depth === 0) return source.slice(tagStart, nextClose.index + nextClose[0].length);
+		depth--;
+		cursor = nextClose.index;
+	}
+	return source.slice(tagStart);
+}
+
+/** The open tag's own attribute list — where `isDirty` must appear. Brace-aware so a
+ *  `>` inside an expression prop (`render={(a) => …}`) does not end the tag early. */
+function openTagOf(source: string, tagStart: number): string {
+	let braceDepth = 0;
+	for (let i = tagStart; i < source.length; i++) {
+		const ch = source[i];
+		if (ch === "{") braceDepth++;
+		else if (ch === "}") braceDepth--;
+		else if (ch === ">" && braceDepth <= 0) return source.slice(tagStart, i + 1);
+	}
+	return source.slice(tagStart);
+}
+
+const noUnguardedEditingModal: Rule = {
+	name: "no-unguarded-editing-modal",
+	description:
+		"a dialog that can hold unsaved input must be a cursedbelt Modal/Drawer AND pass isDirty — otherwise a backdrop click throws the user's edits away with no confirmation. Read-only dialogs (no editing control) are not matched.",
+	check(filePath, source) {
+		const normalized = filePath.replace(/\\/g, "/");
+		const isDialogImpl = isDialogLibrarySource(normalized) || isTestSource(normalized);
+		const violations: Violation[] = [];
+		const scannable = blankComments(source);
+		const lines = source.split("\n");
+		const scannableLines = scannable.split("\n");
+		/**
+		 * Honor the marker anywhere in the CONTIGUOUS COMMENT BLOCK immediately above
+		 * the offense, rather than in a fixed 3-line window.
+		 *
+		 * The other rules use a 3-line window, which is fine for their one-line
+		 * reasons. This rule's opt-outs are the hard cases — "this dialog cannot use
+		 * the primitive, and here is the design decision why" — so the reason runs to
+		 * four or five lines, and a fixed window silently ignores a marker on the
+		 * block's first line. Every real opt-out written for this rule hit that.
+		 *
+		 * A comment line is identified structurally: `blankComments` preserves line
+		 * structure, so a line that is non-blank in the source and blank in the
+		 * scannable copy is comment text — which covers `//`, `/* *\/` and JSX
+		 * `{/* *\/}` blocks without a second comment parser.
+		 */
+		const ignoredAt = (index: number): boolean => {
+			const line = lineOf(source, index); // 1-based
+			const block: string[] = [];
+			for (let i = line - 2; i >= 0; i--) {
+				const raw = lines[i] ?? "";
+				const blanked = scannableLines[i] ?? "";
+				if (raw.trim() === "") break; // a blank line ends the block
+				// Something was blanked on this line ⇒ it carries comment text, and what
+				// survives is only JSX-comment punctuation. The `{`/`}` allowance is what
+				// makes `{/* … */}` a comment line: braces are not comment characters, so
+				// `blankComments` leaves them behind. A bare `}` closing real code is
+				// unchanged by blanking, so it still ends the block — which is what stops
+				// an unrelated marker further up from exempting anything.
+				if (raw === blanked) break;
+				if (blanked.replaceAll(/[{}\s]/g, "") !== "") break;
+				block.push(raw);
+			}
+			return EDITING_MODAL_IGNORE_RE.test(block.join("\n"));
+		};
+
+		// (a) a Modal/Drawer holding an editing control, with no isDirty.
+		MODAL_TAG_OPEN_RE.lastIndex = 0;
+		for (const match of scannable.matchAll(MODAL_TAG_OPEN_RE)) {
+			const tagStart = match.index ?? 0;
+			const openTag = openTagOf(scannable, tagStart);
+			if (ISDIRTY_PROP_RE.test(openTag)) continue;
+			const element = modalElementSpan(scannable, tagStart, match[1] ?? "Modal");
+			if (!EDITING_CONTROL_RE.test(element)) continue;
+			if (ignoredAt(tagStart)) continue;
+			const line = lineOf(source, tagStart);
+			violations.push({ file: filePath, line, snippet: lines[line - 1]?.trim() ?? "" });
+		}
+
+		// (b) a hand-rolled dialog anywhere but cursedbelt's own dialog implementation.
+		if (!isDialogImpl) {
+			HANDROLLED_DIALOG_RE.lastIndex = 0;
+			for (const match of scannable.matchAll(HANDROLLED_DIALOG_RE)) {
+				const index = match.index ?? 0;
+				if (ignoredAt(index)) continue;
+				const line = lineOf(source, index);
+				violations.push({ file: filePath, line, snippet: lines[line - 1]?.trim() ?? "" });
+			}
+		}
+
+		return violations;
+	},
+};
+
+// ── no-tailwind-palette (DESIGN.md §3 / UX_STANDARDS.md §6.6) ───────────────
+// `no-hardcoded-colors` already bans a hex or a literal `rgb()`. It cannot see the
+// OTHER way a colour gets hardcoded, which in a Tailwind codebase is the common one:
+// `bg-slate-800`, `text-red-500`, `border-zinc-700`. Those are not tokens. They are
+// Tailwind's own palette, they do not move when the theme moves, and they are why
+// "one fix per component type" fails — an app painted in `slate-800` has opted out of
+// every future change to `--surface-2`, silently, and nothing anywhere is wrong.
+//
+// UX_STANDARDS.md §6.6 states the law ("One theme system: cursedbelt's tokens. An app
+// that hardcodes a colour has opted out of every future fix") and DESIGN.md §3 states
+// its visible consequence (badges must clear 4.5:1 in DARK mode — a palette step
+// chosen against a light mock cannot). This rule is that law, checked.
+//
+// What it matches: a Tailwind colour utility carrying a PALETTE family and a numeric
+// step, with any variant/opacity decoration around it —
+//   bg-slate-800   hover:text-red-500   dark:border-zinc-700/40   md:from-sky-300
+// What it deliberately does NOT match: the semantic aliases the theme defines
+// (`bg-card`, `text-muted-foreground`, `border-field-border`), arbitrary token values
+// (`bg-[var(--surface-2)]`), and `white`/`black`/`transparent`/`current`/`inherit`,
+// which carry no palette step and are frequently correct (an overlay scrim, an icon
+// mask). Fix by reaching for the token — `bg-[var(--surface-2)]`, `text-foreground`,
+// `border-[var(--border-subtle)]` — or, for a genuinely non-themeable surface (a
+// vendor logo, a fixed brand mark), take the per-line opt-out with the reason.
+const TAILWIND_PALETTE_FAMILIES = [
+	"slate", "gray", "zinc", "neutral", "stone",
+	"red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal",
+	"cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose",
+];
+const TAILWIND_COLOR_UTILITIES = [
+	"bg", "text", "border", "ring", "outline", "shadow", "fill", "stroke",
+	"from", "via", "to", "divide", "placeholder", "caret", "accent", "decoration",
+];
+// `(?<![\w-])` stops `--my-bg-slate-500` and `not-text-red-500` matching; the trailing
+// boundary stops `bg-red-5000`. Variants (`hover:`, `dark:`, `group-hover:`) sit BEFORE
+// the utility and are excluded by the same lookbehind only if they end in a word char —
+// they end in `:`, which is not `[\w-]`, so they pass through and the utility matches.
+const TAILWIND_PALETTE_RE = new RegExp(
+	`(?<![\\w-])(?:${TAILWIND_COLOR_UTILITIES.join("|")})-(?:${TAILWIND_PALETTE_FAMILIES.join("|")})-(?:50|100|200|300|400|500|600|700|800|900|950)\\b`,
+	"g",
+);
+
+const noTailwindPalette: Rule = makeValueRule(
+	"no-tailwind-palette",
+	"DESIGN.md §3 / UX_STANDARDS.md §6.6: no raw Tailwind palette class (bg-slate-800, text-red-500, …) — those are not tokens and do not move when the theme moves. Use the theme's semantic classes or bg-[var(--token)].",
+	TAILWIND_PALETTE_RE,
+);
+
+// ── no-raw-title-attr (DESIGN.md §4 "Help Context Disclosing") ──────────────
+// A native `title=""` is the cheapest possible tooltip and it is four separate
+// failures at once: it does not exist on a touch device (there is no hover), it
+// waits ~500ms before appearing, it cannot be styled or themed, and a screen reader
+// may read it, ignore it, or double it up with the accessible name depending on the
+// element. DESIGN.md §4 asks for explanatory text "behind interactive hover info icon
+// tooltips (i)"; UX_STANDARDS.md §5.1 states the phone half ("a control that only
+// exists on hover does not exist on a phone").
+//
+// cursedbelt has both halves already: `Tooltip` (hover + focus + touch long-press,
+// themed, portalled into the right z-band) and `InfoHint` (the literal `(i)` affordance
+// beside a section header). So this is a rule about REACHING for them.
+//
+// Scoped to a LOWERCASE JSX tag — a DOM element. `title` on a component
+// (`<Modal title=…>`, `<PageHeader title=…>`, `<WidgetHeader title=…>`) is that
+// component's own prop and is nothing to do with this; so is `<title>` inside an SVG,
+// which is the accessible NAME of the graphic and is the correct markup there.
+const LOWERCASE_TAG_RE = /<([a-z][a-zA-Z0-9-]*)\b/g;
+const TITLE_ATTR_RE = /(?:^|[\s{])title\s*=/;
+const TITLE_ATTR_IGNORE_RE = /guardrails-ignore\s+no-raw-title-attr\s*:/;
+
+const noRawTitleAttr: Rule = {
+	name: "no-raw-title-attr",
+	description:
+		'DESIGN.md §4: no native title="" on a DOM element — it does not exist on touch, waits half a second, cannot be themed and reads inconsistently to a screen reader. Use cursedbelt\'s Tooltip, or InfoHint for the (i) affordance beside a heading.',
+	check(filePath, source) {
+		if (/\.(?:spec|test)\.[tj]sx?$/.test(filePath.replace(/\\/g, "/"))) return [];
+		const violations: Violation[] = [];
+		const scannable = blankNonMarkupText(source);
+		const lines = source.split("\n");
+		LOWERCASE_TAG_RE.lastIndex = 0;
+		for (const match of scannable.matchAll(LOWERCASE_TAG_RE)) {
+			// `<title>` is the SVG/`<head>` element, not a title ATTRIBUTE.
+			if (match[1] === "title") continue;
+			// `<iframe title>` is the frame's ACCESSIBLE NAME, not a hover hint — the
+			// same argument that exempts an SVG `<title>` above. WCAG 4.1.2 requires it
+			// and there is no Tooltip equivalent, so flagging it would only teach people
+			// to delete an a11y requirement. (unit 11)
+			if (match[1] === "iframe") continue;
+			const index = match.index ?? 0;
+			const tag = extractOpeningTag(source, index);
+			if (!TITLE_ATTR_RE.test(tag)) continue;
+			if (TITLE_ATTR_IGNORE_RE.test(tag)) continue;
+			const line = lineOf(source, index);
+			const windowStart = Math.max(0, line - 3);
+			if (TITLE_ATTR_IGNORE_RE.test(lines.slice(windowStart, line).join("\n"))) continue;
+			violations.push({ file: filePath, line, snippet: lines[line - 1]?.trim() ?? "" });
+		}
+		return violations;
+	},
+};
+
+// ── no-local-reimplementation (the reason the Optimized-Tasks queue exists) ─
+// The owner, 2026-08-13 (___Todo-Ready/all-apps-ux.md):
+//
+//   *"apply the quality SaaS product enhancement recommendations everywhere in all the
+//   apps because these patterns were everywhere and we need ONE FIX FOR EACH COMPONENT
+//   TYPE instead of asking for judgments on every one individually."*
+//
+// One fix per component type is impossible while an app ships its own `EmptyState`,
+// its own `Modal`, its own `Badge`. The fix lands in cursedbelt and the app keeps
+// rendering its copy — and because the copy compiles, typechecks, tests green and
+// looks approximately right, nothing anywhere reports it. The only symptom is that
+// the design pass "did not take", months later, on a screen nobody re-reviewed.
+//
+// The signal is mechanical and it is the NAME: a component declared in app source
+// under a name cursedbelt already exports is either a duplicate (delete it, import the
+// real one) or a name collision that will mislead every future reader of that file
+// (rename it). Both are worth a line of a person's attention, and neither is
+// detectable any other way — an import cursedbelt does not have is not an error.
+//
+// The inventory that feeds this list is `fleet/standards/CURSEDBELT_INVENTORY.md`;
+// `--reimplements <Name,Name>` passes it in, so the list lives with the inventory and
+// not buried in this file. With no list passed the rule is inert rather than guessing.
+const REIMPL_IGNORE_RE = /guardrails-ignore\s+no-local-reimplementation\s*:/;
+/** Set by `--reimplements` (CLI) or `setReimplementedNames()` (library use). */
+let REIMPLEMENTED_NAMES: string[] = [];
+export function setReimplementedNames(names: readonly string[]): void {
+	REIMPLEMENTED_NAMES = [...names];
+}
+
+const noLocalReimplementation: Rule = {
+	name: "no-local-reimplementation",
+	description:
+		"all-apps-ux.md: an app must not declare its own component under a name cursedbelt already exports — a local copy is why a fix that landed in the design system did not reach the screen. Import the shared one, or rename the local thing so it stops claiming to be it.",
+	check(filePath, source) {
+		if (REIMPLEMENTED_NAMES.length === 0) return [];
+		const normalized = filePath.replace(/\\/g, "/");
+		if (/\.(?:spec|test)\.[tj]sx?$/.test(normalized)) return [];
+		// cursedbelt IS the implementation of these names.
+		if (/(^|\/)packages\/cursedbelt\/src\//.test(normalized)) return [];
+		const violations: Violation[] = [];
+		const scannable = blankComments(source);
+		const lines = source.split("\n");
+		for (const name of REIMPLEMENTED_NAMES) {
+			const re = new RegExp(`(?:export\\s+)?(?:function|class)\\s+${name}\\b|(?:export\\s+)?const\\s+${name}\\s*[:=]`, "g");
+			for (const match of scannable.matchAll(re)) {
+				const index = match.index ?? 0;
+				const line = lineOf(source, index);
+				const windowStart = Math.max(0, line - 3);
+				if (REIMPL_IGNORE_RE.test(lines.slice(windowStart, line).join("\n"))) continue;
+				violations.push({ file: filePath, line, snippet: lines[line - 1]?.trim() ?? "" });
+			}
+		}
+		return violations;
+	},
+};
+
+// ── micro-typography-floor ──────────────────────────────────────────────────────
+// DESIGN.md §4: *"Secondary metadata variables, text placeholders, and descriptions
+// must maintain a minimum body scale of 12px–13px. Lighten dark gray text values to
+// maintain clean scannability against pure black background layers."*
+//
+// The theme scale already carries the floor (`--text-caption` 12px, `--text-data`
+// 13px, and `--text-meta` was raised from 11px to 12px in unit 11 for exactly this
+// reason). What it could not carry is the four keystrokes it takes to write
+// `text-[11px]` instead — and nothing reported those, because a font size is not
+// wrong to any compiler. This is the report.
+//
+// It matches an explicit sub-12px size wherever one can be written: a Tailwind
+// arbitrary value (`text-[11px]`, `text-[0.6875rem]`), an inline style
+// (`fontSize: 10`, `fontSize: '11px'`), or a CSS declaration (`font-size: 11px`).
+// It does NOT guess at semantic classes — `text-xs` is 12px and legal, and a rule
+// that flagged it would be arguing with the scale rather than enforcing it.
+//
+// 🔴 A genuine exception exists and is not rare: a NON-TEXT glyph (a superscript
+// marker, a badge counter inside a 16px dot, an axis tick on a sparkline) is not
+// "secondary metadata" and the clause does not reach it. Take the per-line
+// `guardrails-ignore micro-typography-floor: <reason>` opt-out there — a sentence
+// somebody had to think about — rather than raising a baseline.
+const MIN_TEXT_PX = 12;
+const MICRO_TYPE_IGNORE_RE = /guardrails-ignore\s+micro-typography-floor\s*:/;
+// text-[11px] | text-[0.6875rem] | fontSize: 11 | fontSize: '11px' | font-size: 11px
+const MICRO_TYPE_RE =
+	/(?:text-\[(\d*\.?\d+)(px|rem|em)\]|fontSize\s*:\s*['"]?(\d*\.?\d+)(px|rem|em)?['"]?|font-size\s*:\s*(\d*\.?\d+)(px|rem|em))/g;
+
+function toPx(value: number, unit: string | undefined): number {
+	if (unit === "rem" || unit === "em") return value * 16;
+	return value;
+}
+
+const microTypographyFloor: Rule = {
+	name: "micro-typography-floor",
+	description: `DESIGN.md §4: secondary text may not sit below ${MIN_TEXT_PX}px. Use the theme scale (text-caption 12px / text-data 13px / text-meta 12px) — or take the per-line guardrails-ignore for a non-text glyph.`,
+	check(filePath, source) {
+		if (/\.(?:spec|test)\.[tj]sx?$/.test(filePath.replace(/\\/g, "/"))) return [];
+		const violations: Violation[] = [];
+		const lines = source.split("\n");
+		MICRO_TYPE_RE.lastIndex = 0;
+		for (const match of source.matchAll(MICRO_TYPE_RE)) {
+			const raw = match[1] ?? match[3] ?? match[5];
+			const unit = match[2] ?? match[4] ?? match[6];
+			if (raw === undefined) continue;
+			// A bare `fontSize: 12` in JS means px; a bare number with no unit in CSS is
+			// invalid and never reaches a browser, so treating both as px is right.
+			const px = toPx(Number(raw), unit);
+			if (!Number.isFinite(px) || px >= MIN_TEXT_PX) continue;
+			const line = lineOf(source, match.index ?? 0);
+			const windowStart = Math.max(0, line - 3);
+			if (MICRO_TYPE_IGNORE_RE.test(lines.slice(windowStart, line).join("\n"))) continue;
+			if (MICRO_TYPE_IGNORE_RE.test(lines[line - 1] ?? "")) continue;
+			violations.push({ file: filePath, line, snippet: lines[line - 1]?.trim() ?? "" });
+		}
+		return violations;
+	},
+};
+
+// ── choice-needs-empty-state / no-select-as-action-menu ─────────────────────────
+// The owner, 2026-08-21, on music's `File under…` control:
+//
+//   *"I checked a track and clicked the File under… dropdown and there were no choices
+//   in it. I don't know what the purpose of it is … if it's empty because I don't have
+//   whatever it should link the track to then there should be a create option for
+//   whatever goes in there … All dropdowns should be checked for these types of UX
+//   issues now."*
+//
+// "Should be checked" is the ask these two rules answer. Checking every dropdown once,
+// by reading, is a sweep that decays the day it finishes; there were 80 data-driven
+// choice controls across 13 apps when this was written, and the next one is written
+// tomorrow. So the check runs on every gate instead.
+//
+// `choice-needs-empty-state` — a choice control whose options come from DATA must say
+// what belongs in it when there is none. A list built from a CONSTANT is exempt by
+// construction: `SORTS.map(…)` cannot be empty, and flagging it would teach people the
+// rule fires on things it should not, which is how a rule gets deleted. So "from data"
+// means: mapped from something that is neither a SCREAMING_SNAKE constant nor a
+// module-level array literal in the same file.
+//
+// `no-select-as-action-menu` — a select pinned to `value=""` is not a form field. It is
+// an action menu, and it was built from the one control whose popup the page CANNOT
+// style (the browser draws a native `<select>`'s list outside the document; see
+// `NativeSelect`'s header for the Windows/Chrome incident). That is the whole of the
+// owner's *"the dropdowns open with a gray bland styling"* — nothing was misstyled.
+// `ChoiceMenu` is the right control: Radix all the way down, a create row first, and an
+// empty state that is a way forward rather than a blank popup.
+const CHOICE_COMPONENTS = ["NativeSelect", "SelectField", "MultiSelectField", "ComboboxField"];
+const CHOICE_EMPTY_IGNORE_RE = /guardrails-ignore\s+choice-needs-empty-state\s*:/;
+const ACTION_MENU_IGNORE_RE = /guardrails-ignore\s+no-select-as-action-menu\s*:/;
+
+interface JsxSpan {
+	/** The opening tag only — where the props are. */
+	open: string;
+	/** Opening tag plus children, for a container element. */
+	whole: string;
+}
+
+/**
+ * The source span of one JSX element, without a parser.
+ *
+ * The naive "take the next 2 KB" reads a sibling's `.map()` as this element's, and
+ * `seg.split('>')[0]` — the other obvious shortcut — truncates the opening tag at the
+ * first `>` inside an arrow function, which every `onChange={(e) => …}` has. So this
+ * walks the opening tag tracking brace depth and quotes, then matches the closing tag
+ * counting nested same-name elements.
+ */
+function jsxElementSpan(source: string, start: number, name: string): JsxSpan | null {
+	let depth = 0;
+	let quote: string | null = null;
+	let i = source.indexOf(name, start) + name.length;
+	for (; i < source.length; i++) {
+		const ch = source[i] as string;
+		if (quote) {
+			if (ch === quote && source[i - 1] !== "\\") quote = null;
+			continue;
+		}
+		if (ch === '"' || ch === "'" || ch === "`") {
+			quote = ch;
+			continue;
+		}
+		if (ch === "{") depth++;
+		else if (ch === "}") depth--;
+		else if (ch === ">" && depth === 0) break;
+	}
+	if (i >= source.length) return null;
+	const open = source.slice(start, i + 1);
+	if (source[i - 1] === "/") return { open, whole: open };
+	const closeTag = `</${name}>`;
+	const openTag = `<${name}`;
+	let cursor = i + 1;
+	let nested = 0;
+	for (;;) {
+		const nextClose = source.indexOf(closeTag, cursor);
+		if (nextClose === -1) return { open, whole: source.slice(start) };
+		const nextOpen = source.indexOf(openTag, cursor);
+		if (nextOpen !== -1 && nextOpen < nextClose) {
+			nested++;
+			cursor = nextOpen + openTag.length;
+			continue;
+		}
+		if (nested === 0) return { open, whole: source.slice(start, nextClose) };
+		nested--;
+		cursor = nextClose + closeTag.length;
+	}
+}
+
+const MAP_SOURCE_RE = /([A-Za-z_$][\w$]*(?:\??\.[A-Za-z_$][\w$]*)*)\s*\.map\(/g;
+const OPTIONS_PROP_RE = /\boptions=\{([A-Za-z_$][\w$]*(?:\??\.[A-Za-z_$][\w$]*)*)\}/g;
+
+/**
+ * Is this expression's list something the CALL SITE owns, or something handed to it?
+ *
+ * Three exemptions, and each one is a class of false positive rather than a let-off:
+ *
+ *  - **A constant** — `SORTS.map(…)`, or a module-level array literal in this file.
+ *    It cannot be empty at runtime, so an empty state would be dead code.
+ *  - **A pass-through prop** — a BARE identifier this file never declares (`options`,
+ *    `pageSizeOptions`) is destructured from props, and a generic component cannot
+ *    write the empty state: it does not know whether it is showing categories or
+ *    countries. Its job is to FORWARD `emptyLabel`, which is why the belt's controls
+ *    take one. The rule follows the data to the screen that owns it.
+ *  - A member expression is never exempt on those grounds. `summary?.categories`,
+ *    `data.lists`, `tracker.statuses` — that is fetched state, and the file reading it
+ *    knows exactly what belongs in the list. This is the shape of the owner's own
+ *    report, so exempting it would exempt the bug.
+ */
+function isExemptChoiceSource(expression: string, source: string): boolean {
+	const base = expression.split(/[.?[]/)[0] ?? expression;
+	if (/^[A-Z0-9_]+$/.test(base)) return true;
+	if (new RegExp(`^(?:export\\s+)?const\\s+${base}\\b[^\\n=]*=\\s*(?:\\[|Object\\.)`, "m").test(source)) {
+		return true;
+	}
+	if (expression !== base) return false;
+	// A name pinned to a constant list is still a constant list — `const options =
+	// ROLES.map(…)` cannot be empty either. One level of indirection only: past that
+	// it is a data pipeline and the answer stops being obvious from the file.
+	const alias = new RegExp(`(?:const|let)\\s+${base}\\b[^\\n=]*=\\s*([A-Za-z_$][\\w$]*)`, "m").exec(source);
+	if (alias?.[1] && /^[A-Z0-9_]+$/.test(alias[1])) return true;
+	const declared = new RegExp(
+		`(?:const|let|var)\\s+${base}\\b|(?:const|let|var)\\s*\\[\\s*${base}\\b|function\\s+${base}\\b|import[^;]*\\b${base}\\b`,
+	);
+	return !declared.test(source);
+}
+
+/** The dynamic sources this element's choices come from, if any. */
+function dynamicChoiceSources(span: JsxSpan, source: string): string[] {
+	const found: string[] = [];
+	for (const re of [MAP_SOURCE_RE, OPTIONS_PROP_RE]) {
+		const haystack = re === OPTIONS_PROP_RE ? span.open : span.whole;
+		re.lastIndex = 0;
+		for (const match of haystack.matchAll(re)) {
+			const expression = match[1];
+			if (!expression || isExemptChoiceSource(expression, source)) continue;
+			if (!found.includes(expression)) found.push(expression);
+		}
+	}
+	return found;
+}
+
+/** The contiguous non-blank block above a line — where a reader writes the opt-out. */
+function blockAbove(lines: string[], line: number): string {
+	const block: string[] = [];
+	for (let i = line - 2; i >= 0 && block.length < 12; i--) {
+		const raw = lines[i] ?? "";
+		if (raw.trim() === "") break;
+		block.push(raw);
+	}
+	return block.join("\n");
+}
+
+function eachChoiceControl(
+	filePath: string,
+	source: string,
+	visit: (span: JsxSpan, line: number) => boolean,
+): Violation[] {
+	const normalized = filePath.replace(/\\/g, "/");
+	if (/\.(?:spec|test)\.[tj]sx?$/.test(normalized)) return [];
+	const violations: Violation[] = [];
+	const scannable = blankComments(source);
+	const lines = source.split("\n");
+	for (const name of CHOICE_COMPONENTS) {
+		const re = new RegExp(`<${name}\\b`, "g");
+		for (const match of scannable.matchAll(re)) {
+			const start = match.index ?? 0;
+			const span = jsxElementSpan(scannable, start, name);
+			if (!span) continue;
+			const line = lineOf(source, start);
+			if (!visit(span, line)) continue;
+			violations.push({ file: filePath, line, snippet: lines[line - 1]?.trim() ?? "" });
+		}
+	}
+	return violations;
+}
+
+const choiceNeedsEmptyState: Rule = {
+	name: "choice-needs-empty-state",
+	description:
+		"music-app-clicking-favorite-refreshes.md: a choice control whose options come from DATA must pass `emptyLabel` — an empty popup is a dead end that reads as a broken control. Say what belongs in the list, and use ChoiceMenu where making one is possible (it puts 'New <thing>…' first). A list built from a constant is exempt automatically.",
+	check(filePath, source) {
+		if (/(^|\/)packages\/cursedbelt\/src\/react\/components\//.test(filePath.replace(/\\/g, "/"))) {
+			return [];
+		}
+		const lines = source.split("\n");
+		return eachChoiceControl(filePath, source, (span, line) => {
+			if (/\bemptyLabel[=:]/.test(span.open)) return false;
+			if (dynamicChoiceSources(span, source).length === 0) return false;
+			return !CHOICE_EMPTY_IGNORE_RE.test(blockAbove(lines, line));
+		});
+	},
+};
+
+const noSelectAsActionMenu: Rule = {
+	name: "no-select-as-action-menu",
+	description:
+		"music-app-clicking-favorite-refreshes.md: a select pinned to value=\"\" is an ACTION MENU wearing a form control — and a native <select>'s popup is drawn by the browser outside the page, where no stylesheet reaches it ('the dropdowns open with a gray bland styling'). Use ChoiceMenu: styled, a create row first, and a real empty state.",
+	check(filePath, source) {
+		if (/(^|\/)packages\/cursedbelt\/src\/react\/components\//.test(filePath.replace(/\\/g, "/"))) {
+			return [];
+		}
+		const lines = source.split("\n");
+		return eachChoiceControl(filePath, source, (span, line) => {
+			if (!/\bvalue=(?:""|\{""\}|\{''\})/.test(span.open)) return false;
+			return !ACTION_MENU_IGNORE_RE.test(blockAbove(lines, line));
+		});
+	},
+};
+
+// ── no-native-dialog ────────────────────────────────────────────────────────
+// `window.confirm` / `window.prompt` / `window.alert` — and their bare global
+// forms — are the browser's own chrome, and cursedbelt has shipped styled,
+// awaitable replacements the whole time (`confirm`, `guardWithConfirm`,
+// `prompt` from `cursedbelt/react`, or `ConfirmDialog` rendered in-tree).
+//
+// Six call sites across four satellite apps were still on the native ones in
+// 2026-08-24, beside three apps that had already migrated — which is the shape
+// of drift STANDARDS §2 describes: the primitive exists, nothing requires it,
+// so adoption is a coin toss decided by which day the code was written.
+//
+// It is not a cosmetic rule. A native dialog:
+//   · is drawn by the browser outside the page, so NO stylesheet reaches it —
+//     the same defect `no-select-as-action-menu` exists for, and a direct
+//     violation of the DESIGN.md mandate against unstyled chrome;
+//   · blocks the main thread, freezing animations and in-flight React work;
+//   · is suppressible — a browser hides repeat dialogs from a page behind
+//     "don't show me again", after which the guard silently returns false and
+//     a destructive action is REFUSED with no explanation, or a `prompt`
+//     returns null and the rename quietly does nothing;
+//   · cannot be asserted by a smoke, because it never enters the DOM.
+//
+// The check is on the CALL, which makes it decidable. `globalThis.confirm`,
+// `self.confirm`, `window.confirm` and a bare `confirm(` all match; an import of
+// cursedbelt's own `confirm`/`prompt` is exempt by construction (the file's
+// import list is read first), as are cursedbelt's own dialog internals and any
+// non-DOM code, since the rule only scans `.tsx`.
+const NATIVE_DIALOG_IGNORE_RE = /guardrails-ignore\s+no-native-dialog\s*:/;
+const NATIVE_DIALOG_RE =
+	/(?:^|[^\w.$])(?:(?:window|globalThis|self|globalThis\?)\s*\??\.\s*)?(confirm|prompt|alert)\s*\(/;
+
+/** True when this file gets `confirm`/`prompt` from cursedbelt — then a bare
+ *  `confirm(` IS the belt primitive and must not be reported.
+ *
+ *  THREE spellings count, and each one was found by a false positive:
+ *   · `import { confirm } from 'cursedbelt/react'` — the ordinary consumer form.
+ *   · `import { confirm } from '../confirm'` — cursedbelt's own components
+ *     reaching their sibling wrapper. Missing it reported every in-belt caller
+ *     of the belt's own primitive, `DeleteButton` among them.
+ *   · `const { prompt } = await import('cursedbelt/react/prompt')` — a DYNAMIC
+ *     import, which apps/music uses deliberately: `prompt` is the only other
+ *     thing on that screen pulling `Modal` (and `react-dom/client`'s
+ *     `createRoot` with it), and importing it statically put music's entry
+ *     chunk at 555 KB against a 520 KB budget. Reporting that is telling an app
+ *     to break its own byte-budget gate to satisfy this one. */
+function importsBeltDialog(source: string, fn: string): boolean {
+	const spec = `['"]cursedbelt(?:/[^'"]*)?['"]`;
+	const named = `\\{[^}]*\\b${fn}\\b[^}]*\\}`;
+	return (
+		// static, from the package
+		new RegExp(`import\\s*${named}\\s*from\\s*${spec}`, "s").test(source) ||
+		// static, from a sibling inside cursedbelt itself
+		new RegExp(`import\\s*${named}\\s*from\\s*['"][./]+(?:react/)?${fn}['"]`, "s").test(source) ||
+		// dynamic — `const { prompt } = await import('cursedbelt/react/prompt')`
+		new RegExp(`${named}\\s*=\\s*(?:await\\s+)?import\\(\\s*${spec}`, "s").test(source) ||
+		// and its type-only companion, `typeof import('…').prompt`
+		new RegExp(`typeof\\s+import\\(\\s*${spec}\\s*\\)\\.${fn}\\b`, "s").test(source)
+	);
+}
+
+const noNativeDialog: Rule = {
+	name: "no-native-dialog",
+	description:
+		"DESIGN.md core mandate: no `window.confirm` / `window.prompt` / `window.alert`. The browser draws them outside the page (no stylesheet reaches them), they block the main thread, a browser can SUPPRESS a repeat dialog — after which the guard returns false and the action is silently refused — and a smoke cannot assert one. Use `confirm` / `guardWithConfirm` / `prompt` from `cursedbelt/react`, or render `ConfirmDialog` in-tree.",
+	check(filePath, source) {
+		const unix = filePath.replace(/\\/g, "/");
+		// cursedbelt's own imperative wrappers are the replacement; they must be
+		// able to name the thing they replace.
+		if (/(^|\/)src\/react\/(confirm|prompt)\.tsx$/.test(unix)) return [];
+		// A spec is not a shipped surface: its sources are fixtures (an XSS payload
+		// string, a `describe('confirm() imperative')`), and the belt's own dialog
+		// specs necessarily call the thing they test. Same carve-out `no-raw-data-table`
+		// makes for test fixtures.
+		if (/\.(spec|test)\.tsx?$/.test(unix)) return [];
+		const raws = source.split("\n");
+		// Scan the copy with comments AND string/template literals blanked: prose
+		// above a call is not a call, and neither is `'<script>alert(1)</script>'`
+		// inside a sanitiser's fixture. `raws` keeps the real text for the snippet
+		// and the same-line opt-out.
+		const scan = blankNonMarkupText(source).split("\n");
+		const out: Violation[] = [];
+		for (const [i, line] of scan.entries()) {
+			const match = NATIVE_DIALOG_RE.exec(line);
+			if (!match) continue;
+			const fn = match[1] as string;
+			// A bare `confirm(`/`prompt(` in a file that imports cursedbelt's is the
+			// belt one — that is the whole point of the migration.
+			const qualified = /(?:window|globalThis|self)\s*\??\.\s*$/.test(
+				line.slice(0, match.index + match[0].length - fn.length - 1),
+			);
+			if (!qualified && importsBeltDialog(source, fn)) continue;
+			const raw = raws[i] ?? "";
+			if (NATIVE_DIALOG_IGNORE_RE.test(raw)) continue;
+			if (NATIVE_DIALOG_IGNORE_RE.test(blockAbove(raws, i + 1))) continue;
+			out.push({ file: filePath, line: i + 1, snippet: raw.trim().slice(0, 160) });
+		}
+		return out;
+	},
+};
+
+// ── no-fast-tooltip ────────────────────────────────────────────────────────────
+// The owner, 2026-09-08:
+//
+//   *"tooltips on apps like roms are showing up way too fast for items like the pause
+//   unpause button. Make them delay at least 500ms via cb and any apps that are
+//   adjusting them to be faster when they shouldn't be faster … Generally users get
+//   used to what the buttons do and never try to use the tooltip again so I want it to
+//   be hard to accidentally have them popup and block part of the screen."*
+//
+// The WHY is `cursedbelt/src/react/lib/hoverIntent.ts`; this is the WHETHER. It exists
+// because "how fast does the hint appear" is a number, and a number is the single
+// easiest thing in a codebase to re-tune locally: the belt's own default had already
+// drifted to three different answers (Tooltip 120, HoverCard 300, InfoHint none at all)
+// with nothing anywhere reporting it, and the only symptom was the owner noticing on one
+// app, months later, that bubbles kept landing on top of what he was aiming at.
+//
+// Two shapes are flagged:
+//   1. A hover-open delay written as a numeric LITERAL below the floor — `delayDuration={120}`,
+//      `openDelay={300}`, `delay: { open: 0 }`, `tooltipDelay: 200`. Passing the exported
+//      constant (`HOVER_HINT_DELAY_MS`, or `HOVER_HINT_INSTANT_MS` for a tap-to-open
+//      disclosure, which is a deliberate REQUEST rather than an accident) is the intended
+//      spelling and is never matched — which is what the constants are exported for.
+//   2. A direct `@radix-ui/react-tooltip` / `@radix-ui/react-hover-card` import outside
+//      cursedbelt's own two implementation files. That is the other half of the same
+//      drift and the half a delay-value scan cannot see: an app that builds its own
+//      Radix tooltip does not have a delay to lower, it simply inherits Radix's and is
+//      no longer reachable from the belt at all. `no-local-reimplementation` does not
+//      catch it, because that rule fires on a declared NAME and this needs none.
+//
+// Both take the standard per-line opt-out for a genuine exception — the owner's
+// "unless one has a special reason to show faster":
+//
+//   // guardrails-ignore no-fast-tooltip: <why this one must appear sooner>
+const HOVER_DELAY_FLOOR_MS = 500;
+/** `delayDuration={120}` / `openDelay = 300` / `delay: { open: 0 }` / `tooltipDelay: 200`.
+ *  Only a NUMERIC literal — an identifier is the constant and is the point. */
+const HOVER_DELAY_RE =
+	/\b(delayDuration|openDelay|hoverDelay|tooltipDelay|hintDelay)\b\s*(?:=\s*\{|[=:])\s*(\d+)/g;
+/** The `open:` member of a floating-ui `delay: { open, close }` pair. */
+const HOVER_DELAY_OPEN_RE = /\bdelay\s*:\s*\{[^}]*?\bopen\s*:\s*(\d+)/g;
+const RAW_HOVER_IMPORT_RE = /from\s*['"]@radix-ui\/react-(tooltip|hover-card)['"]/g;
+const FAST_TOOLTIP_IGNORE_RE = /guardrails-ignore\s+no-fast-tooltip\s*:/;
+/** cursedbelt's own Radix wrappers — they ARE the seam, so they necessarily import it.
+ *  Matched on the path tail so the rule behaves identically from either repo's root. */
+const HOVER_IMPL_FILES =
+	/(^|\/)src\/react\/components\/(TooltipImpl|HoverCard|InfoHint)\.tsx$/;
+
+const noFastTooltip: Rule = {
+	name: "no-fast-tooltip",
+	description: `DESIGN.md §4 / hoverIntent.ts: a hover-only hint must rest ${HOVER_DELAY_FLOOR_MS}ms before it opens — import cursedbelt's HOVER_HINT_DELAY_MS instead of writing a literal, and build hover hints from cursedbelt's Tooltip/HoverCard rather than importing Radix directly. A tap-to-open disclosure is the documented exception (HOVER_HINT_INSTANT_MS).`,
+	check(filePath, source) {
+		const unix = filePath.replace(/\\/g, "/");
+		// A spec's fixtures necessarily write the bad number in order to assert on it —
+		// the same carve-out `no-raw-data-table` and `no-native-dialog` make.
+		if (/\.(spec|test)\.[tj]sx?$/.test(unix)) return [];
+		const isBeltImpl = HOVER_IMPL_FILES.test(unix);
+		const lines = source.split("\n");
+		// Comments AND string bodies blanked, for the numeric scan: a delay quoted in
+		// prose above the code is not a delay.
+		const scannable = blankNonMarkupText(source);
+		// Comments only, for the import scan — a module specifier IS a string literal, so
+		// blanking strings would blank the very thing being looked for.
+		const codeOnly = blankComments(source);
+		const out: Violation[] = [];
+
+		const flag = (index: number) => {
+			const line = lineOf(source, index);
+			const raw = lines[line - 1] ?? "";
+			if (FAST_TOOLTIP_IGNORE_RE.test(raw)) return;
+			const windowStart = Math.max(0, line - 3);
+			if (FAST_TOOLTIP_IGNORE_RE.test(lines.slice(windowStart, line).join("\n"))) return;
+			out.push({ file: filePath, line, snippet: raw.trim().slice(0, 160) });
+		};
+
+		for (const re of [HOVER_DELAY_RE, HOVER_DELAY_OPEN_RE]) {
+			re.lastIndex = 0;
+			for (const match of scannable.matchAll(re)) {
+				const ms = Number(match[match.length - 1]);
+				if (!Number.isFinite(ms) || ms >= HOVER_DELAY_FLOOR_MS) continue;
+				flag(match.index ?? 0);
+			}
+		}
+
+		if (!isBeltImpl) {
+			RAW_HOVER_IMPORT_RE.lastIndex = 0;
+			for (const match of codeOnly.matchAll(RAW_HOVER_IMPORT_RE)) flag(match.index ?? 0);
+		}
+		return out;
+	},
+};
+
+export const RULES: Record<string, Rule> = {
+	[noRawActionButton.name]: noRawActionButton,
+	[noRawOverflow.name]: noRawOverflow,
+	[noRawInputs.name]: noRawInputs,
+	[noHardcodedColors.name]: noHardcodedColors,
+	[noRawModalFooter.name]: noRawModalFooter,
+	[noUnguardedEditingModal.name]: noUnguardedEditingModal,
+	[controlHeightTokens.name]: controlHeightTokens,
+	[noRawZindex.name]: noRawZindex,
+	[noRawDataTable.name]: noRawDataTable,
+	[noTailwindPalette.name]: noTailwindPalette,
+	[noRawTitleAttr.name]: noRawTitleAttr,
+	[noLocalReimplementation.name]: noLocalReimplementation,
+	[microTypographyFloor.name]: microTypographyFloor,
+	[choiceNeedsEmptyState.name]: choiceNeedsEmptyState,
+	[noSelectAsActionMenu.name]: noSelectAsActionMenu,
+	[noNativeDialog.name]: noNativeDialog,
+	[noFastTooltip.name]: noFastTooltip,
+};
+
+// ── File-scoped allowances ──────────────────────────────────────────────────────
+// `guardrails-file-allow <rule>[,<rule>...]: <category> — <reason>` — a deliberate,
+// reviewable, header-only, category-tagged exemption for the rare file whose whole
+// premise defeats a rule (a canvas/WebGL art surface, or a design-system-agnostic
+// embeddable primitive). See the header block for the full rationale + abuse controls.
+const FILE_ALLOW_MAX_LINE = 40; // must appear in the header to be honored
+const FILE_ALLOW_MIN_REASON = 12; // a token reason isn't good enough
+export const ALLOWED_FILE_CATEGORIES = new Set(["canvas-art", "embeddable-primitive"]);
+const FILE_ALLOW_RE = /guardrails-file-allow\s+([a-z0-9,\s-]+?)\s*:\s*([a-z][a-z-]*)\b([^\n]*)/gi;
+
+export interface FileAllow {
+	rules: Set<string>;
+	category: string;
+	reason: string;
+	line: number;
+}
+
+/** Parse honored file-level allowances from a source file's header, plus warnings for any
+ *  malformed/unrecognized directive (which is NOT honored — its violations still fire). */
+export function parseFileAllows(source: string): { allows: FileAllow[]; warnings: string[] } {
+	const allows: FileAllow[] = [];
+	const warnings: string[] = [];
+	// Neutralize `//` line-comment markers (→ same-length spaces so indices/line numbers stay
+	// valid) so a directive that wraps across several comment lines still matches: the regex's
+	// `\s*` can then bridge the newline between the rule list, the `:`, and the category.
+	const head = source
+		.split("\n")
+		.slice(0, FILE_ALLOW_MAX_LINE)
+		.join("\n")
+		.replace(/\/\//g, "  ");
+	FILE_ALLOW_RE.lastIndex = 0;
+	for (const m of head.matchAll(FILE_ALLOW_RE)) {
+		const line = lineOf(source, m.index ?? 0);
+		const rules = new Set(
+			m[1]
+				.split(",")
+				.map((s) => s.trim())
+				.filter(Boolean),
+		);
+		const category = m[2].toLowerCase();
+		const reason = (m[3] ?? "").replace(/^[\s—–-]+/, "").trim();
+		const unknownRules = [...rules].filter((r) => !(r in RULES));
+		if (!ALLOWED_FILE_CATEGORIES.has(category)) {
+			warnings.push(
+				`line ${line}: unrecognized category "${category}" — must be one of ${[...ALLOWED_FILE_CATEGORIES].join(", ")}; allowance ignored`,
+			);
+			continue;
+		}
+		if (rules.size === 0 || unknownRules.length > 0) {
+			warnings.push(
+				`line ${line}: names unknown rule(s) [${unknownRules.join(", ")}] — must be from ${Object.keys(RULES).join(", ")}; allowance ignored`,
+			);
+			continue;
+		}
+		if (reason.length < FILE_ALLOW_MIN_REASON) {
+			warnings.push(`line ${line}: reason too short — explain why this file qualifies; allowance ignored`);
+			continue;
+		}
+		allows.push({ rules, category, reason, line });
+	}
+	return { allows, warnings };
+}
+
+export type { Rule, Violation };
+
+// ── Ratchet baseline ────────────────────────────────────────────────────────────
+// `guardrails-baseline.json` holds a checked-in violation-count ceiling per
+// `<scope>` (the calling package, passed via `--scope <name>`) and rule. A run
+// FAILS only when a rule's CURRENT count exceeds its baseline — this is what lets
+// all four rules be blocking immediately without demanding a full pre-existing-
+// violation cleanup in one pass: a scope that's already at 0 stays zero-tolerance,
+// while a scope with known pre-existing violations can ratchet down over time.
+// When the current count drops below the baseline, the run still passes AND prints
+// a suggested lower baseline (never auto-written — a human commits the tightened
+// number deliberately). No `--scope` (e.g. an ad-hoc manual invocation) defaults
+// every rule's baseline to 0.
+const BASELINE_PATH = join(import.meta.dir, "guardrails-baseline.json");
+
+type Baseline = Record<string, Record<string, number>>;
+
+function loadBaseline(): Baseline {
+	if (!existsSync(BASELINE_PATH)) return {};
+	try {
+		return JSON.parse(readFileSync(BASELINE_PATH, "utf8"));
+	} catch {
+		console.error(`⚠ ${BASELINE_PATH}: invalid JSON — treating as empty (every rule defaults to a 0 baseline)`);
+		return {};
+	}
+}
+
+function main() {
+	const [ruleArg, ...rest] = process.argv.slice(2);
+	const ruleNames = ruleArg ? ruleArg.split(",") : [];
+	const rules = ruleNames.map((n) => RULES[n]).filter((r): r is Rule => Boolean(r));
+	if (ruleNames.length === 0 || rules.length !== ruleNames.length) {
+		console.error(
+			`Usage: bun run guardrailsEnforce.ts <rule>[,<rule>...] [--scope <name>] [--reimplements <Name,…>] [root...]\nKnown rules: ${Object.keys(RULES).join(", ")}`,
+		);
+		process.exit(2);
+	}
+
+	let scope: string | undefined;
+	const roots: string[] = [];
+	for (let i = 0; i < rest.length; i++) {
+		if (rest[i] === "--scope") {
+			scope = rest[i + 1];
+			i++;
+			continue;
+		}
+		// The inventoried component names `no-local-reimplementation` looks for. Passed
+		// in rather than hardcoded so the list lives beside the inventory it comes from
+		// (fleet/standards/CURSEDBELT_INVENTORY.md) — see that rule's header.
+		if (rest[i] === "--reimplements") {
+			setReimplementedNames((rest[i + 1] ?? "").split(",").map((n) => n.trim()).filter(Boolean));
+			i++;
+			continue;
+		}
+		roots.push(rest[i]);
+	}
+	const baseline = loadBaseline();
+	const scopeBaseline = (scope && baseline[scope]) || {};
+
+	const searchRoots = roots.length > 0 ? roots : ["."];
+	const files: string[] = [];
+	for (const root of searchRoots) {
+		try {
+			if (statSync(root).isDirectory()) walk(root, files);
+			else files.push(root);
+		} catch {
+			// missing root — skip (keeps the rule usable across packages that don't have
+			// every directory, e.g. a plugin package with no `apps/` dir)
+		}
+	}
+
+	const sourcesByFile = new Map<string, string>();
+	for (const file of files) sourcesByFile.set(file, readFileSync(file, "utf8"));
+
+	// Parse file-scoped allowances once per file; surface malformed directives loudly.
+	const allowsByFile = new Map<string, FileAllow[]>();
+	const honoredAllows: { file: string; allow: FileAllow }[] = [];
+	for (const [file, source] of sourcesByFile) {
+		const { allows, warnings } = parseFileAllows(source);
+		if (allows.length > 0) allowsByFile.set(file, allows);
+		for (const w of warnings) {
+			console.error(`⚠ ${relative(process.cwd(), file)}: guardrails-file-allow ${w}`);
+		}
+	}
+
+	let anyExceededBaseline = false;
+	const lowerableBaselines: Record<string, number> = {};
+	for (const rule of rules) {
+		const violations: Violation[] = [];
+		for (const [file, source] of sourcesByFile) {
+			// Honor a file-scoped allowance for this rule (auditably — recorded + printed below).
+			const allow = allowsByFile.get(file)?.find((a) => a.rules.has(rule.name));
+			if (allow) {
+				honoredAllows.push({ file, allow });
+				continue;
+			}
+			violations.push(...rule.check(file, source));
+		}
+
+		const allowedByBaseline = scopeBaseline[rule.name] ?? 0;
+		if (violations.length <= allowedByBaseline) {
+			console.log(
+				`✓ ${rule.name}: ${violations.length} violation(s) across ${files.length} files (baseline allows ${allowedByBaseline})`,
+			);
+			if (violations.length < allowedByBaseline) {
+				lowerableBaselines[rule.name] = violations.length;
+			}
+			continue;
+		}
+
+		anyExceededBaseline = true;
+		console.error(
+			`✗ ${rule.name}: ${violations.length} violation(s) — exceeds baseline of ${allowedByBaseline}\n${rule.description}\n`,
+		);
+		for (const v of violations) {
+			console.error(`  ${relative(process.cwd(), v.file)}:${v.line}  ${v.snippet}`);
+		}
+		console.error(
+			`\nFix the violation, or opt out with a "guardrails-ignore ${rule.name}: <reason>" comment\n` +
+				`(see the header of guardrailsEnforce.ts for the exact convention).\n`,
+		);
+	}
+
+	if (Object.keys(lowerableBaselines).length > 0 && scope) {
+		console.log(`\nℹ baseline could be lowered for scope "${scope}" in ${relative(process.cwd(), BASELINE_PATH)}:`);
+		for (const [name, count] of Object.entries(lowerableBaselines)) {
+			console.log(`  "${name}": ${scopeBaseline[name] ?? 0} → ${count}`);
+		}
+	}
+
+	// Audit trail: every honored file-scoped allowance is printed once (deduped across the
+	// rules it covers), so these stay few and visible in review rather than silently
+	// suppressing whole files.
+	const uniqueAllows = new Map<string, { file: string; allow: FileAllow }>();
+	for (const entry of honoredAllows) {
+		uniqueAllows.set(`${entry.file}:${entry.allow.line}`, entry);
+	}
+	if (uniqueAllows.size > 0) {
+		console.log(
+			`\nℹ ${uniqueAllows.size} file-scoped allowance(s) honored (guardrails-file-allow):`,
+		);
+		for (const { file, allow } of uniqueAllows.values()) {
+			console.log(
+				`  ${relative(process.cwd(), file)}:${allow.line}  [${[...allow.rules].join(",")}] ${allow.category} — ${allow.reason}`,
+			);
+		}
+	}
+
+	process.exit(anyExceededBaseline ? 1 : 0);
+}
+
+if (import.meta.main) main();