@adia-ai/adia-ui-forge 0.8.55 → 0.8.57

package/scripts/lint-rules.generated.mjs

@@ -0,0 +1,1700 @@
+// GENERATED — do not hand-edit. Sources:
+//   scripts/lint/engine/primitives.mjs, scripts/lint/engine/run.mjs
+//   scripts/lint/rules/consumer/genui-doc.mjs
+//   scripts/lint/rules/consumer/hardcoded-open.mjs
+//   scripts/lint/rules/consumer/llm-key-in-client.mjs
+//   scripts/lint/rules/consumer/shell-nesting.mjs
+//   scripts/lint/rules/consumer/shell-resize.mjs
+//   scripts/lint/rules/consumer/ssr.mjs
+//   scripts/lint/rules/forge/missing-scope.mjs
+//   scripts/lint/rules/generated/composition/chat-shell.mjs
+//   scripts/lint/rules/genui-output/anti-patterns.mjs
+//   scripts/lint/rules/shared/attr-typo.mjs
+//   scripts/lint/rules/shared/bool-default-true.mjs
+//   scripts/lint/rules/shared/dead-font-token.mjs
+//   scripts/lint/rules/shared/example-id-grammar.mjs
+//   scripts/lint/rules/shared/example-prop-contract.mjs
+//   scripts/lint/rules/shared/legacy-shell.mjs
+//   scripts/lint/rules/shared/native-primitive.mjs
+//   scripts/lint/rules/shared/raw-color.mjs
+//   scripts/lint/rules/shared/raw-px.mjs
+//   scripts/lint/rules/shared/scope-extent.mjs
+//   scripts/lint/rules/shared/shadow-dom.mjs
+//   scripts/lint/rules/shared/slotted.mjs
+//   scripts/lint/rules/shared/stale-dialect.mjs
+// Rebuild: node scripts/build/lint-rules.mjs
+// Freshness gate: node scripts/verify/check-lint-rules-fresh.mjs --verify
+// Self-contained (no relative imports) — copied byte-for-byte to 4 vendored
+// destinations at different directory depths (LLD-0016 §C5), one of which
+// (packages/gen-ui/engine/retrieval/anti-patterns.generated.js) is
+// browser-reachable — check:browser-safe forbids a top-level 'node:*'
+// import there. Rules that touch disk (only the .yaml-corpus ones) reach
+// node:fs/node:path via process.getBuiltinModule() inside their own
+// functions instead of a static import — zero import statements, so
+// nothing to strip or guard per-destination.
+
+/**
+ * scripts/lint/engine/primitives.mjs — the fixed matcher-primitive library
+ * every rule module (scripts/lint/rules/**\/*.mjs) is written against.
+ *
+ * LLD-0016 §C2: rules are real code, not serializable config, but every
+ * rule is built from this small, fixed set of primitives — the engine's
+ * real extensibility seam. Ported 1:1 from forge-lint's and adia-lint's
+ * shared regex bank + `_strip_comments`/`_is_foundation_css` helpers
+ * (both scripts' docstrings called that bank a deliberate vendored
+ * duplicate; this module is its single source now).
+ *
+ * Stdlib-equivalent only (node:fs / node:path, no npm deps) — LLD-0016 §C2:
+ * this is what keeps the generated rule bank safely vendorable into three
+ * plugin trees with no `npm install` at hook-execution time.
+ */
+
+const CODE_EXT = ['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'];
+const STYLE_EXT = ['.css'];
+const MARKUP_EXT = ['.html', '.htm', '.vue', '.svelte', '.astro', '.tsx', '.jsx'];
+// gh#2649 — the yaml-corpus rules (STALE-DIALECT, EXAMPLE-PROP-CONTRACT,
+// EXAMPLE-ID-GRAMMAR) are the first .yaml-fileType rules in the bank;
+// without this, `npm run lint`'s git-ls-files filter and both hooks'
+// ext gate drop every .yaml write before lintText ever sees it, making
+// those three rules permanently unreachable outside their own selftest.
+const YAML_EXT = ['.yaml'];
+const LINT_EXT = [...new Set([...CODE_EXT, ...STYLE_EXT, ...MARKUP_EXT, ...YAML_EXT])].sort();
+
+const FOUNDATION_STEMS = new Set([
+  'tokens', 'token', 'theme', 'themes', 'foundation', 'foundations',
+  'palette', 'palettes', 'host', 'reset', 'resets', 'scheme', 'schemes',
+  'color', 'colors',
+]);
+
+/** File extension, lowercased, dot included (mirrors Python's os.path.splitext). */
+function ext(path) {
+  const base = (path || '').split('/').pop() || '';
+  const i = base.lastIndexOf('.');
+  return i <= 0 ? '' : base.slice(i).toLowerCase();
+}
+
+/**
+ * A genuine token/foundation sheet — exempt from the CSS-literal + scope
+ * checks. Matched by exact stem or a styles/tokens dir, never a path
+ * substring (so a `color-picker` component is still linted).
+ */
+function isFoundationCss(path, text, optInTag) {
+  const segs = (path || '').replace(/\\/g, '/').split('/');
+  if (segs.includes('styles') || segs.includes('tokens')) return true;
+  const base = segs[segs.length - 1] || '';
+  const dot = base.lastIndexOf('.');
+  const stem = (dot <= 0 ? base : base.slice(0, dot)).toLowerCase();
+  if (FOUNDATION_STEMS.has(stem)) return true;
+  if (optInTag) {
+    const re = new RegExp(`${optInTag}:\\s*foundation`, 'i');
+    return re.test(text.slice(0, 1000));
+  }
+  return false;
+}
+
+/**
+ * Per-line comment-stripping iterator (gh#976): tracks /* *\/ block-comment
+ * state across lines; also strips `//` line comments for CODE_EXT files.
+ * Returns an array of { lineNo, raw, stripped } — `stripped` is what rules
+ * should match against so a literal quoted in prose never fires.
+ */
+function stripCommentLines(text, fileExt) {
+  const lines = text.split('\n');
+  const out = [];
+  let inBlock = false;
+  for (let idx = 0; idx < lines.length; idx += 1) {
+    const raw = lines[idx];
+    let stripped = '';
+    let j = 0;
+    const n = raw.length;
+    while (j < n) {
+      if (inBlock) {
+        const k = raw.indexOf('*/', j);
+        if (k === -1) { j = n; break; }
+        inBlock = false;
+        j = k + 2;
+        continue;
+      }
+      const k = raw.indexOf('/*', j);
+      const m = CODE_EXT.includes(fileExt) ? raw.indexOf('//', j) : -1;
+      if (m !== -1 && (k === -1 || m < k)) {
+        stripped += raw.slice(j, m);
+        j = n;
+        break;
+      }
+      if (k === -1) {
+        stripped += raw.slice(j);
+        j = n;
+        break;
+      }
+      stripped += raw.slice(j, k);
+      inBlock = true;
+      j = k + 2;
+    }
+    out.push({ lineNo: idx + 1, raw, stripped });
+  }
+  return out;
+}
+
+/** 1-based line number of a character offset into `text`. */
+function lineOf(text, offset) {
+  let n = 1;
+  for (let i = 0; i < offset && i < text.length; i += 1) if (text[i] === '\n') n += 1;
+  return n;
+}
+
+/** Suppression comment recognized on the line itself or the line before a finding. */
+const SUPPRESS_RE = /\/\*\s*adia-lint-disable\s+([A-Z0-9-]+)(?:\s*—\s*(.*?))?\s*\*\//;
+
+/** Given all raw lines and a finding's line number, is it suppressed, and was a reason given? */
+function suppressionFor(rawLines, lineNo, ruleId) {
+  const candidates = [rawLines[lineNo - 1], rawLines[lineNo - 2]].filter(Boolean);
+  for (const line of candidates) {
+    const m = SUPPRESS_RE.exec(line || '');
+    if (m && m[1] === ruleId) return { suppressed: true, hasReason: Boolean(m[2] && m[2].trim()) };
+  }
+  return { suppressed: false, hasReason: false };
+}
+
+/**
+ * Every suppression comment in the file, bare-reason ones flagged — used by
+ * the engine to both apply suppression and emit SUPPRESS-NO-REASON findings
+ * for a disable with no `<reason>` (LLD-0016 §Interfaces: "a bare `-disable`
+ * with no `<reason>` is itself a lint finding").
+ */
+function allSuppressions(rawLines) {
+  const out = [];
+  const re = new RegExp(SUPPRESS_RE.source, 'g');
+  rawLines.forEach((line, idx) => {
+    let m;
+    re.lastIndex = 0;
+    while ((m = re.exec(line))) {
+      out.push({ lineNo: idx + 1, ruleId: m[1], hasReason: Boolean(m[2] && m[2].trim()) });
+    }
+  });
+  return out;
+}
+
+const RE = {
+  HEXCOLOR: /#[0-9a-fA-F]{3,8}\b/,
+  FUNCCOLOR: /\b(?:rgba?|hsla?|oklch|oklab|lab|lch)\s*\(/,
+  DEAD_FONT: /var\(\s*--a-font\s*[,)]/,
+  SCOPE_EXTENT: /:scope(?:\[[^\]]*\])?\s*\{[^{}]*?\b(?:width|height|inline-size|block-size)\s*:/s,
+  BOOL_TRUE: /\bdefault:\s*true\b/,
+  ATTR_TYPO: /\battr:\s*['"]/,
+  NATIVE_PRIMITIVE: /<(?:button|input|select|textarea|dialog)(?![\w-])/,
+  LEGACY_SHELL: /data-chat-(?:messages|input|empty|name)|data-editor-body|data-canvas\b|data-sidebar=|data-pane-(?:side|grow)|<aside-ui\b|<dialog\s+data-command/,
+  PX_GE: /(?<![\w.-])(\d+)px\b/g,
+  SELECTOR_RULE: /^\s*[.#:[&\w][^{}\n]*\{/m,
+  SSR_SIGNAL: /['"]use client['"]|\buseEffect\b|\bonMounted\b|\bonMount\b|from\s+['"](?:react|vue|svelte|next|nuxt|@sveltejs|astro)|getServerSideProps|defineNuxtComponent/i,
+  TOPLEVEL_IMPORT: /^\s*import\s+['"]@adia-ai\/web-components['"]\s*;?\s*$/m,
+  OVERLAY_OPEN: /<(?:modal|drawer)-ui\b[^>]*?(?<![:.\w])\bopen\b(?!\s*=\s*\{)/,
+};
+
+/** Per-declaration split on `;` — mirrors both Python scripts' `line.split(';')` loops. */
+function declarations(line) {
+  return line.split(';');
+}
+
+/**
+ * Scans one double-quoted YAML scalar starting at text[startIdx] === '"',
+ * spanning as many physical lines as needed — used by extractYamlA2uiBlocks
+ * for the inline-quoted `a2ui: "[\n ... ]"` style, which the corpus authors
+ * as a long single YAML scalar wrapped across many lines via YAML's
+ * "escaped line break" rule: a lone `\` immediately before a newline drops
+ * both the backslash and the newline (no space inserted) and strips the
+ * next line's leading indentation — the shape `pane.yaml`/`input.yaml`/etc.
+ * actually use for long examples. A bare (non-escaped) newline inside the
+ * quotes does not occur in this corpus and is not specially handled here
+ * (falls through to JSON.parse failing on it, same fail-soft as any other
+ * unparseable block). Returns `{ raw, endIdx }` — `raw` is a single-line
+ * JSON-string-literal source (JSON.parse-able); `endIdx` is the index one
+ * past the closing quote, for the caller to resume scanning after.
+ */
+function scanYamlDoubleQuoted(text, startIdx) {
+  let i = startIdx + 1;
+  let out = '"';
+  while (i < text.length) {
+    const c = text[i];
+    if (c === '\\' && text[i + 1] === '\n') {
+      // escaped line break — drop `\` + newline, strip the continuation
+      // line's leading indentation, insert nothing.
+      i += 2;
+      while (i < text.length && (text[i] === ' ' || text[i] === '\t')) i += 1;
+      continue;
+    }
+    if (c === '\\' && text[i + 1] === ' ') {
+      // YAML double-quoted scalar's `\ ` escape (literal space, used to
+      // pin down leading whitespace that line-folding would otherwise
+      // strip) has no JSON equivalent — JSON.parse rejects a bare
+      // backslash-space. Emit the space alone; JSON needs no escape for it.
+      out += ' ';
+      i += 2;
+      continue;
+    }
+    if (c === '\\') {
+      out += c;
+      if (i + 1 < text.length) { out += text[i + 1]; i += 2; } else { i += 1; }
+      continue;
+    }
+    out += c;
+    i += 1;
+    if (c === '"') break;
+  }
+  return { raw: out, endIdx: i };
+}
+
+/**
+ * Yaml-corpus primitive (grows C2's primitive set for the .yaml fileType
+ * rules — LLD-0016 §C3): walks a component yaml's raw text for every
+ * `examples[].a2ui` scalar (block `>-`/`|`/`|-` or inline double-quoted,
+ * single- or multi-line) and JSON.parses each into its flat node array.
+ * Indentation-based, not a full YAML parse — rule modules stay stdlib-only
+ * (§C2), so this only recognizes the two scalar shapes the corpus actually
+ * uses, not the full YAML scalar grammar. A block whose content isn't
+ * JSON.parse-able, or doesn't parse to an array, is skipped (a malformed
+ * example is verify:a2ui-schema's concern, not this primitive's). Returns
+ * `{ line, nodes }[]`, `line` = the `a2ui:` key's own 1-based line number.
+ */
+function extractYamlA2uiBlocks(text) {
+  const lines = text.split('\n');
+  const out = [];
+  const KEY_RE = /^([ \t]*)a2ui:[ \t]*(.*)$/gm;
+  let m;
+  while ((m = KEY_RE.exec(text))) {
+    const indent = m[1].length;
+    const rest = m[2];
+    const keyLineNo = lineOf(text, m.index);
+    let jsonText = null;
+    if (rest.trim().startsWith('"')) {
+      const quoteOffset = m.index + (m[0].length - rest.length) + rest.indexOf('"');
+      const { raw, endIdx } = scanYamlDoubleQuoted(text, quoteOffset);
+      try {
+        jsonText = JSON.parse(raw);
+      } catch {
+        jsonText = null;
+      }
+      KEY_RE.lastIndex = endIdx;
+    } else {
+      const i = keyLineNo - 1;
+      const body = [];
+      let j = i + 1;
+      while (j < lines.length) {
+        const line = lines[j];
+        if (line.trim() === '') { body.push(''); j += 1; continue; }
+        const lineIndent = line.match(/^(\s*)/)[1].length;
+        if (lineIndent <= indent) break;
+        body.push(line);
+        j += 1;
+      }
+      jsonText = body.join('\n');
+    }
+    if (!jsonText || !jsonText.trim().startsWith('[')) continue;
+    try {
+      const nodes = JSON.parse(jsonText);
+      if (Array.isArray(nodes)) out.push({ line: keyLineNo, nodes });
+    } catch {
+      // malformed example JSON — not this primitive's concern
+    }
+  }
+  return out;
+}
+
+const TAG_TOKEN_RE = /<(\/?)([a-zA-Z][\w-]*)((?:\s+[^<>]*)?)(\/?)>/g;
+const VOID_TAGS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr',
+]);
+
+/**
+ * LLD-0016 §C4/Risk R4: a single-file tag-adjacency walk — a stack-based
+ * tokenizer, not a full HTML/DOM parser, matching SHELL-NESTING's existing
+ * markup-only, single-file, no-cross-file-resolution precedent (the
+ * closest prior art this design extends rather than building from
+ * scratch). Tolerant of malformed/truncated markup (unclosed tags at EOF
+ * are flushed as-is) so a small fixture snippet never throws.
+ *
+ * Returns one node per open (or self-closing/void) tag, in document
+ * order: `{ tag, parentTag, line, childTags }` — `parentTag` is `'ROOT'`
+ * for a top-level occurrence (the A2UI "Surface" case), `childTags` is
+ * the ordered list of direct-child tag names only (not descendants).
+ */
+function tagTree(text) {
+  const nodes = [];
+  const stack = []; // { tag, parentTag, line, children: string[] }
+  TAG_TOKEN_RE.lastIndex = 0;
+  let m;
+  while ((m = TAG_TOKEN_RE.exec(text))) {
+    const [, closing, tag, , selfClose] = m;
+    const line = lineOf(text, m.index);
+    if (closing) {
+      let at = -1;
+      for (let i = stack.length - 1; i >= 0; i -= 1) {
+        if (stack[i].tag === tag) { at = i; break; }
+      }
+      if (at === -1) continue; // stray close tag — ignore
+      const frame = stack[at];
+      nodes.push({ tag: frame.tag, parentTag: frame.parentTag, line: frame.line, childTags: frame.children });
+      stack.length = at; // pop this frame and any unclosed frames above it
+      continue;
+    }
+    const parentTag = stack.length ? stack[stack.length - 1].tag : 'ROOT';
+    if (stack.length) stack[stack.length - 1].children.push(tag);
+    if (selfClose || VOID_TAGS.has(tag.toLowerCase())) {
+      nodes.push({ tag, parentTag, line, childTags: [] });
+    } else {
+      stack.push({ tag, parentTag, line, children: [] });
+    }
+  }
+  while (stack.length) {
+    const frame = stack.pop();
+    nodes.push({ tag: frame.tag, parentTag: frame.parentTag, line: frame.line, childTags: frame.children });
+  }
+  return nodes;
+}
+
+/**
+ * LLD-0016 §C4: check every occurrence of `tag` in `text` against its
+ * declared `allowedParents`/`allowedChildren` (already resolved from
+ * catalog `component:` names to tag names by the generator —
+ * scripts/build/gen-composition-rules.mjs — so this stays a pure
+ * string/tree matcher with no registry lookup at match-time, same as
+ * every other rule). The reserved catalog name `'Surface'` in
+ * `allowedParents` matches a `parentTag === 'ROOT'` occurrence.
+ */
+function compositionFindings(text, { tag, allowedParents, allowedChildren }) {
+  const out = [];
+  for (const node of tagTree(text)) {
+    if (node.tag !== tag) continue;
+    if (allowedParents && allowedParents.length) {
+      const parentOk = node.parentTag === 'ROOT'
+        ? allowedParents.includes('Surface')
+        : allowedParents.includes(node.parentTag);
+      if (!parentOk) {
+        const parentLabel = node.parentTag === 'ROOT' ? '(surface root)' : `<${node.parentTag}>`;
+        out.push({
+          line: node.line,
+          snippet: `${parentLabel} > <${tag}>`,
+          why: `<${tag}> declares a2ui.allowedParents: [${allowedParents.join(', ')}] — ${parentLabel} is not one of them`,
+        });
+      }
+    }
+    if (allowedChildren && allowedChildren.length) {
+      for (const child of node.childTags) {
+        if (!allowedChildren.includes(child)) {
+          out.push({
+            line: node.line,
+            snippet: `<${tag}> > <${child}>`,
+            why: `<${tag}> declares a2ui.allowedChildren: [${allowedChildren.join(', ')}] — <${child}> is not one of them`,
+          });
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Yaml-corpus primitive (LLD-0016 §C3): reads one component yaml's own
+ * top-level `component:` scalar and its `props:` mapping's first-level key
+ * names (not the full per-prop schema) — enough for EXAMPLE-PROP-CONTRACT's
+ * cross-file corpus map. Indentation-based, not a full YAML parse (§C2).
+ */
+function extractYamlComponentPropKeys(text) {
+  const lines = text.split('\n');
+  let component = null;
+  const propKeys = new Set();
+  for (let i = 0; i < lines.length; i += 1) {
+    const cm = /^component:\s*(.+?)\s*$/.exec(lines[i]);
+    if (cm && component === null) {
+      // Strip a trailing `# comment` outside quotes — a bare split would
+      // otherwise bake it into the captured component name.
+      component = cm[1].replace(/\s+#.*$/, '').replace(/^['"]|['"]$/g, '');
+      continue;
+    }
+    if (/^props:\s*$/.test(lines[i])) {
+      let j = i + 1;
+      let keyIndent = null;
+      while (j < lines.length) {
+        const line = lines[j];
+        if (line.trim() === '') { j += 1; continue; }
+        const lineIndent = line.match(/^(\s*)/)[1].length;
+        if (lineIndent === 0) break;
+        if (keyIndent === null) keyIndent = lineIndent;
+        if (lineIndent < keyIndent) break;
+        if (lineIndent === keyIndent) {
+          const km = /^\s*(?:'([^']+)'|"([^"]+)"|([\w-]+)):/.exec(line);
+          if (km) propKeys.add(km[1] || km[2] || km[3]);
+        }
+        j += 1;
+      }
+    }
+  }
+  return { component, propKeys };
+}
+
+
+/**
+ * scripts/lint/engine/run.mjs — the rule-bank runner. Takes a list of rule
+ * modules (LLD-0016 §C1 shape) plus a scope filter, and turns
+ * `lintText(text, path)` into the same `{ name, line, snippet, why }`
+ * Finding[] shape both Python scripts returned — so `_render()`'s output
+ * format, and everything downstream of it (PostToolUse additionalContext,
+ * `npm run lint` console output), does not have to change in this slice.
+ */
+
+
+/**
+ * @param {Array<{id:string, severity:string, scope:string, fileTypes:string[], match:Function}>} rules
+ * @param {{scopes?: string[]}} [opts] which rule scopes to run — omit for all
+ */
+function makeLinter(rules, opts = {}) {
+  const scopes = opts.scopes || null;
+  const active = rules.filter((r) => !scopes || scopes.includes(r.scope));
+
+  function lintText(text, path = '') {
+    const fileExt = ext(path);
+    const rawLines = text.split('\n');
+    let findings = [];
+    for (const rule of active) {
+      if (rule.fileTypes && rule.fileTypes.length && !rule.fileTypes.includes(fileExt)) continue;
+      const hits = rule.match(text, path, { scopes }) || [];
+      for (const h of hits) {
+        findings.push({ name: rule.id, line: h.line, snippet: h.snippet, why: h.why });
+      }
+    }
+
+    // Suppression syntax (LLD-0016 §Interfaces):
+    // /* adia-lint-disable <rule-id> — <reason> */ on the finding's own line
+    // or the line before it drops that one finding. A bare disable with no
+    // <reason> is itself a finding (SUPPRESS-NO-REASON, warn) — checked
+    // once per suppression comment in the file, independent of whether it
+    // actually suppressed anything this run.
+    findings = findings.filter((f) => !suppressionFor(rawLines, f.line, f.name).suppressed);
+    for (const s of allSuppressions(rawLines)) {
+      if (!s.hasReason) {
+        findings.push({
+          name: 'SUPPRESS-NO-REASON',
+          line: s.lineNo,
+          snippet: (rawLines[s.lineNo - 1] || '').trim().slice(0, 90),
+          why: `annotate why ${s.ruleId} is suppressed here — a bare adia-lint-disable with no reason is load-bearing, not cosmetic`,
+        });
+      }
+    }
+
+    findings.sort((a, b) => (a.line - b.line) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return findings;
+  }
+
+  return { lintText, rules: active };
+}
+
+function render(path, findings) {
+  const out = [`${findings.__label || 'lint'}: ${findings.length} structural smell(s) in ${path || '<stdin>'}`];
+  for (const f of findings) {
+    out.push(`  [${f.name}] line ${f.line}: ${f.snippet}`);
+    out.push(`      → ${f.why}`);
+  }
+  return out.join('\n');
+}
+
+
+const RULES = [];
+{
+
+
+const APPLIES_EXT = ['.html', '.htm', '.vue', '.svelte', '.astro', '.tsx', '.jsx', '.js', '.mjs', '.ts'];
+
+const genuiUnvalidated = {
+  id: 'GENUI-UNVALIDATED',
+  severity: 'error',
+  scope: 'consumer-only',
+  fileTypes: APPLIES_EXT,
+  match(text) {
+    const m = /\.doc\s*=/.exec(text);
+    if (!m) return [];
+    const line = lineOf(text, m.index);
+    if (text.includes('validate_schema') || text.includes('check_anti_patterns')) return [];
+    return [{
+      line,
+      snippet: '.doc = … with no validate in file',
+      why: 'A2UI fed to .doc must pass validate_schema + check_anti_patterns first (gen-ui-wiring\'s hard gate) — validate in the same module or cite where it happened',
+    }];
+  },
+};
+
+const genuiDocConflict = {
+  id: 'GENUI-DOC-CONFLICT',
+  severity: 'error',
+  scope: 'consumer-only',
+  fileTypes: APPLIES_EXT,
+  match(text) {
+    const m = /\.doc\s*=/.exec(text);
+    if (!m) return [];
+    const line = lineOf(text, m.index);
+    if (/<(?:a2ui-root|gen-root)[^>]*\b(?:src|transport)=/.test(text)) {
+      return [{
+        line,
+        snippet: '.doc = … alongside src=/transport=',
+        why: 'two feed paths fight — a root is fed EITHER declaratively (src/transport) OR programmatically (.doc), never both',
+      }];
+    }
+    return [];
+  },
+};
+
+
+RULES.push(genuiUnvalidated, genuiDocConflict);
+}
+
+{
+
+
+// `*.examples.html` is always a component-gallery page (packages/*/
+// components, apps/overview.examples.html) — never live wired app code.
+// `*.contents.html` is NOT universally a demo: ADR-0021 makes it the live
+// production content-fragment convention fetched and injected verbatim by
+// every apps/* and playgrounds/* page shell, so a stuck-open modal there is
+// a real bug, not a gallery artifact. Only catalog/**/*.contents.html — the
+// pattern-catalog's own chunk demos, captured statically for the gallery —
+// gets the exemption; scope it to that tree, not the filename alone.
+const EXAMPLES_FILE = /\.examples\.html$/;
+const CATALOG_CONTENTS_FILE = /\.contents\.html$/;
+
+
+RULES.push({
+  id: 'HARDCODED-OPEN',
+  severity: 'error',
+  scope: 'consumer-only',
+  fileTypes: MARKUP_EXT,
+  match(text, path) {
+    const p = (path || '').replace(/\\/g, '/');
+    if (EXAMPLES_FILE.test(p)) return [];
+    if (CATALOG_CONTENTS_FILE.test(p) && p.split('/')[0] === 'catalog') return [];
+    const out = [];
+    text.split('\n').forEach((line, i) => {
+      if (RE.OVERLAY_OPEN.test(line)) {
+        out.push({
+          line: i + 1,
+          snippet: line.trim().slice(0, 90),
+          why: 'drive overlays via the .open property, not a hardcoded `open` attribute (it bricks the page)',
+        });
+      }
+    });
+    return out;
+  },
+});
+}
+
+{
+
+
+const APPLIES_EXT = ['.html', '.htm', '.vue', '.svelte', '.astro', '.tsx', '.jsx', '.js', '.mjs', '.ts'];
+
+// Only a quoted string literal is a candidate secret — `process.env.X`, a
+// bare identifier (`opts.apiKey`), and a TS type annotation (`apiKey:
+// string`) are all references, not values, and never match this capture.
+const KEY_ASSIGN = /\bapi[-_]?[Kk]ey\b\s*[:=]\s*(['"`])((?:\\.|(?!\1).)*)\1/g;
+
+
+RULES.push({
+  id: 'LLM-KEY-IN-CLIENT',
+  severity: 'error',
+  scope: 'consumer-only',
+  fileTypes: APPLIES_EXT,
+  match(text, path) {
+    const segs = (path || '').replace(/\\/g, '/').toLowerCase().split('/');
+    const base = segs[segs.length - 1] || '';
+    // server-side execution contexts: an explicit server/proxy/api dir, a
+    // CLI/MCP script tree, or a test file (fake keys in test fixtures never
+    // ship to a browser).
+    if (segs.some((s) => s.includes('server') || s.includes('proxy') || s === 'api' || s === 'mcp' || s === 'cli' || s === 'scripts')) return [];
+    if (/\.(test|spec)\.[jt]sx?$/.test(base)) return [];
+    const out = [];
+    for (const { lineNo, stripped } of stripCommentLines(text, ext(path))) {
+      let m;
+      KEY_ASSIGN.lastIndex = 0;
+      while ((m = KEY_ASSIGN.exec(stripped))) {
+        const value = m[2];
+        // an empty string is a default/reset, not a secret; a value that
+        // documents itself as non-secret (a proxy sentinel) isn't one either
+        if (!value || /server-side|proxy/i.test(value)) continue;
+        out.push({
+          line: lineNo,
+          snippet: stripped.trim().slice(0, 90),
+          why: 'a provider key in client source ships to the browser — production uses a same-origin smart proxy (proxy-url); keys live server-side (llm-wiring)',
+        });
+      }
+    }
+    return out;
+  },
+});
+}
+
+{
+
+
+const APPLIES_EXT = ['.html', '.htm', '.vue', '.svelte', '.astro', '.tsx', '.jsx', '.js', '.mjs', '.ts'];
+
+
+RULES.push({
+  id: 'SHELL-NESTING',
+  severity: 'error',
+  scope: 'consumer-only',
+  fileTypes: APPLIES_EXT,
+  match(text) {
+    const out = [];
+    const pages = (text.match(/<admin-page[\s/>]/g) || []).length;
+    const scrolls = (text.match(/<admin-scroll[\s/>]/g) || []).length;
+    if (scrolls && pages > scrolls) {
+      out.push({
+        line: 1,
+        snippet: '<admin-page> × N inside <admin-scroll>',
+        why: 'each <admin-scroll> hosts exactly one <admin-page> — multiple pages need multiple scroll regions',
+      });
+    }
+    const re = /<(?:col|row)-ui[^>]*>\s*<(?:admin|chat|editor)-/g;
+    let m;
+    while ((m = re.exec(text))) {
+      out.push({
+        line: lineOf(text, m.index),
+        snippet: text.slice(m.index, m.index + 60).trim().slice(0, 90),
+        why: 'shell children are positioned by tag selectors — wrapping them in <col-ui>/<row-ui> breaks the shell grid; generics go inside admin-content/admin-page-body',
+      });
+    }
+    return out;
+  },
+});
+}
+
+{
+const APPLIES_EXT = ['.html', '.htm', '.vue', '.svelte', '.astro', '.tsx', '.jsx', '.js', '.mjs', '.ts'];
+
+
+RULES.push({
+  id: 'SHELL-RESIZE',
+  severity: 'error',
+  scope: 'consumer-only',
+  fileTypes: APPLIES_EXT,
+  match(text) {
+    if (/<admin-sidebar[^>]*\bresizable\b/.test(text) && !text.includes('data-sidebar-resize')) {
+      return [{
+        line: 1,
+        snippet: '<admin-sidebar resizable> without [data-sidebar-resize]',
+        why: '[resizable] needs a child <div data-sidebar-resize> or there is no drag handle',
+      }];
+    }
+    return [];
+  },
+});
+}
+
+{
+
+
+function isSsr(text, fileExt) {
+  return RE.SSR_SIGNAL.test(text) || ['.vue', '.svelte', '.astro'].includes(fileExt);
+}
+
+const ssrDoubleRouter = {
+  id: 'SSR-DOUBLE-ROUTER',
+  severity: 'error',
+  scope: 'consumer-only',
+  fileTypes: [],
+  match(text, path) {
+    const fileExt = ext(path);
+    if (!isSsr(text, fileExt)) return [];
+    const out = [];
+    text.split('\n').forEach((line, i) => {
+      if (line.includes('<router-ui')) {
+        out.push({
+          line: i + 1,
+          snippet: line.trim().slice(0, 90),
+          why: "in SSR the framework router owns routing — don't also mount <router-ui> (two route owners)",
+        });
+      }
+    });
+    return out;
+  },
+};
+
+const ssrToplevelImport = {
+  id: 'SSR-TOPLEVEL-IMPORT',
+  severity: 'error',
+  scope: 'consumer-only',
+  fileTypes: [],
+  match(text, path) {
+    const fileExt = ext(path);
+    if (!isSsr(text, fileExt)) return [];
+    const out = [];
+    text.split('\n').forEach((line, i) => {
+      if (RE.TOPLEVEL_IMPORT.test(line)) {
+        out.push({
+          line: i + 1,
+          snippet: line.trim().slice(0, 90),
+          why: 'a top-level kit import throws `HTMLElement is not defined` on the server — defer it into a client hook',
+        });
+      }
+    });
+    return out;
+  },
+};
+
+
+RULES.push(ssrDoubleRouter, ssrToplevelImport);
+}
+
+{
+
+
+
+RULES.push({
+  id: 'MISSING-SCOPE',
+  severity: 'error',
+  scope: 'forge-only',
+  fileTypes: STYLE_EXT,
+  match(text, path) {
+    const isTokenish = isFoundationCss(path, text, 'forge-lint');
+    if (isTokenish) return [];
+    if (text.includes('@scope')) return [];
+    if (!RE.SELECTOR_RULE.test(text)) return [];
+    return [{
+      line: 1,
+      snippet: '(file has CSS rules but no @scope block)',
+      why: 'component CSS must be wrapped in `@scope (<tag>) { … }` so styles don\'t leak in light DOM (foundation/token sheets excepted; opt out with /* forge-lint: foundation */)',
+    }];
+  },
+});
+}
+
+{
+// GENERATED — do not hand-edit. Source: packages/web-modules/chat/chat-shell/chat-shell.yaml's a2ui.allowedParents/allowedChildren.
+// Rebuild: node scripts/build/gen-composition-rules.mjs
+// Freshness gate: node scripts/verify/check-composition-rules-fresh.mjs --verify
+
+
+const TAG = "chat-shell";
+const ALLOWED_PARENTS = ["Surface"];
+const ALLOWED_CHILDREN = [];
+
+
+RULES.push({
+  id: "COMPOSITION-CHAT-SHELL",
+  severity: 'warn', // LLD-0016 §C4: new, unproven-at-scale matcher (Risk R4) — advisory until a corpus-wide rollout promotes it, same posture check-example-ids.mjs's Phase-1 rule started at.
+  scope: 'shared',
+  fileTypes: MARKUP_EXT,
+  match(text) {
+    return compositionFindings(text, { tag: TAG, allowedParents: ALLOWED_PARENTS, allowedChildren: ALLOWED_CHILDREN });
+  },
+  fix: null, // moving markup to satisfy a composition constraint is a judgment call, not a mechanical rename (LLD-0016 §Risks R4/R5)
+  fixtures: {
+    "smelly": [
+      "<col-ui><chat-shell></chat-shell></col-ui>"
+    ],
+    "clean": [
+      "<chat-shell></chat-shell>"
+    ]
+  },
+});
+}
+
+{
+
+
+/**
+ * gh#2648 (LLD-0016 §C3) — the 12-entry hand-authored registry formerly in
+ * packages/gen-ui/engine/retrieval/anti-patterns.js, absorbed as rule
+ * modules with `scope: 'genui-output'`. `noInventedComponents` stays OUT of
+ * this file and out of the generated bank on purpose: it needs the live
+ * `@adia-ai/a2ui` registry + component-catalog.js sidecar data at check
+ * time, not a stdlib-only text/regex match — the same reasoning LLD-0016's
+ * own Non-goals section gives for leaving check-genui-catalog.mjs's
+ * runtime-state assertions out of the shared bank. It stays authored
+ * directly in anti-patterns.js, which composes it with these 11.
+ *
+ * `id` is kept as the original camelCase pattern name (not the bank's usual
+ * UPPER-KEBAB convention) because `checkAntiPattern(name, html)`'s public
+ * contract keys on that exact string (LLD-0016 §Interfaces: "public name
+ * and input/output shape unchanged") — a callable a2ui-maintenance skills
+ * and anti-patterns.test.js both depend on today.
+ *
+ * `description`/`guidance` are extra fields the generic engine (run.mjs)
+ * never reads — anti-patterns.js reads them to reconstruct the legacy
+ * `{name, description, fix}` shape. `fix` is deliberately left unset: it is
+ * the C1 auto-fixer slot `(text, finding) => text`, a different thing from
+ * the human-readable remediation text these patterns call `fix` in their
+ * old shape (renamed `guidance` here to avoid the collision).
+ */
+
+const HTML_LIKE = [];
+
+const noBareDivs = {
+  id: 'noBareDivs',
+  severity: 'error',
+  scope: 'genui-output',
+  fileTypes: HTML_LIKE,
+  description: 'All elements should be AdiaUI components, not bare <div> elements.',
+  guidance: 'Replace <div> with the appropriate AdiaUI layout component: Row, Column, Grid, Card, or Section.',
+  match(text) {
+    const m = /<div[\s>]/i.exec(text);
+    if (!m) return [];
+    return [{ line: lineOf(text, m.index), snippet: text.slice(m.index, m.index + 60).trim(), why: 'bare <div> — AdiaUI elements only' }];
+  },
+};
+
+const noBareInputs = {
+  id: 'noBareInputs',
+  severity: 'error',
+  scope: 'genui-output',
+  fileTypes: HTML_LIKE,
+  description: 'Form controls should use component wrappers, not native <input>/<select>/<textarea>.',
+  guidance: 'Use input-ui, select-ui, textarea-ui, check-ui, switch-ui, slider-ui, or datetime-ui instead.',
+  match(text) {
+    const m = /<(input|select|textarea)[\s>]/i.exec(text);
+    if (!m) return [];
+    return [{ line: lineOf(text, m.index), snippet: text.slice(m.index, m.index + 60).trim(), why: 'native form control — AdiaUI wrapper only' }];
+  },
+};
+
+const cardStructure = {
+  id: 'cardStructure',
+  severity: 'error',
+  scope: 'genui-output',
+  fileTypes: HTML_LIKE,
+  description: 'Card children must follow the header/section/footer anatomy. Header and footer are direct children of card.',
+  guidance: 'Header and Footer must be direct children of Card, not nested inside Section. Structure: Card > Header + Section + Footer.',
+  match(text) {
+    const m = /<section[^>]*>\s*<header/i.exec(text) || /<section[^>]*>\s*<footer/i.exec(text);
+    if (!m) return [];
+    return [{ line: lineOf(text, m.index), snippet: text.slice(m.index, m.index + 60).trim(), why: 'header/footer nested inside section' }];
+  },
+};
+
+const flatAdjacency = {
+  id: 'flatAdjacency',
+  severity: 'error',
+  scope: 'genui-output',
+  fileTypes: HTML_LIKE,
+  description: 'AdiaUI uses flat component lists with ID references, not deeply nested component trees.',
+  guidance: 'Use a flat adjacency list with unique IDs and children arrays referencing IDs.',
+  match(text) {
+    const m = /<[a-z]+-(?:n|ui)[^>]*>\s*<[a-z]+-(?:n|ui)[^>]*>\s*<[a-z]+-(?:n|ui)[^>]*>\s*<[a-z]+-(?:n|ui)[^>]*>\s*<[a-z]+-(?:n|ui)/i.exec(text);
+    if (!m) return [];
+    return [{ line: lineOf(text, m.index), snippet: text.slice(m.index, m.index + 60).trim(), why: '5+ levels of nested AdiaUI components' }];
+  },
+};
+
+const columnWrap = {
+  id: 'columnWrap',
+  severity: 'error',
+  scope: 'genui-output',
+  fileTypes: HTML_LIKE,
+  description: 'Content inside Section must be wrapped in a Column (col-ui), not placed directly.',
+  guidance: 'Wrap section content in <col-ui>: Section > Column > Text/content.',
+  match(text) {
+    const m = /<section[^>]*>\s*<(text-ui|p |p>|h[1-6])/i.exec(text);
+    if (!m) return [];
+    return [{ line: lineOf(text, m.index), snippet: text.slice(m.index, m.index + 60).trim(), why: 'section content not wrapped in col-ui' }];
+  },
+};
+
+const noHardcodedColors = {
+  id: 'noHardcodedColors',
+  severity: 'error',
+  scope: 'genui-output',
+  fileTypes: HTML_LIKE,
+  description: 'Use design token colors (--a-*) instead of hardcoded hex/rgb/hsl values.',
+  guidance: 'Use token-based colors via variant attributes or CSS custom properties (--a-canvas-*, --a-primary-*, etc.).',
+  match(text) {
+    const m = /(style\s*=\s*"[^"]*(?:color|background)\s*:\s*(?:#[0-9a-f]{3,8}|rgb|hsl))/i.exec(text);
+    if (!m) return [];
+    return [{ line: lineOf(text, m.index), snippet: text.slice(m.index, m.index + 60).trim(), why: 'hardcoded color literal in inline style' }];
+  },
+};
+
+const noInlineLayout = {
+  id: 'noInlineLayout',
+  severity: 'error',
+  scope: 'genui-output',
+  fileTypes: HTML_LIKE,
+  description: 'Use declarative layout attributes instead of inline display/flex/grid styles.',
+  guidance: 'Use Row, Column, Grid components with gap/columns attributes instead of inline CSS layout.',
+  match(text) {
+    const m = /(style\s*=\s*"[^"]*(?:display\s*:|flex|grid-template))/i.exec(text);
+    if (!m) return [];
+    return [{ line: lineOf(text, m.index), snippet: text.slice(m.index, m.index + 60).trim(), why: 'inline CSS layout instead of a layout component' }];
+  },
+};
+
+const noCssPropAttrs = {
+  id: 'noCssPropAttrs',
+  severity: 'error',
+  scope: 'genui-output',
+  fileTypes: HTML_LIKE,
+  description: 'CSS properties (display, visibility) are not markup attributes. Components silently ignore unknown attributes, so display="none" content renders VISIBLY — overlapping its siblings.',
+  guidance: 'Remove the attribute. To hide content conditionally, omit the element from the tree (or use the component\'s documented state attribute, e.g. [hidden] on plain containers).',
+  match(text) {
+    const m = /\s(?:display|visibility)\s*=\s*"/i.exec(text);
+    if (!m) return [];
+    return [{ line: lineOf(text, m.index), snippet: text.slice(m.index, m.index + 60).trim(), why: 'CSS property used as a markup attribute' }];
+  },
+};
+
+const inputTypeTextarea = {
+  id: 'inputTypeTextarea',
+  severity: 'error',
+  scope: 'genui-output',
+  fileTypes: HTML_LIKE,
+  description: 'input-ui has no type="textarea" — multi-line input is its own component.',
+  guidance: 'Use <textarea-ui rows="…"> for multi-line text input.',
+  match(text) {
+    const m = /<input-ui[^>]*\btype\s*=\s*"textarea"/i.exec(text);
+    if (!m) return [];
+    return [{ line: lineOf(text, m.index), snippet: text.slice(m.index, m.index + 60).trim(), why: 'input-ui type="textarea" does not exist' }];
+  },
+};
+
+const fieldOwnsLabelHintError = {
+  id: 'fieldOwnsLabelHintError',
+  severity: 'error',
+  scope: 'genui-output',
+  fileTypes: HTML_LIKE,
+  description: 'field-ui OWNS the label / hint / error chrome via its label= / hint= / error= attributes. Emitting a sibling text-ui "label", a raw <label>, or a <small> error inside field-ui double-renders and breaks the label-to-control binding (field-ui binds the first slot-less child as the control — a text-ui label steals that binding).',
+  guidance: 'Use <field-ui label="Full Name" hint="…" error="…"><input-ui …/></field-ui> — exactly ONE slot-less child (the control); field-ui renders the label, hint, and error itself.',
+  match(text) {
+    // Excludes the stamped internal label (data-field-label) so post-render
+    // HTML doesn't false-positive — matches the original check's own comment.
+    let m = /<field-ui[^>]*>\s*(?:<text-ui[^>]*variant\s*=\s*"label"|<label(?![^>]*data-field-label))/i.exec(text);
+    if (!m) m = /<field-ui[^>]*>[\s\S]*?<small[\s>]/i.exec(text);
+    if (!m) return [];
+    return [{ line: lineOf(text, m.index), snippet: text.slice(m.index, m.index + 60).trim(), why: 'field-ui already owns label/hint/error chrome' }];
+  },
+};
+
+const slotOnContainer = {
+  id: 'slotOnContainer',
+  severity: 'error',
+  scope: 'genui-output',
+  fileTypes: HTML_LIKE,
+  description: 'Slot attributes (slot="heading", slot="description", slot="action") must go on the content children inside Header/Footer, not on Header/Footer elements themselves.',
+  guidance: 'Move slot="heading" from <header> to the Text/heading child inside it. Header is a grid container — slots go on its children.',
+  match(text) {
+    let m = /<header[^>]*\bslot\s*=/i.exec(text);
+    if (!m) m = /<footer[^>]*\bslot\s*=/i.exec(text);
+    if (!m) return [];
+    return [{ line: lineOf(text, m.index), snippet: text.slice(m.index, m.index + 60).trim(), why: 'slot attribute on header/footer instead of its child' }];
+  },
+};
+
+
+RULES.push(noBareDivs,
+  noBareInputs,
+  cardStructure,
+  flatAdjacency,
+  columnWrap,
+  noHardcodedColors,
+  noInlineLayout,
+  noCssPropAttrs,
+  inputTypeTextarea,
+  fieldOwnsLabelHintError,
+  slotOnContainer,);
+}
+
+{
+
+
+// A UIElement `static properties = {...}` (or the legacy `static props =`
+// spelling) block — `attr:` is only a real typo for `attribute:` inside one
+// of these; the same key shows up on plenty of unrelated APIs
+// (observeBreakpoint's config, example-data objects) where it's correct.
+const PROPS_BLOCK_OPEN = /\bstatic\s+prop(?:s|erties)\s*=\s*\{/g;
+
+/** Char-offset [start, end) ranges of every static-properties block body. */
+function propsBlockRanges(stripped) {
+  const ranges = [];
+  let m;
+  PROPS_BLOCK_OPEN.lastIndex = 0;
+  while ((m = PROPS_BLOCK_OPEN.exec(stripped))) {
+    const braceStart = m.index + m[0].length - 1;
+    let depth = 1;
+    let i = braceStart + 1;
+    let quote = null;
+    // brace-count outside string literals only — a `{`/`}` inside a quoted
+    // default value must not throw off the block's real close.
+    while (i < stripped.length && depth > 0) {
+      const c = stripped[i];
+      if (quote) {
+        if (c === '\\') i += 1;
+        else if (c === quote) quote = null;
+      } else if (c === '"' || c === "'" || c === '`') {
+        quote = c;
+      } else if (c === '{') {
+        depth += 1;
+      } else if (c === '}') {
+        depth -= 1;
+      }
+      i += 1;
+    }
+    ranges.push([braceStart, i]);
+  }
+  return ranges;
+}
+
+
+RULES.push({
+  id: 'ATTR-TYPO',
+  severity: 'error',
+  scope: 'shared',
+  fileTypes: CODE_EXT,
+  match(text, path) {
+    const out = [];
+    const stripped = stripCommentLines(text, ext(path)).map((l) => l.stripped).join('\n');
+    const ranges = propsBlockRanges(stripped);
+    if (!ranges.length) return out;
+    const rawLines = text.split('\n');
+    const re = new RegExp(RE.ATTR_TYPO.source, 'g');
+    let m;
+    while ((m = re.exec(stripped))) {
+      if (!ranges.some(([s, e]) => m.index >= s && m.index < e)) continue;
+      const lineNo = lineOf(stripped, m.index);
+      out.push({
+        line: lineNo,
+        snippet: (rawLines[lineNo - 1] || '').trim().slice(0, 90),
+        why: 'did you mean `attribute:`? `attr:` is silently ignored in a property definition',
+      });
+    }
+    return out;
+  },
+});
+}
+
+{
+
+
+
+RULES.push({
+  id: 'BOOL-DEFAULT-TRUE',
+  severity: 'warn',
+  scope: 'shared',
+  fileTypes: CODE_EXT,
+  match(text, path) {
+    const out = [];
+    for (const { lineNo, raw, stripped } of stripCommentLines(text, ext(path))) {
+      if (!stripped.trim()) continue;
+      if (RE.BOOL_TRUE.test(stripped)) {
+        out.push({
+          line: lineNo,
+          snippet: raw.trim().slice(0, 90),
+          why: "a boolean prop defaulting true can't be turned off by absence — flip the name so absent = false; if the shape is deliberate, note that UIElement stamps the attribute on connect since gh#961 (attribute-keyed CSS is safe), and the attribute reflects truth",
+        });
+      }
+    }
+    return out;
+  },
+});
+}
+
+{
+
+
+
+RULES.push({
+  id: 'DEAD-FONT-TOKEN',
+  severity: 'warn',
+  scope: 'shared',
+  fileTypes: STYLE_EXT,
+  match(text, path) {
+    const out = [];
+    for (const { lineNo, raw, stripped } of stripCommentLines(text, ext(path))) {
+      if (!stripped.trim()) continue;
+      if (RE.DEAD_FONT.test(stripped)) {
+        out.push({
+          line: lineNo,
+          snippet: raw.trim().slice(0, 90),
+          why: '--a-font is not a real token (resolves to UA serif) — use var(--a-font-family-ui)',
+        });
+      }
+    }
+    return out;
+  },
+  // LLD-0016 §Risks R5: the one rule this design proves `fix()` against —
+  // its own `why` already names the single correct replacement
+  // (`--a-font-family-ui`), and RE.DEAD_FONT only matches the bare dead
+  // token immediately followed by `,`/`)` (optional whitespace between),
+  // so it can never re-match an already-correct `--a-font-family-ui`
+  // reference — no ambiguity, unlike ATTR-TYPO's `attr:` regex, which
+  // this ticket's grounding pass found collides with unrelated option
+  // keys named `attr` in real corpus code (packages/web-components/core/
+  // breakpoint-observer.test.js) and is therefore NOT safe to auto-fix
+  // as shipped — filed as a follow-up, not built here (out of gh#2647's
+  // scope, a Phase-0 rule's own matcher precision).
+  fix(text, finding) {
+    const lines = text.split('\n');
+    const idx = finding.line - 1;
+    if (idx < 0 || idx >= lines.length) return text;
+    lines[idx] = lines[idx].replace(/--a-font(\s*[,)])/, '--a-font-family-ui$1');
+    return lines.join('\n');
+  },
+  fixtures: {
+    smelly: [':root { font-family: var(--a-font, sans-serif); }'],
+    clean: [':root { font-family: var(--a-font-family-ui, sans-serif); }'],
+  },
+});
+}
+
+{
+
+
+// gh#2492 Phase 1 — advisory gate: walks every component yaml's
+// `examples[].a2ui` JSON blocks and reports node ids that fail the
+// semantic-id grammar documented in
+// packages/plugins/adia-ui-forge/skills/primitive-authoring/references/
+// yaml-contract.md's `## examples: field` section (kebab-case, no
+// positional-abbreviation shape like k1/c2/q1, min 3 chars, unique within
+// its own example — do not restate the rule's rationale here, only its
+// shape). gh#2492 Phase 2's corpus-wide sweep will promote this rule's
+// severity to error once every yaml is renamed — do not flip early.
+
+// A bare 1-2 char id, or a short letter run immediately followed by digits
+// (positional-abbreviation shape: k1, k1v, c2, q1, hdr2). Intentionally
+// does NOT flag every short id — a single real word like `card`/`row` is
+// the documented root/wrapper exception.
+const POSITIONAL_RE = /^[a-z]{1,3}\d+[a-z]*$/;
+const KEBAB_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+/**
+ * Validate one example's flat id list against the grammar. Returns an array
+ * of { id, reason } violations.
+ */
+function checkExampleIds(ids) {
+  const violations = [];
+  const seen = new Map();
+  for (const id of ids) {
+    seen.set(id, (seen.get(id) ?? 0) + 1);
+  }
+  const handled = new Set();
+  for (const id of ids) {
+    if (typeof id !== 'string' || id.length === 0) continue;
+    if (handled.has(id)) continue;
+    if (seen.get(id) > 1) {
+      violations.push({ id, reason: 'duplicate-in-example' });
+      handled.add(id);
+      continue;
+    }
+    if (id.length <= 2) {
+      violations.push({ id, reason: 'too-short' });
+      handled.add(id);
+      continue;
+    }
+    if (POSITIONAL_RE.test(id)) {
+      violations.push({ id, reason: 'positional-pattern' });
+      handled.add(id);
+      continue;
+    }
+    if (!KEBAB_RE.test(id)) {
+      violations.push({ id, reason: 'not-kebab-case' });
+      handled.add(id);
+    }
+  }
+  return violations;
+}
+
+
+RULES.push({
+  id: 'EXAMPLE-ID-GRAMMAR',
+  severity: 'advisory',
+  scope: 'shared',
+  fileTypes: ['.yaml'],
+  match(text) {
+    const findings = [];
+    for (const block of extractYamlA2uiBlocks(text)) {
+      const ids = block.nodes
+        .filter((n) => n && typeof n === 'object')
+        .map((n) => n.id)
+        .filter((id) => typeof id === 'string');
+      for (const v of checkExampleIds(ids)) {
+        findings.push({
+          line: block.line,
+          snippet: `"${v.id}" — ${v.reason}`.slice(0, 90),
+          why: 'example node id fails the semantic-id grammar (kebab-case, no positional pattern like k1/c2, 3+ chars, unique within its example) — see yaml-contract.md',
+        });
+      }
+    }
+    return findings;
+  },
+});
+}
+
+{
+
+
+// No static `node:fs`/`node:path` import — this rule module is inlined
+// into a shared generated bank copied byte-for-byte to 4 destinations
+// (LLD-0016 §C5), one of which (anti-patterns.generated.js) is
+// browser-reachable and check:browser-safe forbids a top-level `node:*`
+// import there. process.getBuiltinModule() reaches the same builtins with
+// zero import statements — undefined in a browser, so the corpus walk
+// below fails soft (`[]`/`null`) instead of throwing there.
+function nodeFsPath() {
+  if (typeof process === 'undefined' || typeof process.getBuiltinModule !== 'function') return null;
+  return { fs: process.getBuiltinModule('node:fs'), path: process.getBuiltinModule('node:path') };
+}
+
+// gh#2540 — example-node prop-key contract (advisory). A hand-authored
+// `a2ui.examples` node can set a prop key the target component never
+// declares (`"text"` instead of the real `textContent`) and nothing else
+// catches it: the wire schema's `additionalProperties: true` accepts it,
+// the renderer's generic `#applyProps` loop hands it to
+// `applyResolvedProp` which just stamps a dead HTML attribute, and no
+// other build gate diffs a node's keys against the component's own prop
+// contract. This bug class has already bitten kbd, the shells slice
+// (#2504), and table (`rows` instead of `data`) — all silently. This rule
+// makes a new instance visible at lint time without blocking the build on
+// the (many) pre-existing instances the corpus already carries — those
+// stay advisory, not error, until a corpus-wide sweep clears them.
+//
+// Every node key is legal if it is one of:
+//   - a structural key: id, component, children, child, slot
+//   - a universal prop synthesized onto every component regardless of its
+//     own sidecar: slot, hidden, ariaLive (derive-genui-catalog.mjs's
+//     deriveProps()), plus traits (ADR-0097)
+//   - a prop the TARGET component's own yaml declares under `props:`
+//
+// The target component is resolved by the node's own `"component"` value
+// against every yaml SoT's own `component:` field (the same name an
+// example author writes — NOT the registry's canonical wire name). A node
+// whose `component` matches no yaml at all is a different bug class
+// (unresolvable component name) and is skipped here, not flagged.
+const STRUCTURAL_KEYS = new Set(['id', 'component', 'children', 'child', 'slot']);
+const UNIVERSAL_PROP_KEYS = new Set(['slot', 'hidden', 'ariaLive', 'traits']);
+
+/**
+ * Check one example's flat node array against the componentPropMap.
+ * Returns { id, component, key } findings for keys that are neither
+ * structural, universal, nor declared by the target component. A node
+ * whose component resolves to nothing in the map is skipped (different
+ * bug class).
+ */
+function checkExamplePropContract(nodes, componentPropMap) {
+  const findings = [];
+  if (!Array.isArray(nodes)) return findings;
+  for (const node of nodes) {
+    if (!node || typeof node !== 'object' || typeof node.component !== 'string') continue;
+    const declared = componentPropMap.get(node.component);
+    if (!declared) continue; // unresolvable component name — not this rule's concern
+    for (const key of Object.keys(node)) {
+      if (STRUCTURAL_KEYS.has(key)) continue;
+      if (UNIVERSAL_PROP_KEYS.has(key)) continue;
+      if (declared.has(key)) continue;
+      findings.push({ id: typeof node.id === 'string' ? node.id : '(no id)', component: node.component, key });
+    }
+  }
+  return findings;
+}
+
+// Same two SoT roots scripts/build/components.mjs (and check-genui-catalog.mjs)
+// scan (ADR-0012: primitives + composite modules share one yaml contract).
+const CORPUS_ROOTS = ['packages/web-components/components', 'packages/web-modules'];
+
+function findRepoRoot(fs, path, filePath) {
+  let dir = path.isAbsolute(filePath) ? path.dirname(filePath) : path.resolve(process.cwd(), path.dirname(filePath || '.'));
+  for (let i = 0; i < 15; i += 1) {
+    if (CORPUS_ROOTS.every((r) => fs.existsSync(path.join(dir, r)))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+function walkYamlFiles(fs, path, dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...walkYamlFiles(fs, path, full));
+    else if (e.isFile() && e.name.endsWith('.yaml')) out.push(full);
+  }
+  return out;
+}
+
+// Module-level cache (this rule module is a process-lifetime singleton):
+// the corpus componentPropMap is read from disk once per repo root, not
+// once per linted file — building it fresh for every one of ~190 yaml
+// files in a `npm run lint` pass would be O(n^2) disk IO for no benefit.
+let cachedRoot;
+let cachedMap;
+function corpusPropMap(filePath) {
+  const builtins = nodeFsPath();
+  if (!builtins) return null; // browser/non-Node runtime — fail soft
+  const { fs, path } = builtins;
+  const root = findRepoRoot(fs, path, filePath);
+  if (!root) return null; // no repo root found (e.g. a synthetic/fixture path) — fail soft
+  if (cachedRoot === root && cachedMap) return cachedMap;
+  const files = CORPUS_ROOTS.flatMap((r) => walkYamlFiles(fs, path, path.join(root, r)));
+  const map = new Map();
+  for (const f of files) {
+    let text;
+    try {
+      text = fs.readFileSync(f, 'utf8');
+    } catch {
+      continue;
+    }
+    const { component, propKeys } = extractYamlComponentPropKeys(text);
+    if (component) map.set(component, propKeys);
+  }
+  cachedRoot = root;
+  cachedMap = map;
+  return map;
+}
+
+
+RULES.push({
+  id: 'EXAMPLE-PROP-CONTRACT',
+  severity: 'advisory',
+  scope: 'shared',
+  fileTypes: ['.yaml'],
+  match(text, path) {
+    const map = corpusPropMap(path || '');
+    if (!map) return [];
+    const findings = [];
+    for (const block of extractYamlA2uiBlocks(text)) {
+      for (const hit of checkExamplePropContract(block.nodes, map)) {
+        findings.push({
+          line: block.line,
+          snippet: `node "${hit.id}" (${hit.component}) sets unknown key "${hit.key}"`.slice(0, 90),
+          why: 'example sets a prop key its target component does not declare (structural/universal/component-own props only) — fix the source yaml and re-run npm run build:components',
+        });
+      }
+    }
+    return findings;
+  },
+});
+}
+
+{
+
+
+
+RULES.push({
+  id: 'LEGACY-SHELL',
+  severity: 'error',
+  scope: 'shared',
+  fileTypes: [],
+  match(text, path) {
+    const out = [];
+    for (const { lineNo, raw, stripped } of stripCommentLines(text, ext(path))) {
+      if (!stripped.trim()) continue;
+      if (RE.LEGACY_SHELL.test(stripped)) {
+        out.push({
+          line: lineNo,
+          snippet: raw.trim().slice(0, 90),
+          why: 'retired shell shape (ADR-0024, v0.4.0) — use the bespoke tag (chat-thread / chat-composer / chat-empty · admin-sidebar / admin-command · editor-canvas · pane-ui)',
+        });
+      }
+    }
+    return out;
+  },
+});
+}
+
+{
+
+
+// `<!-- -->` can span many lines; a native tag *mentioned* inside one
+// (prose, a commented-out example) isn't a live violation. Blank the
+// comment body char-for-char (newlines kept, so line numbers survive) —
+// stripCommentLines only understands `/* */` and `//`, not HTML comments.
+function blankHtmlComments(text) {
+  let out = '';
+  let i = 0;
+  while (i < text.length) {
+    const start = text.indexOf('<!--', i);
+    if (start === -1) {
+      out += text.slice(i);
+      break;
+    }
+    out += text.slice(i, start);
+    const close = text.indexOf('-->', start + 4);
+    const end = close === -1 ? text.length : close + 3;
+    for (let j = start; j < end; j += 1) out += text[j] === '\n' ? '\n' : ' ';
+    i = end;
+  }
+  return out;
+}
+
+// a bare `data-native-ok=""` opts out of nothing — require a real reason,
+// mirroring how `SUPPRESS_RE`/`suppressionFor` treat a reason-less disable
+// elsewhere in this engine.
+const NATIVE_OK = /data-native-ok\s*=\s*(['"])((?:(?!\1).)*)\1/;
+function hasNativeOk(line) {
+  const m = NATIVE_OK.exec(line);
+  return Boolean(m && m[2].trim());
+}
+
+
+RULES.push({
+  id: 'NATIVE-PRIMITIVE',
+  severity: 'error',
+  scope: 'shared',
+  fileTypes: MARKUP_EXT,
+  match(text, path) {
+    const out = [];
+    const blanked = blankHtmlComments(text);
+    const rawLines = text.split('\n');
+    let lineNo = 0;
+    for (const { raw, stripped } of stripCommentLines(blanked, ext(path))) {
+      lineNo += 1;
+      const s = stripped.trim().slice(0, 90);
+      if (!s) continue;
+      if (stripped.includes('slot=')) continue;
+      if (s.startsWith('//') || s.startsWith('*') || s.startsWith('/*')) continue;
+      if (hasNativeOk(rawLines[lineNo - 1] || raw)) continue;
+      if (RE.NATIVE_PRIMITIVE.test(stripped)) {
+        out.push({
+          line: lineNo,
+          snippet: (rawLines[lineNo - 1] || raw).trim().slice(0, 90),
+          why: 'a composite must build from *-ui primitives (button-ui / input-ui / select-ui / textarea-ui / modal-ui) — raw natives skip focus rings, theming, and form association; a deliberate slotted trigger (with slot=) is the exception, and a genuinely native surface can opt out with data-native-ok="<reason>"',
+        });
+      }
+    }
+    return out;
+  },
+});
+}
+
+{
+
+
+// Parity with the two retired scripts: forge-lint recognized only
+// `forge-lint: foundation`, adia-lint only `adia-lint: foundation` — never
+// either tag under the other script. Since this rule is shared, the active
+// caller scope (passed by the engine's `opts.scopes`) picks which single
+// tag applies; a run with both scopes active (not a real CLI shape today)
+// accepts either, the closest available reading.
+function optInTagsFor(scopes) {
+  if (scopes && scopes.includes('forge-only') && !scopes.includes('consumer-only')) return ['forge-lint'];
+  if (scopes && scopes.includes('consumer-only') && !scopes.includes('forge-only')) return ['adia-lint'];
+  return ['forge-lint', 'adia-lint'];
+}
+
+
+RULES.push({
+  id: 'RAW-COLOR',
+  severity: 'error',
+  scope: 'shared',
+  fileTypes: STYLE_EXT,
+  match(text, path, opts = {}) {
+    const isTokenish = optInTagsFor(opts.scopes).some((tag) => isFoundationCss(path, text, tag));
+    if (isTokenish) return [];
+    const out = [];
+    for (const { lineNo, raw, stripped } of stripCommentLines(text, ext(path))) {
+      if (!stripped.trim()) continue;
+      for (const decl of stripped.split(';')) {
+        const d = decl.trim();
+        if (!d || d.startsWith('//') || d.startsWith('/*') || d.startsWith('*')) continue;
+        if (decl.includes('var(') || decl.includes('light-dark(')) continue;
+        if (RE.HEXCOLOR.test(decl) || RE.FUNCCOLOR.test(decl)) {
+          out.push({
+            line: lineNo,
+            snippet: raw.trim().slice(0, 90),
+            why: 'component CSS is token-only — replace the literal with var(--a-*) (foundation/token files excepted)',
+          });
+          break;
+        }
+      }
+    }
+    return out;
+  },
+});
+}
+
+{
+
+
+// Parity with the two retired scripts: forge-lint recognized only
+// `forge-lint: foundation`, adia-lint only `adia-lint: foundation` — never
+// either tag under the other script. Since this rule is shared, the active
+// caller scope (passed by the engine's `opts.scopes`) picks which single
+// tag applies; a run with both scopes active (not a real CLI shape today)
+// accepts either, the closest available reading.
+function optInTagsFor(scopes) {
+  if (scopes && scopes.includes('forge-only') && !scopes.includes('consumer-only')) return ['forge-lint'];
+  if (scopes && scopes.includes('consumer-only') && !scopes.includes('forge-only')) return ['adia-lint'];
+  return ['forge-lint', 'adia-lint'];
+}
+
+
+RULES.push({
+  id: 'RAW-PX',
+  severity: 'warn',
+  scope: 'shared',
+  fileTypes: STYLE_EXT,
+  match(text, path, opts = {}) {
+    const isTokenish = optInTagsFor(opts.scopes).some((tag) => isFoundationCss(path, text, tag));
+    if (isTokenish) return [];
+    const out = [];
+    for (const { lineNo, raw, stripped } of stripCommentLines(text, ext(path))) {
+      if (!stripped.trim()) continue;
+      if (stripped.trimStart().startsWith('@')) continue; // skip @media/@container/@scope
+      for (const decl of stripped.split(';')) {
+        if (decl.includes('/*')) continue; // author-annotated carve-out
+        const matches = [...decl.matchAll(new RegExp(RE.PX_GE.source, 'g'))];
+        if (matches.some((m) => Number(m[1]) >= 3)) {
+          out.push({
+            line: lineNo,
+            snippet: raw.trim().slice(0, 90),
+            why: 'no raw px >= 3 in component CSS — use var(--a-space-*); 1-2px hairlines exempt, annotate a deliberate exception with a comment',
+          });
+          break;
+        }
+      }
+    }
+    return out;
+  },
+});
+}
+
+{
+
+
+
+RULES.push({
+  id: 'SCOPE-EXTENT',
+  severity: 'error',
+  scope: 'shared',
+  fileTypes: STYLE_EXT,
+  match(text) {
+    const out = [];
+    const re = new RegExp(RE.SCOPE_EXTENT.source, 'gs');
+    let m;
+    while ((m = re.exec(text))) {
+      out.push({
+        line: lineOf(text, m.index),
+        snippet: ':scope { … width/height … }',
+        why: "a primitive is size-agnostic — let the consumer own width/height; don't set extent on :scope",
+      });
+    }
+    return out;
+  },
+});
+}
+
+{
+
+
+
+RULES.push({
+  id: 'SHADOW-DOM',
+  severity: 'error',
+  scope: 'shared',
+  fileTypes: [],
+  match(text, path) {
+    const out = [];
+    for (const { lineNo, raw, stripped } of stripCommentLines(text, ext(path))) {
+      if (!stripped.trim()) continue;
+      if (stripped.includes('attachShadow')) {
+        out.push({
+          line: lineNo,
+          snippet: raw.trim().slice(0, 90),
+          why: 'adia-ui is light-DOM — never attachShadow; it breaks the token cascade + @scope',
+        });
+      }
+    }
+    return out;
+  },
+});
+}
+
+{
+
+
+
+RULES.push({
+  id: 'SLOTTED',
+  severity: 'error',
+  scope: 'shared',
+  fileTypes: [],
+  match(text, path) {
+    const out = [];
+    const marker = '::' + 'slotted(';
+    for (const { lineNo, raw, stripped } of stripCommentLines(text, ext(path))) {
+      if (!stripped.trim()) continue;
+      if (stripped.includes(marker)) {
+        out.push({
+          line: lineNo,
+          snippet: raw.trim().slice(0, 90),
+          why: 'light DOM has no ::slotted — style projected content via :scope > [slot="x"]',
+        });
+      }
+    }
+    return out;
+  },
+});
+}
+
+{
+
+
+// gh#2507 — the v1.0 renderer has no `attrs`/`slots` handling and no
+// `content` prop on any real component (`content` only ever appears as a
+// SLOT NAME, targeted via `"slot": "content"` — never as a node's own
+// literal key). A yaml example authored in the pre-v1.0 dialect wraps
+// props in an `attrs: {}` object, wraps children position in a `slots: {}`
+// map, and stuffs text into a bare `content` key instead of
+// `text`/`textContent`. The renderer silently drops all three.
+const STALE_DIALECT_KEYS = ['attrs', 'slots', 'content'];
+
+// Walks the parsed a2ui JSON (an array of flat node objects) and reports
+// every node that carries one of the stale wrapper keys as its OWN
+// property. Recurses into any nested object/array values too, in case an
+// example nests node-shaped objects directly rather than only via the
+// flat id-array convention.
+function findStaleDialectNodes(value, path_ = '$') {
+  const findings = [];
+  if (Array.isArray(value)) {
+    value.forEach((v, i) => findings.push(...findStaleDialectNodes(v, `${path_}[${i}]`)));
+    return findings;
+  }
+  if (value && typeof value === 'object') {
+    const hit = STALE_DIALECT_KEYS.filter((k) => Object.prototype.hasOwnProperty.call(value, k));
+    if (hit.length > 0) {
+      const id = typeof value.id === 'string' ? value.id : '(no id)';
+      findings.push({ id, path: path_, keys: hit });
+    }
+    for (const [k, v] of Object.entries(value)) {
+      findings.push(...findStaleDialectNodes(v, `${path_}.${k}`));
+    }
+  }
+  return findings;
+}
+
+
+RULES.push({
+  id: 'STALE-DIALECT',
+  severity: 'error',
+  scope: 'shared',
+  fileTypes: ['.yaml'],
+  match(text) {
+    const findings = [];
+    for (const block of extractYamlA2uiBlocks(text)) {
+      for (const hit of findStaleDialectNodes(block.nodes)) {
+        findings.push({
+          line: block.line,
+          snippet: `node "${hit.id}" at ${hit.path} carries stale key(s): ${hit.keys.join(', ')}`.slice(0, 90),
+          why: 'pre-v1.0 dialect (attrs:{} / slots:{} / bare content key) — rewrite to the flat v1.0 wire shape: props at top level, text/textContent per the component\'s own yaml, children arrays with a "slot" attribute per child',
+        });
+      }
+    }
+    return findings;
+  },
+});
+}
+
+
+export { CODE_EXT, STYLE_EXT, MARKUP_EXT, LINT_EXT, ext, isFoundationCss, stripCommentLines, lineOf, suppressionFor, RE, declarations, makeLinter, render, RULES };