cursedbelt 4.3.0 → 4.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt",
-	"version": "4.3.0",
+	"version": "4.4.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The React design system of the cursedbelt split — components, styles, theme. cursedbelt-core below it; server tier in cursedbelt-server.",
@@ -31,10 +31,10 @@
 		"styles": "bun run styles:static && bun run styles:utilities && bun run styles:areas",
 		"styles:static": "bun run scripts/generateStaticStyles.ts",
 		"styles:utilities": "bun run scripts/generateUtilityStyles.ts",
-		"test": "NODE_ENV=development bun test src --timeout 60000 --parallel=6",
+		"test": "NODE_ENV=development bun test src scripts --timeout 60000 --parallel=6",
 		"demo": "vite --config demo/vite.config.ts",
 		"demo:build": "vite build --config demo/vite.config.ts",
-		"demo:serve": "bun run demo:build && vite preview --config demo/vite.config.ts",
+		"demo:serve": "bun run demo:build && bun run scripts/demoServer.ts",
 		"build": "rm -rf dist.next dist.prev && bun run scripts/generateStaticStyles.ts && bun run scripts/generateUtilityStyles.ts && bun run scripts/generateAreaStyles.ts && tsc --project tsconfig.build.json --outDir dist.next && tsc --project tsconfig.scripts.build.json --outDir dist.next/scripts && CURSEDBELT_DIST_DIR=dist.next bun run scripts/copyDistAssets.ts && CURSEDBELT_DIST_DIR=dist.next bun run scripts/checkDistExports.ts &&{ [ -d dist ] && mv dist dist.prev || true; } && mv dist.next dist && rm -rf dist.prev",
 		"e2e": "playwright test --config e2e/playwright.config.ts",
 		"e2e:filter-rail": "playwright test --config e2e/playwright.config.ts filter-rail.spec.ts",
@@ -47,9 +47,10 @@
 		"e2e:touch": "playwright test --config e2e/playwright.config.ts --project=touch",
 		"done:serial": "bun run typecheck && bun run lint && bun run test && bun run build",
 		"paths": "bun run scripts/paths.ts",
-		"verify": "bun run scripts/verify.ts",
-		"prepublishOnly": "bun run verify",
-		"styles:areas": "bun run scripts/generateAreaStyles.ts"
+		"verify": "bun run gate",
+		"prepublishOnly": "bun run gate --force",
+		"styles:areas": "bun run scripts/generateAreaStyles.ts",
+		"gate": "bun run scripts/gate.ts"
 	},
 	"exports": {
 		".": {
@@ -687,5 +688,48 @@
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/curtwphillips/cursedbelt.git"
+	},
+	"gate": {
+		"stages": [
+			{
+				"script": "paths"
+			},
+			{
+				"script": "typecheck:root"
+			},
+			{
+				"script": "typecheck:specs"
+			},
+			{
+				"script": "typecheck:scripts"
+			},
+			{
+				"script": "demo:check"
+			},
+			{
+				"script": "styles"
+			},
+			{
+				"script": "build",
+				"needs": [
+					"styles"
+				],
+				"why": "its first two steps are the same generators; two writers on one stylesheet is a race"
+			},
+			{
+				"script": "test",
+				"needs": [
+					"styles"
+				],
+				"why": "stylesStaticMatches / stylesUtilitiesMatches read those two files and assert they are current"
+			},
+			{
+				"script": "e2e",
+				"needs": [
+					"styles"
+				],
+				"why": "the demo bundle it drives is compiled from the same stylesheets"
+			}
+		]
 	}
 }

package/scripts/demoServer.ts

@@ -0,0 +1,211 @@
+#!/usr/bin/env bun
+/**
+ * The static server `bun run e2e` drives — the built demo, served by code this repo owns.
+ *
+ * ## Why this exists instead of `vite preview`
+ *
+ * Measured 2026-09-18 (task 388): `bun run verify` went red about one run in four on an
+ * unmodified tree, always the same way — `e2e` failing at exactly `webServer.timeout`
+ * (120.1s) with all 138 specs marked failed, and the real cause 150 lines below the noise:
+ *
+ *     [WebServer] error: write after end
+ *     [WebServer]  code: "ERR_STREAM_WRITE_AFTER_END"
+ *     [WebServer]       at advanceResponsePipeline (node:_http_server:1343:38)
+ *     [WebServer] error: script "demo:serve" exited with code 1
+ *
+ * That throw comes out of Bun 1.4.2's `node:http` compatibility layer, *after* the connect
+ * handler `vite preview` installed has returned — so no middleware, and no `server.on`
+ * listener on the connect app, is positioned to catch it. It fires when the peer closes a
+ * socket the response is still being written to, which is the normal state of affairs with
+ * eight Playwright workers: every navigation supersedes its own in-flight subresource
+ * requests, and `page.goto` during teardown abandons whatever was in flight.
+ *
+ * `Bun.serve` is a different layer. A handler returns a `Response`; a peer that hangs up
+ * cancels the body stream, and there is no socket write for user code to get wrong. The
+ * `error` hook below is the only place a fault can surface, and it answers with a 500
+ * instead of exiting.
+ *
+ * 🔴 This is deliberately the dumbest static server that can serve the fixture, because
+ * every feature it does not have is a way it cannot die halfway through a gate. No
+ * compression, no range requests, no directory listing, no watch mode, no HMR. `bun run
+ * demo` is still vite's dev server — a human editing a primitive wants the HMR, and that
+ * process has one tab attached to it rather than eight aborting workers.
+ */
+import { statSync } from 'node:fs';
+import { extname, resolve, sep } from 'node:path';
+import { DEMO_DIST_DIR, DEMO_HOST, DEMO_PORT, DEMO_URL } from '../demo/devServer';
+
+/**
+ * 🔴 Never cached, by anything. The gate's whole claim is that it tested the bytes in the
+ * tree; a 304 from a browser profile that outlived the build would quietly break that, and
+ * it would break it in the direction that reads green.
+ */
+const NO_STORE = { 'cache-control': 'no-store, max-age=0' } as const;
+
+/**
+ * The request path a URL resolves to inside `root`, or `null` for anything that is not a
+ * file under it.
+ *
+ * Pure and exported so the traversal refusal is provable without a socket.
+ */
+export function resolveRequestPath(root: string, pathname: string): string | null {
+	let decoded: string;
+	try {
+		decoded = decodeURIComponent(pathname);
+	} catch {
+		// A malformed `%` escape. Not a path, and not worth guessing at.
+		return null;
+	}
+	if (decoded.includes('\0')) return null;
+	const wanted = decoded === '' || decoded === '/' ? '/index.html' : decoded;
+	// `resolve` collapses `..` itself; the prefix check below is what makes that a
+	// guarantee rather than a belief about how many segments the caller sent.
+	const candidates = [resolve(root, `.${wanted}`)];
+	// The fixture pages are a multi-page BUILD, so `/table-layout` and `/table-layout.html`
+	// are the same page. vite preview resolved both; specs use the explicit form, and a
+	// silent 404 on the bare one would be a difference nobody would notice until it bit.
+	if (extname(wanted) === '') candidates.push(resolve(root, `.${wanted}.html`));
+
+	const fence = root.endsWith(sep) ? root : root + sep;
+	for (const candidate of candidates) {
+		if (candidate !== root && !candidate.startsWith(fence)) continue;
+		try {
+			if (statSync(candidate).isFile()) return candidate;
+		} catch {
+			// Missing, or a directory we will not list. Try the next shape.
+		}
+	}
+	return null;
+}
+
+/**
+ * Faults that are the PEER's doing, not ours: a client that went away mid-response.
+ *
+ * 🔴 The allow-list is closed on purpose. A blanket `uncaughtException` handler on a test
+ * fixture is how a server keeps serving after it has lost the thing it was serving, and
+ * the gate then measures a corpse that answers 200. Anything not named here still kills
+ * the process, loudly, which is the behaviour every other fault should have.
+ */
+const PEER_HANGUP_CODES: ReadonlySet<string> = new Set([
+	'ECONNRESET',
+	'ECONNABORTED',
+	'EPIPE',
+	'ERR_STREAM_WRITE_AFTER_END',
+	'ERR_STREAM_DESTROYED',
+	'ERR_STREAM_PREMATURE_CLOSE',
+	'ABORT_ERR',
+]);
+
+/** Whether a thrown value is a peer hang-up rather than a fault in this server. */
+export function isPeerHangup(thrown: unknown): boolean {
+	if (typeof thrown !== 'object' || thrown === null) return false;
+	const code = (thrown as { code?: unknown }).code;
+	if (typeof code === 'string' && PEER_HANGUP_CODES.has(code)) return true;
+	const name = (thrown as { name?: unknown }).name;
+	return name === 'AbortError';
+}
+
+export interface DemoServerOptions {
+	/** The directory to serve. Defaults to the built demo. */
+	root?: string;
+	/** Defaults to `DEMO_PORT`; `0` takes an ephemeral one, which is what the spec uses. */
+	port?: number;
+	hostname?: string;
+}
+
+export function startDemoServer(options: DemoServerOptions = {}): Bun.Server<undefined> {
+	const root = options.root ?? DEMO_DIST_DIR;
+	return Bun.serve({
+		port: options.port ?? DEMO_PORT,
+		// 🔴 One literal address, never the name — `demo/devServer.ts` has the measurement.
+		// Binding `localhost` let two processes hold 4318 at once, on `::1` and `127.0.0.1`,
+		// with no collision between them.
+		hostname: options.hostname ?? DEMO_HOST,
+		// 🔴 EXPLICIT, and the single least obvious line in this file. Bun.serve defaults to
+		// SO_REUSEPORT: measured 2026-09-18 on Bun 1.4.2, a second process binding a port
+		// another one already holds SUCCEEDS, prints a ready line, and serves nothing —
+		// every request is still answered by the first. That is `strictPort: false` with the
+		// failure hidden one layer deeper, and it would have made this whole change worse
+		// than what it replaced: the gate would build the demo, "serve" it, and then test
+		// whatever stale bundle a stray `bun run demo` was holding. With this, the bind
+		// throws EADDRINUSE and `main()` says so in one line.
+		reusePort: false,
+		development: false,
+		// Long enough for the heaviest chunk on a loaded machine; short enough that a
+		// wedged connection cannot hold a gate open. Bun's default is 10s.
+		idleTimeout: 60,
+		fetch(request) {
+			const file = resolveRequestPath(root, new URL(request.url).pathname);
+			if (!file) return new Response('not found\n', { status: 404, headers: NO_STORE });
+			return new Response(Bun.file(file), { headers: NO_STORE });
+		},
+		error(thrown) {
+			// The one seam a fault can reach. Returning a Response keeps the process alive;
+			// this is the hook `vite preview` had no equivalent of.
+			if (!isPeerHangup(thrown)) {
+				process.stderr.write(`demo server: request failed — ${thrown instanceof Error ? thrown.stack : String(thrown)}\n`);
+			}
+			return new Response('demo server error\n', { status: 500, headers: NO_STORE });
+		},
+	});
+}
+
+/**
+ * 🔴 Both halves matter. Exiting non-zero the moment the bundle or the port is wrong is
+ * what turns "Playwright waited 120s and then failed 138 specs" into one line a reader
+ * believes — and `$FORGE/tools/gate.ts` lifts these exact words to the top of a red gate.
+ */
+async function main(): Promise<void> {
+	try {
+		if (!statSync(DEMO_DIST_DIR).isDirectory()) throw new Error('not a directory');
+	} catch {
+		process.stderr.write(
+			`demo server: no built demo at ${DEMO_DIST_DIR} — run \`bun run demo:build\` first.\n` +
+				'`bun run demo:serve` does both, and that is what the e2e webServer runs.\n',
+		);
+		process.exit(1);
+	}
+
+	let server: Bun.Server<undefined>;
+	try {
+		server = startDemoServer();
+	} catch (thrown) {
+		const code = (thrown as { code?: string } | null)?.code;
+		if (code === 'EADDRINUSE') {
+			process.stderr.write(
+				`demo server: EADDRINUSE — port ${DEMO_PORT} is already taken, so the gate cannot serve ` +
+					'the demo it just built.\nSomething else is listening (a stray `bun run demo`, or a ' +
+					'previous run that outlived its Playwright). Stop it and run the gate again.\n',
+			);
+			process.exit(1);
+		}
+		throw thrown;
+	}
+
+	// 🔴 Ask ourselves, over the socket, on the URL the specs are pointed at — before
+	// Playwright starts a 120-second wait it cannot explain. This catches the shapes a
+	// successful `bind` does not: a `localhost` that resolved to an address the client will
+	// not use, and a `dist` that built but emitted no `index.html`.
+	try {
+		const probe = await fetch(DEMO_URL, { signal: AbortSignal.timeout(5_000) });
+		if (!probe.ok) throw new Error(`${DEMO_URL} answered ${probe.status}`);
+	} catch (thrown) {
+		process.stderr.write(
+			`demo server: bound ${DEMO_PORT}, but ${DEMO_URL} does not answer — ` +
+				`${thrown instanceof Error ? thrown.message : String(thrown)}\n` +
+				`Nothing can drive this. Check that \`bun run demo:build\` wrote ${DEMO_DIST_DIR}/index.html.\n`,
+		);
+		await server.stop(true);
+		process.exit(1);
+	}
+
+	for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+		process.on(signal, () => {
+			void server.stop(true);
+			process.exit(0);
+		});
+	}
+	process.stdout.write(`demo server: serving ${DEMO_DIST_DIR} at ${DEMO_URL}\n`);
+}
+
+if (import.meta.main) await main();

package/scripts/gate.ts

@@ -0,0 +1,101 @@
+/**
+ * `bun run gate` — this repo's gate, run by the generation's shared runner.
+ *
+ * ## Where the argument went
+ *
+ * This repo's gate stopped being an `&&` chain on 2026-09-15 and became a dependency graph, and
+ * `src/verifyGraph.spec.ts` is the file that holds it to that — the stage set it may never
+ * shrink below, the two edges, and why `build` is a leaf. On 2026-09-20 the SCHEDULER moved to
+ * `$FORGE/tools/gate.ts` so the other twenty repos could have it too, and the stages moved to the
+ * `gate` block in `package.json`, which keeps `package.json` the one place every command is
+ * spelled. Read those two; this file only locates the tool.
+ *
+ * What the move buys this repo specifically is the SECOND run, not the first. One gate here is
+ * 33–65 s and has been since 2026-09-18 (the graph did that; `autopilot timings`' all-time median
+ * of 6.5 m is dominated by runs from before it, and is the wrong number to plan against). What
+ * this repo spends is 14.72 h — 58 % of every gate second this generation has ever spent, over 84
+ * runs across 41 agents — because the ledger says the median agent runs the gate TWICE and the
+ * supervisor runs it again after, on the same tree. A stamped run is 0.1 s. See
+ * `$FORGE/tools/gate.ts` for why the stamp is keyed on content and not on a clock.
+ *
+ * ## 🔴 Why this is a wrapper and not `bun ../../tools/gate.ts .`
+ *
+ * That spelling assumes this checkout sits at a fixed depth under the generation root, and a
+ * WORKTREE never does. It is the same argument, verbatim, as `scripts/paths.ts` — which is where
+ * it is written down, along with what it cost on 2026-09-17 — and the same two walks: up for
+ * `forge.env`, then via the primary checkout a worktree's `.git` file points at.
+ *
+ * 🔴 **No generation, no pass.** A gate that could not be located has not passed.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The one tool: the shared runner. The stages it runs are the `gate` block in `package.json`. */
+const TOOLS = ["gate.ts"];
+
+/** How far up either walk looks before giving up — a bound, so a misuse is `null` in ms. */
+const MAX_HOPS = 16;
+
+/** Walk up from `from` for a directory containing `marker`, or `null`. */
+function walkUp(from: string, marker: string): string | null {
+	let dir = resolve(from);
+	for (let hops = 0; hops < MAX_HOPS; hops++) {
+		if (existsSync(join(dir, marker))) return dir;
+		const up = dirname(dir);
+		if (up === dir) return null;
+		dir = up;
+	}
+	return null;
+}
+
+/** The directory holding `forge.env` above `from`, or `null` when that is not inside a generation. */
+function findForgeRoot(from: string): string | null {
+	return walkUp(from, "forge.env");
+}
+
+/** The generation above the checkout this WORKTREE was cut from, or `null` on anything unexpected. */
+function viaWorktree(from: string): string | null {
+	try {
+		const git = spawnSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
+			cwd: from,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (git.status !== 0) return null;
+		const gitDir = (git.stdout ?? "").trim();
+		if (!gitDir || !gitDir.startsWith("/")) return null;
+		// `<primary>/.git` → `<primary>`, then the ordinary walk up.
+		return findForgeRoot(dirname(gitDir));
+	} catch {
+		return null;
+	}
+}
+
+const here = dirname(fileURLToPath(import.meta.url));
+/** This checkout — the nearest ancestor holding a `package.json`, so it is right in a worktree. */
+const repo = walkUp(here, "package.json");
+const root = findForgeRoot(here) ?? viaWorktree(here);
+
+if (!repo) {
+	console.error(`✗ no package.json above ${here}, so there is no repo to check.`);
+	process.exit(1);
+}
+if (!root) {
+	console.error("✗ this checkout is not inside a generation and is not a worktree of one, so");
+	console.error(`  tools/{${TOOLS.join(",")}} cannot be located. Run it from a checkout under a`);
+	console.error("  generation, or from a worktree cut from one — a skipped check is not a passed one.");
+	process.exit(1);
+}
+
+for (const name of TOOLS) {
+	const tool = join(root, "tools", name);
+	if (!existsSync(tool)) {
+		console.error(`✗ ${tool} does not exist. The generation at ${root} has no ${name},`);
+		console.error("  so this repo cannot prove it obeys that law. That is a failure, not a skip.");
+		process.exit(1);
+	}
+	const result = spawnSync("bun", [tool, repo, ...process.argv.slice(2)], { stdio: "inherit" });
+	if ((result.status ?? 1) !== 0) process.exit(result.status ?? 1);
+}

package/scripts/guardrailsEnforce.spec.ts

@@ -1,3 +1,8 @@
+// 🔴 `package.json`'s `test` script globs `src scripts`, not `src` — this file is the only
+// spec outside `src`, and until 2026-09-18 nothing ran it. The gate was green while every
+// assertion in here (129 of them, the scanner's entire behavioural contract) was inert, so a
+// rule could rot and `bun run verify` would still say ok. If you narrow that glob back, the
+// tests below stop being checks and become a document.
 import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -107,6 +112,70 @@ describe('opening-tag extraction (comment-aware)', () => {
   });
 });
 
+// Filed 2026-09-18, found while proving the fix above: the first negative test came back
+// green for the WRONG reason. Making the walker comment-aware widened what it returns, and
+// the opt-out checks then read prose with regexes that look for a real ATTRIBUTE — so a
+// comment merely QUOTING `role="radio"` suppressed no-raw-action-button on a raw button
+// that had no presentational role at all. The rule could not be trusted to read zero in
+// exactly the well-documented files it should be strictest about. The input was wrong, not
+// the pattern: the comment check reads the tag as written, the attribute check reads it
+// comment-blanked.
+describe('a presentational marker must be an ATTRIBUTE, not prose about one', () => {
+  test('role="radio" only inside a comment does NOT opt the button out', () => {
+    const source = `<button
+      // A radio-like list: \`role="radio"\` + \`aria-checked\` says so to a screen reader.
+      type="button"
+      onClick={() => onPick(id)}
+    >Move here</button>`;
+    expect(check('no-raw-action-button', source)).toHaveLength(1);
+  });
+
+  test('aria-selected= only inside a block comment does NOT opt the button out', () => {
+    const source = `<button
+      /* The row is the control here; aria-selected= would be the tab-ish spelling. */
+      type="button"
+    >Move here</button>`;
+    expect(check('no-raw-action-button', source)).toHaveLength(1);
+  });
+
+  test('the guardrails-ignore comment still opts out beside that same prose', () => {
+    const source = `<button
+      // A radio-like list: \`role="radio"\` + \`aria-checked\` says so to a screen reader.
+      // guardrails-ignore no-raw-action-button: presentational row in a radio-like list
+      type="button"
+    >Move here</button>`;
+    expect(check('no-raw-action-button', source)).toHaveLength(0);
+  });
+
+  test('the REAL attributes still pass silently, prose and all', () => {
+    const source = `<button
+      // A radio-like list: \`role="radio"\` + \`aria-checked\` says so to a screen reader.
+      role="radio"
+      aria-checked={selected}
+      type="button"
+    >Move here</button>`;
+    expect(check('no-raw-action-button', source)).toHaveLength(0);
+  });
+
+  // The same shape on no-raw-title-attr, which fires the other way: there the attribute
+  // regex is what CREATES the violation, so prose mentioning `title=` invented one.
+  test('a title= written only in a comment is not a title attribute', () => {
+    const source = `<span
+      // Not a title= hover hint — the expansion is rendered beside it.
+      className="tabular"
+    >UTC</span>`;
+    expect(check('no-raw-title-attr', source)).toHaveLength(0);
+  });
+
+  test('a real title attribute below that prose is still flagged', () => {
+    const source = `<span
+      // Reads as a title= hover hint, and that is the bug.
+      title="Coordinated Universal Time"
+    >UTC</span>`;
+    expect(check('no-raw-title-attr', source)).toHaveLength(1);
+  });
+});
+
 describe('no-raw-overflow', () => {
   test('flags inline style overflow: auto', () => {
     expect(check('no-raw-overflow', '<div style={{ overflow: "auto" }} />')).toHaveLength(1);

package/scripts/guardrailsEnforce.ts

@@ -258,7 +258,24 @@ function skipQuoted(source: string, start: number): number {
 	return i;
 }
 
-/** Slice from a `<button` (or similar) match to the end of its opening tag, tolerating
+/** One opening tag, in the two forms its checks need. Both strings cover the SAME span
+ *  and have the same length, so a line number or offset taken from one is valid in the
+ *  other. */
+interface OpeningTag {
+	/** Exactly as written, comments included — what a `guardrails-ignore <rule>:` check
+	 *  must read, since the thing it is looking for IS a comment. */
+	readonly text: string;
+	/** The same span with comment bodies blanked to spaces (newlines kept, so offsets and
+	 *  line numbers hold) — what an ATTRIBUTE check must read. An attribute check run over
+	 *  `text` is fooled by prose that merely QUOTES the attribute: a comment reading
+	 *  ``role="radio" + aria-checked says so to a screen reader`` matched
+	 *  `PRESENTATIONAL_MARKER_RE` and silently opted a raw `<button>` out of
+	 *  no-raw-action-button (task 42). Narrowing such a regex only moves the goalposts —
+	 *  the input was wrong, so the input is what changed. */
+	readonly code: string;
+}
+
+/** Read from a `<button` (or similar) match to the end of its opening tag, tolerating
  *  `{...}` JS expressions in attribute values that may themselves contain `>`
  *  (`onClick={() => …}`, which works because that `>` sits inside braces).
  *
@@ -266,30 +283,40 @@ function skipQuoted(source: string, start: number): number {
  *  so it may contain an angle bracket ("a radio-like list rather than a `<select>`").
  *  Those are skipped the same way `blankComments` skips them, because a `>` written in prose
  *  used to end the tag here and make every attribute below it invisible — the
- *  `guardrails-ignore` opt-out included. `blankComments` cannot simply be run first: the
- *  opt-out checks read this slice and must see the ORIGINAL comment text (see the
- *  no-raw-action-button check below), so the skip only suppresses TERMINATION; the comment
- *  stays in what is returned. */
-function extractOpeningTag(source: string, startIndex: number): string {
+ *  `guardrails-ignore` opt-out included. The skip therefore suppresses only TERMINATION;
+ *  the comment text survives in `.text` for the opt-out checks, and is blanked in `.code`
+ *  for the attribute checks. */
+function readOpeningTag(source: string, startIndex: number): OpeningTag {
+	const blank = (span: string) => span.replaceAll(/[^\n]/g, " ");
 	let i = startIndex;
 	let braceDepth = 0;
+	let code = "";
 	while (i < source.length) {
 		const two = source.slice(i, i + 2);
 		if (two === "//") {
 			const end = source.indexOf("\n", i);
-			i = end === -1 ? source.length : end;
+			const stop = end === -1 ? source.length : end;
+			code += blank(source.slice(i, stop));
+			i = stop;
 			continue;
 		}
 		if (two === "/*") {
 			const end = source.indexOf("*/", i + 2);
-			i = end === -1 ? source.length : end + 2;
+			const stop = end === -1 ? source.length : end + 2;
+			code += blank(source.slice(i, stop));
+			i = stop;
 			continue;
 		}
 		const ch = source[i];
 		if (ch === '"' || ch === "'" || ch === "`") {
-			i = skipQuoted(source, i);
+			// A quoted attribute VALUE is real markup, not prose — `role="radio"` must
+			// survive into `.code`, which is the whole point of the attribute checks.
+			const stop = skipQuoted(source, i);
+			code += source.slice(i, stop);
+			i = stop;
 			continue;
 		}
+		code += ch;
 		if (ch === "{") braceDepth++;
 		else if (ch === "}") braceDepth--;
 		else if (ch === ">" && braceDepth <= 0) {
@@ -298,7 +325,7 @@ function extractOpeningTag(source: string, startIndex: number): string {
 		}
 		i++;
 	}
-	return source.slice(startIndex, i);
+	return { text: source.slice(startIndex, i), code };
 }
 
 function lineOf(source: string, index: number): number {
@@ -445,10 +472,13 @@ const noRawActionButton: Rule = {
 		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;
+			// Re-read the tag from the ORIGINAL source so opt-out comments (which were
+			// just blanked out of `scannable`) are still visible to the ignore check.
+			// The two halves take DIFFERENT inputs, and that is the point: the ignore
+			// check is looking for a comment, the marker check for a real attribute, so
+			// prose quoting `role="radio"` opts nothing out.
+			const tag = readOpeningTag(source, match.index);
+			if (IGNORE_COMMENT_RE.test(tag.text) || PRESENTATIONAL_MARKER_RE.test(tag.code)) continue;
 			const line = lineOf(source, match.index);
 			violations.push({
 				file: filePath,
@@ -510,9 +540,10 @@ const noRawInputs: Rule = {
 		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 tag = readOpeningTag(source, match.index);
 			const ignoreRe = /guardrails-ignore\s+no-raw-inputs\s*:/;
-			if (ignoreRe.test(tag)) continue;
+			// `.text`: this rule's only opt-out IS a comment, so it reads the comments.
+			if (ignoreRe.test(tag.text)) continue;
 			const line = lineOf(source, match.index);
 			violations.push({
 				file: filePath,
@@ -838,6 +869,12 @@ const ISDIRTY_PROP_RE = /\bisDirty\s*=/;
  * 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.
+ *
+ * 🔴 Run it over COMMENT-BLANKED source only (`blankComments`, as `check` does below),
+ * never over raw text. It is an attribute regex, so prose quoting `role="dialog"` reads
+ * to it as a declaration — the same defect that let a quoted `role="radio"` suppress
+ * no-raw-action-button (task 42, see `OpeningTag`). Here it would fire the other way, on
+ * a comment explaining why a dialog role is wrong.
  */
 const HANDROLLED_DIALOG_RE =
 	/(?<!\[)\brole\s*=\s*(?:['"]dialog['"]|\{\s*['"]dialog['"]\s*\})|<DialogContent\b/g;
@@ -1059,9 +1096,12 @@ const noRawTitleAttr: Rule = {
 			// 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 tag = readOpeningTag(source, index);
+			// Same split as no-raw-action-button, the other way up: reading comments with
+			// an ATTRIBUTE regex here flags an element that has no `title` at all because
+			// a comment in its attribute list mentions one ("not a title= hover hint").
+			if (!TITLE_ATTR_RE.test(tag.code)) continue;
+			if (TITLE_ATTR_IGNORE_RE.test(tag.text)) 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;

package/scripts/paths.ts

@@ -38,7 +38,7 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 /** The generation's tools this repo runs over its own tree, in the order they should fail. */
-const TOOLS = ["check-paths.ts", "check-doc-citations.ts"];
+const TOOLS = ["check-paths.ts", "check-doc-citations.ts", "check-gate-graph.ts"];
 
 /** How far up either walk looks before giving up — a bound, so a misuse is `null` in ms. */
 const MAX_HOPS = 16;