@cosmicdrift/kumiko-guards 0.1.0

package/src/guard-primitives-discipline.ts

@@ -0,0 +1,330 @@
+#!/usr/bin/env bun
+/**
+ * Guard: enforces that app-/feature-web code uses UI building blocks from
+ * the framework primitives, not hand-rolled Tailwind on raw HTML tags.
+ *
+ * Why: hand-rolled Tailwind in `web/` folders costs twice:
+ *   1. Style drift — every renderer/theme update then has to be re-applied
+ *      to each hand-tailwound screen individually.
+ *   2. Multi-platform lock-out — native (renderer-native) has no
+ *      `<table>`, `<form>`, `<button>`. Direct DOM tags bind the code to
+ *      web. Framework primitives (`<DataTable>`, `<Form>`, `<Button>`) are
+ *      contractually platform-neutral.
+ *
+ * Forbidden in app-/feature-web code:
+ *
+ *   <table>/<thead>/<tbody>/<tr>/<td>/<th>  →  <DataTable>
+ *   <form>                                  →  <Form>
+ *   <input>                                 →  <Input> (in <Field>)
+ *   <button>                                →  <Button>
+ *   <select>                                →  <ComboboxInput>
+ *   <textarea>                              →  <Input kind="textarea">
+ *   <dialog>                                →  <DefaultDialog>
+ *   alert() / window.alert()               →  <DefaultDialog> from @cosmicdrift/kumiko-renderer-web
+ *   className "bg-card" (hand-rolled card) →  <Card> (slots/options)
+ *
+ * Allowed: containers and text — `<div>`, `<span>`, `<section>`,
+ *   `<header>`, `<main>`, `<nav>`, `<aside>`, `<article>`,
+ *   `<h1>`-`<h6>`, `<p>`, `<ul>`, `<ol>`, `<li>`, `<a>`, `<img>`,
+ *   `<svg>`, `<label>`, `<small>`, `<strong>`, `<em>`, `<br>`, `<hr>`,
+ *   `<pre>`, `<code>`.
+ *
+ * `__tests__` folders are excluded. Per-line override:
+ *   `// kumiko-lint-ignore primitives-discipline <reason>`
+ *   (on the same line or the line directly above).
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
+import { isFlatSrcLayout, type RepoRoot, sourceRootDirs } from "./_lib/roots";
+
+const FORBIDDEN_TAGS: ReadonlyArray<{
+  readonly tag: string;
+  readonly counterpart: string;
+}> = [
+  { tag: "table", counterpart: "<DataTable>" },
+  { tag: "thead", counterpart: "<DataTable>" },
+  { tag: "tbody", counterpart: "<DataTable>" },
+  { tag: "tr", counterpart: "<DataTable>" },
+  { tag: "td", counterpart: "<DataTable>" },
+  { tag: "th", counterpart: "<DataTable>" },
+  { tag: "form", counterpart: "<Form>" },
+  { tag: "input", counterpart: "<Input> (über <Field>)" },
+  { tag: "button", counterpart: "<Button>" },
+  { tag: "select", counterpart: "<ComboboxInput>" },
+  { tag: "textarea", counterpart: '<Input kind="textarea">' },
+  { tag: "dialog", counterpart: "<DefaultDialog>" },
+];
+
+const FORBIDDEN_CALLS: ReadonlyArray<{
+  readonly call: string;
+  readonly counterpart: string;
+}> = [{ call: "alert", counterpart: "<DefaultDialog> aus @cosmicdrift/kumiko-renderer-web" }];
+
+// Forbidden className tokens: an allowed tag (`<div>`), but the class gives
+// away hand-rolled primitive chrome. `bg-card` is the dedicated card-surface
+// token — seeing it in a className means a hand-rebuilt card instead of
+// `<Card>` (slots/options). Exactly the copy-paste drift the Card primitive
+// is meant to eliminate. Real exceptions (foundation token swatches,
+// navigation surfaces) carry `// kumiko-lint-ignore primitives-discipline`.
+const FORBIDDEN_CLASSES: ReadonlyArray<{
+  readonly token: string;
+  readonly counterpart: string;
+}> = [{ token: "bg-card", counterpart: "<Card>" }];
+
+const IGNORE_TAG = "kumiko-lint-ignore primitives-discipline";
+
+export type ScopeKind = "bundled-features" | "samples" | "app";
+
+type ScanScope = {
+  readonly kind: ScopeKind;
+  readonly root: string;
+};
+
+// Framework checkout enforces bundled-features + samples. App-repo checkout
+// scans the app's web/ screens — primitives-discipline as a ratchet per app
+// repo (infra#224). Every other resolved repo (enterprise, platform, ...)
+// scans alongside the others in one run — flatMap all of them instead of
+// cascading, which would silently skip every root after the first, exactly
+// the silent-skip this guard fixes.
+function resolveScopes(roots: readonly RepoRoot[]): ScanScope[] {
+  const frameworkRoot = roots.find((r) => r.kind === "framework");
+  if (frameworkRoot) {
+    return [
+      {
+        kind: "bundled-features",
+        root: path.join(frameworkRoot.absPath, "packages/bundled-features/src"),
+      },
+      { kind: "samples", root: path.join(frameworkRoot.absPath, "samples") },
+    ];
+  }
+  const appRoot = roots.find((r) => r.kind === "app" && isFlatSrcLayout(r));
+  if (appRoot) {
+    return [{ kind: "app", root: path.join(appRoot.absPath, "src") }];
+  }
+  const otherRoots = roots.filter((r) => r.kind !== "framework" && !isFlatSrcLayout(r));
+  return otherRoots.flatMap(sourceRootDirs).map((root) => ({ kind: "app" as const, root }));
+}
+
+function resolveRoot(roots: readonly RepoRoot[]): string {
+  const frameworkRoot = roots.find((r) => r.kind === "framework");
+  if (frameworkRoot) return frameworkRoot.absPath;
+  const appRoot = roots.find((r) => r.kind === "app" && isFlatSrcLayout(r));
+  if (appRoot) return appRoot.absPath;
+  const otherRoots = roots.filter((r) => r.kind !== "framework" && !isFlatSrcLayout(r));
+  return otherRoots[0]?.absPath ?? process.cwd();
+}
+
+type Violation = {
+  readonly file: string;
+  readonly line: number;
+  readonly kind: "tag" | "call" | "class";
+  readonly tag: string;
+  readonly counterpart: string;
+  readonly excerpt: string;
+  readonly scope: ScopeKind;
+};
+
+function isWebFile(absPath: string, scopeRoot: string): boolean {
+  // Only .tsx files under a `web/` or `public/` path segment (prevents
+  // scanning random .tsx in screens/ or feature roots — those are schema
+  // definitions, not web code).
+  if (!absPath.endsWith(".tsx")) return false;
+  const rel = path.relative(scopeRoot, absPath);
+  const parts = rel.split(path.sep);
+  return parts.includes("web") || parts.includes("public");
+}
+
+function walk(dir: string, out: string[]): void {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "__tests__") continue;
+      if (entry.name === "node_modules") continue;
+      if (entry.name === "dist") continue;
+      walk(full, out);
+      continue;
+    }
+    if (entry.isFile()) out.push(full);
+  }
+}
+
+function buildTagPattern(tag: string): RegExp {
+  // Match `<tag` at the JSX opening: after whitespace, a paren, or >.
+  // Negative lookahead `[a-zA-Z0-9-]` so `<input` doesn't match `<inputfoo`.
+  // Doesn't match the closing tag (`</tag>`) — that would be redundant.
+  return new RegExp(`(^|[\\s(>{,;])<${tag}(?![a-zA-Z0-9-])`, "u");
+}
+
+const TAG_PATTERNS = FORBIDDEN_TAGS.map((t) => ({ ...t, pattern: buildTagPattern(t.tag) }));
+
+// Match `alert(` and `window.alert(` — the native browser dialog is forbidden.
+const CALL_PATTERNS = FORBIDDEN_CALLS.map((c) => ({
+  ...c,
+  // Lookbehind instead of \b: \b also matches after a dot — `toast.alert(`
+  // would otherwise be a hit. window.alert( stays deliberately forbidden.
+  pattern: new RegExp(`(?<![.\\w$])(?:window\\.)?${c.call}\\s*\\(`, "u"),
+}));
+
+// `\b` alone isn't enough: `-` is itself a non-word character, so
+// `\bbg-card\b` also matches as a substring in a longer hyphen-prefixed
+// token (e.g. a hypothetical `my-bg-card`). A lookaround against word
+// characters AND `-` on both sides keeps `bg-card` exact, without losing
+// `hover:bg-card`/`bg-card/40`.
+const CLASS_PATTERNS = FORBIDDEN_CLASSES.map((c) => ({
+  ...c,
+  pattern: new RegExp(`(?<![\\w-])${c.token}(?![\\w-])`, "u"),
+}));
+
+function hasIgnore(currentLine: string, prevLine: string): boolean {
+  return currentLine.includes(IGNORE_TAG) || prevLine.includes(IGNORE_TAG);
+}
+
+export function checkFile(
+  file: string,
+  scope: ScopeKind,
+  root: string = process.cwd(),
+): Violation[] {
+  const text = fs.readFileSync(file, "utf-8");
+  const lines = text.split("\n");
+  const violations: Violation[] = [];
+  let inBlockComment = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const trimmed = line.trim();
+    // Block-comment tracking (heuristic): `/* ... */` across multiple lines.
+    // Single-line `//` and `*` (inside /* */) are skipped.
+    if (inBlockComment) {
+      if (trimmed.includes("*/")) inBlockComment = false;
+      continue;
+    }
+    if (trimmed.startsWith("/*") && !trimmed.includes("*/")) {
+      inBlockComment = true;
+      continue;
+    }
+    if (trimmed.startsWith("//") || trimmed.startsWith("*")) continue;
+    // Strip trailing inline comments — `foo(); // alert() would be wrong`
+    // must not match. (?<!:) leaves URLs (https://…) in strings alone;
+    // string contents themselves stay an accepted heuristic gap.
+    const codeOnly = line.replace(/(?<!:)\/\/.*$/u, "");
+
+    const prev = i > 0 ? (lines[i - 1] ?? "") : "";
+    if (hasIgnore(line, prev)) continue;
+
+    for (const { tag, counterpart, pattern } of TAG_PATTERNS) {
+      if (pattern.test(codeOnly)) {
+        violations.push({
+          file: path.relative(root, file),
+          line: i + 1,
+          kind: "tag",
+          tag,
+          counterpart,
+          excerpt: trimmed.length > 120 ? `${trimmed.slice(0, 117)}...` : trimmed,
+          scope,
+        });
+      }
+    }
+    for (const { call, counterpart, pattern } of CALL_PATTERNS) {
+      if (pattern.test(codeOnly)) {
+        violations.push({
+          file: path.relative(root, file),
+          line: i + 1,
+          kind: "call",
+          tag: call,
+          counterpart,
+          excerpt: trimmed.length > 120 ? `${trimmed.slice(0, 117)}...` : trimmed,
+          scope,
+        });
+      }
+    }
+    for (const { token, counterpart, pattern } of CLASS_PATTERNS) {
+      if (pattern.test(codeOnly)) {
+        violations.push({
+          file: path.relative(root, file),
+          line: i + 1,
+          kind: "class",
+          tag: token,
+          counterpart,
+          excerpt: trimmed.length > 120 ? `${trimmed.slice(0, 117)}...` : trimmed,
+          scope,
+        });
+      }
+    }
+  }
+  return violations;
+}
+
+function violationMessage(v: Violation): string {
+  const label =
+    v.kind === "call" ? `${v.tag}()` : v.kind === "class" ? `class "${v.tag}"` : `<${v.tag}>`;
+  return `${label}  →  ${v.counterpart}  |  ${v.excerpt}`;
+}
+
+const HINT =
+  "Migration: usePrimitives() in eine Custom-Screen-Komponente, oder schema-driven via EntityListScreenDefinition / EntityEditScreenDefinition wo möglich. Override pro Zeile: // kumiko-lint-ignore primitives-discipline <reason>";
+
+export const check: RepoCheck = {
+  name: "Primitives-Discipline Guard",
+  hint: HINT,
+  run(roots) {
+    const scopes = resolveScopes(roots);
+    if (scopes.length === 0) {
+      // infra exits 1 here ("weder FRAMEWORK_ROOT, APP_ROOT noch ein anderer
+      // Repo-Root aufgelöst") — the vacuity floor below reproduces that.
+      return { violations: [], matchedFiles: 0, notApplicable: false };
+    }
+    const root = resolveRoot(roots);
+    // Pre-filter count (every file walk() found, before the web/-segment
+    // filter): an app repo whose screens are schema-driven with zero
+    // web/*.tsx (phronexsis before its first screen) must not be flagged as
+    // vacuous just because isWebFile() legitimately matched nothing.
+    let walkedFiles = 0;
+    const violations: { file: string; line: number; message: string }[] = [];
+    const warnings: { file: string; line: number; message: string }[] = [];
+
+    for (const scope of scopes) {
+      const files: string[] = [];
+      walk(scope.root, files);
+      walkedFiles += files.length;
+      const webFiles = files.filter((f) => isWebFile(f, scope.root));
+      for (const file of webFiles) {
+        const target = scope.kind === "samples" ? warnings : violations;
+        for (const v of checkFile(file, scope.kind, root)) {
+          target.push({ file: v.file, line: v.line, message: violationMessage(v) });
+        }
+      }
+    }
+
+    return {
+      violations,
+      warnings: warnings.length > 0 ? warnings : undefined,
+      matchedFiles: walkedFiles,
+      notApplicable: false,
+    };
+  },
+};
+
+if (import.meta.main) {
+  // --strict also blocks the samples scope (infra's `--strict` mode);
+  // --strict-bundled is accepted for CLI compatibility — bundled-features is
+  // already always-blocking here (what framework CI ran as --strict-bundled).
+  const strict = process.argv.includes("--strict");
+  const effectiveCheck: RepoCheck = strict
+    ? {
+        name: check.name,
+        hint: check.hint,
+        async run(roots) {
+          const outcome = await check.run(roots);
+          return {
+            violations: [...outcome.violations, ...(outcome.warnings ?? [])],
+            matchedFiles: outcome.matchedFiles,
+            notApplicable: outcome.notApplicable,
+          };
+        },
+      }
+    : check;
+  const failed = reportResults(await runRepoChecks([effectiveCheck]));
+  process.exit(failed > 0 ? 1 : 0);
+}

package/src/guard-raw-classname.ts

@@ -0,0 +1,111 @@
+#!/usr/bin/env bun
+// Design comes from widgets/theme tokens, not raw Tailwind in app code.
+// Flags design-carrying classes in app `className`: default-palette colors
+// (bg-red-500), arbitrary color values (bg-[#fff], text-[rgb(...)]), shadow-*.
+// Layout utilities (flex/grid/gap/p-/m-/w-) and token classes
+// (bg-primary, text-status-ok, …) stay allowed.
+//
+// Part of App-Mounting 2.0 (infra#208). Enabled per app repo in the
+// respective migration PR (ui-guards input in _app-test.yml).
+
+import { type JsxAttribute, type SourceFile, SyntaxKind } from "ts-morph";
+import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
+import { hasIgnoreTag } from "./_lib/ignore-tag";
+
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["tsx"],
+  frameworkWithin: ["packages/bundled-features/src/**"],
+};
+const EXCLUDE = /(__tests__|\.test\.tsx?$|\.integration\.tsx?$|\.d\.ts$)/;
+const IGNORE_TAG = "kumiko-lint-ignore raw-classname";
+
+const PALETTE =
+  "red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|zinc|neutral|stone";
+const COLOR_PREFIX =
+  "bg|text|border|ring|fill|stroke|from|via|to|outline|decoration|divide|accent|caret";
+
+const PALETTE_CLASS = new RegExp(`^(${COLOR_PREFIX})-(${PALETTE})-\\d+(/\\d+)?$`);
+const ARBITRARY_COLOR = new RegExp(`^(${COLOR_PREFIX})-\\[(#|rgb|hsl|oklch|color-mix)`);
+// Only shadows — `rounded-*` was included initially, but the evidence
+// across studio/publicstatus/money-horse shows: radius hits are
+// chips/pills/small surfaces, not design drift (that comes via
+// colors/shadows). 41 of 44 mh hits were rounded noise.
+const CHROME_CLASS = /^shadow(-.+)?$/;
+
+// Strip modifier prefixes (hover:, dark:, sm:, group-open:, …) — the base
+// class is what gets checked.
+function baseClass(token: string): string {
+  const idx = token.lastIndexOf(":");
+  return idx === -1 ? token : token.slice(idx + 1);
+}
+
+function offendingTokens(text: string): string[] {
+  return text
+    .split(/\s+/)
+    .filter((t) => t.length > 0)
+    .map(baseClass)
+    .filter((t) => PALETTE_CLASS.test(t) || ARBITRARY_COLOR.test(t) || CHROME_CLASS.test(t));
+}
+
+function classNameStrings(attr: JsxAttribute): { text: string; line: number }[] {
+  const init = attr.getInitializer();
+  if (init === undefined) return [];
+  if (init.getKind() === SyntaxKind.StringLiteral) {
+    return [
+      {
+        text: init.asKindOrThrow(SyntaxKind.StringLiteral).getLiteralText(),
+        line: init.getStartLineNumber(),
+      },
+    ];
+  }
+  // Expression: collect every string/template component (covers
+  // cn("…", cond && "…") and template literals).
+  const parts: { text: string; line: number }[] = [];
+  for (const s of init.getDescendantsOfKind(SyntaxKind.StringLiteral)) {
+    parts.push({ text: s.getLiteralText(), line: s.getStartLineNumber() });
+  }
+  for (const s of init.getDescendantsOfKind(SyntaxKind.NoSubstitutionTemplateLiteral)) {
+    parts.push({ text: s.getLiteralText(), line: s.getStartLineNumber() });
+  }
+  for (const kind of [
+    SyntaxKind.TemplateHead,
+    SyntaxKind.TemplateMiddle,
+    SyntaxKind.TemplateTail,
+  ]) {
+    for (const s of init.getDescendantsOfKind(kind)) {
+      parts.push({ text: s.getText().replace(/^[`}]|[`$]{?$/g, ""), line: s.getStartLineNumber() });
+    }
+  }
+  return parts;
+}
+
+export const guard: AstGuard = {
+  name: "Raw-ClassName Guard (App-Repos)",
+  scan: SCAN,
+  hint:
+    "Design-tragende Klassen gehören in Widgets/Theme-Tokens (@cosmicdrift/kumiko-renderer-web widgets/, --color-status-*). " +
+    `Begründete Ausnahme: // ${IGNORE_TAG} <Grund>`,
+  run(files: readonly SourceFile[]) {
+    const violations: GuardViolation[] = [];
+    for (const sf of files) {
+      if (EXCLUDE.test(sf.getFilePath())) continue;
+      for (const attr of sf.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
+        if (attr.getNameNode().getText() !== "className") continue;
+        if (hasIgnoreTag(attr, IGNORE_TAG)) continue;
+        for (const part of classNameStrings(attr)) {
+          const bad = offendingTokens(part.text);
+          if (bad.length === 0) continue;
+          violations.push({
+            file: sf.getFilePath(),
+            line: part.line,
+            message: `design-tragende Tailwind-Klassen in App-Code: ${bad.join(", ")}`,
+          });
+        }
+      }
+    }
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

package/src/guard-raw-interactive-elements.ts

@@ -0,0 +1,154 @@
+#!/usr/bin/env bun
+/**
+ * Guard: raw interactive HTML elements in feature UI. <a>, <details> and
+ * <summary> each have a framework replacement (usePrimitives().Link,
+ * CollapsibleSection from @cosmicdrift/kumiko-renderer-web) but nothing was
+ * checking for them — turn-cards.tsx/agent-layer.tsx (raw <details>/<summary>)
+ * and agent-settings.tsx (raw <a href>) shipped past CI in kumiko-enterprise.
+ *
+ * <button>/<input>/<select>/<textarea>/<dialog>/<form> are deliberately NOT
+ * in this guard: <button>/<input>/<select>/<textarea>/<dialog> are already
+ * enforced by guard-primitives-discipline.ts (its own CI step, not this
+ * bundle), and <form> is a documented exception (PR #488, agent-layer.tsx:71
+ * uses a native <form onSubmit> on purpose) — adding either back here would
+ * duplicate or contradict an existing rule.
+ *
+ * Only fires when the file demonstrably has primitives access (same gate as
+ * guard-no-custom-primitives's raw-form-html rule) — proof the replacement
+ * was reachable, not just a tag ban on files outside the primitives world.
+ *
+ * Baseline-regression guard like guard-tailwind-scan-surface.ts: pins the
+ * currently-known violation count per file. Reductions are allowed but
+ * don't auto-update the baseline. Without a baseline file the guard stays
+ * warning-only (bootstrap: run `--write-baseline` once).
+ *
+ * Usage:
+ *   bun guards/guard-raw-interactive-elements.ts                  # compare against baseline
+ *   bun guards/guard-raw-interactive-elements.ts --write-baseline # (re)write the baseline
+ *   bun guards/guard-raw-interactive-elements.ts --no-baseline    # skip the comparison
+ */
+
+import * as path from "node:path";
+import { type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  type AstGuard,
+  baselineRatchet,
+  buildSharedProject,
+  filesForGuard,
+  type GuardOutcome,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
+import { hasIgnoreTag } from "./_lib/ignore-tag";
+import { hasPrimitivesAccess } from "./_lib/primitives-access";
+
+const ROOT = process.cwd();
+
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["tsx"],
+  frameworkWithin: ["packages/bundled-features/src/**"],
+};
+const EXCLUDE = /(__tests__|\.test\.tsx?$|\.integration\.tsx?$|\.d\.ts$)/;
+const IGNORE_TAG = "kumiko-lint-ignore raw-interactive-elements";
+
+type BannedTag = "a" | "details" | "summary";
+
+const REPLACEMENT: Readonly<Record<BannedTag, string>> = {
+  a: "usePrimitives().Link",
+  details: "CollapsibleSection (@cosmicdrift/kumiko-renderer-web)",
+  summary: "CollapsibleSection (@cosmicdrift/kumiko-renderer-web)",
+};
+
+function isBannedTag(tag: string): tag is BannedTag {
+  return Object.hasOwn(REPLACEMENT, tag);
+}
+
+export type Finding = {
+  readonly file: string;
+  readonly line: number;
+  readonly tag: BannedTag;
+};
+
+function scan(files: readonly SourceFile[]): Finding[] {
+  const findings: Finding[] = [];
+  for (const sf of files) {
+    if (EXCLUDE.test(sf.getFilePath())) continue;
+    if (!hasPrimitivesAccess(sf)) continue;
+    const elements = [
+      ...sf.getDescendantsOfKind(SyntaxKind.JsxOpeningElement),
+      ...sf.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement),
+    ];
+    for (const el of elements) {
+      const tag = el.getTagNameNode().getText();
+      if (!isBannedTag(tag)) continue;
+      if (hasIgnoreTag(el, IGNORE_TAG)) continue;
+      const file = path.relative(ROOT, sf.getFilePath());
+      const line = el.getStartLineNumber();
+      findings.push({ file, line, tag });
+      console.warn(
+        `  [raw-interactive-elements WARN] ${file}:${line}  raw <${tag}> — use ${REPLACEMENT[tag]}`,
+      );
+    }
+  }
+  return findings;
+}
+
+export function baselineCounts(findings: readonly Finding[]): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const f of findings) counts[f.file] = (counts[f.file] ?? 0) + 1;
+  return counts;
+}
+
+const BASELINE_FILE = ".kumiko-raw-interactive-elements-baseline.json";
+const rawInteractiveElementsBaseline = baselineRatchet({
+  file: path.join(ROOT, BASELINE_FILE),
+  formatVersion: 1,
+  unit: "Fund(e) rohes interaktives HTML",
+});
+
+const REMEDIATION =
+  "Framework replacement: <a> → usePrimitives().Link, <details>/<summary> → CollapsibleSection " +
+  `(@cosmicdrift/kumiko-renderer-web). Genuine exception: // ${IGNORE_TAG} <reason>`;
+
+function analyse(files: readonly SourceFile[], compareBaseline: boolean): GuardOutcome {
+  const findings = scan(files);
+  if (!compareBaseline) {
+    console.log("  Baseline-Vergleich uebersprungen (--no-baseline).");
+    return { violations: [] };
+  }
+  const resolveLine = (file: string): number => findings.find((f) => f.file === file)?.line ?? 1;
+  return {
+    violations: rawInteractiveElementsBaseline.check(baselineCounts(findings), REMEDIATION, {
+      formatDriftRemediation:
+        "Einmalig `bun guards/guard-raw-interactive-elements.ts --write-baseline` aufrufen.",
+      resolveLine,
+    }),
+  };
+}
+
+export const guard: AstGuard = {
+  name: "Raw-Interactive-Elements Guard (App-Repos)",
+  scan: SCAN,
+  hint: REMEDIATION,
+  run: (files: readonly SourceFile[]) => analyse(files, true),
+};
+
+// Flags are read ONLY here, not in run() — the shared runner
+// (run-ui-guards.ts) runs every guard with the same argv, a
+// --write-baseline there must not silently rewrite the baseline.
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  if (args.includes("--write-baseline")) {
+    const project = buildSharedProject([guard]);
+    const findings = scan(filesForGuard(project, guard));
+    rawInteractiveElementsBaseline.write(baselineCounts(findings));
+    process.exit(0);
+  }
+  if (args.includes("--no-baseline")) {
+    const project = buildSharedProject([guard]);
+    analyse(filesForGuard(project, guard), false);
+    process.exit(0);
+  }
+  runStandalone(guard);
+}

package/src/guard-raw-sql.ts

@@ -0,0 +1,89 @@
+#!/usr/bin/env bun
+/**
+ * Raw-SQL Guard — blocks `.unsafe()` / `asRawClient()` outside allowed paths.
+ *
+ * Escape hatch for a justified raw-SQL call:
+ *   // kumiko-lint-ignore raw-sql <reason>
+ * on the call's own line or the line directly above (one hit per marker). A bare tag with no
+ * reason text after it does NOT suppress the finding — production code
+ * should otherwise route SQL through `db/queries/*` or typed
+ * `bun-db/query` helpers.
+ *
+ * Plan: kumiko-platform/docs/plans/architecture/intern/sql-queries-consolidation.md
+ */
+
+import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
+import { BLOCKING_SQL_KINDS, scanRepo, sqlScanLayoutFor } from "./_lib/sql-inventory";
+
+export type RawSqlFinding = {
+  readonly repo: string;
+  readonly file: string;
+  readonly line: number;
+  readonly kind: string;
+  readonly snippet: string;
+};
+
+async function scanAllRepos(roots: readonly RepoRoot[]): Promise<{
+  readonly findings: RawSqlFinding[];
+  readonly scannedFiles: number;
+}> {
+  const findings: RawSqlFinding[] = [];
+  let scannedFiles = 0;
+
+  for (const root of roots) {
+    const report = await scanRepo(root.absPath, sqlScanLayoutFor(root));
+    scannedFiles += report.scannedFiles;
+
+    for (const hit of report.hits) {
+      if (hit.allowed) continue;
+      if (hit.markerSuppressed) continue;
+      if (hit.file.includes("/__tests__/")) continue;
+      if (!(BLOCKING_SQL_KINDS as readonly string[]).includes(hit.kind)) continue;
+      findings.push({
+        repo: root.name,
+        file: hit.file,
+        line: hit.line,
+        kind: hit.kind,
+        snippet: hit.snippet,
+      });
+    }
+  }
+
+  return { findings, scannedFiles };
+}
+
+export async function collectRawSqlFindings(
+  roots: readonly RepoRoot[] = resolveRepoRoots(),
+): Promise<readonly RawSqlFinding[]> {
+  return (await scanAllRepos(roots)).findings;
+}
+
+export const check: RepoCheck = {
+  name: "guard-raw-sql",
+  hint:
+    "Regel: Runtime-SQL nur in db/queries/*, bun-db/query.ts, testing/*, oder mit " +
+    "// kumiko-lint-ignore raw-sql <Grund> auf der Zeile bzw. der Zeile davor.",
+  async run(roots) {
+    // kumiko-platform's deliberate empty scan-dir list must not read as vacuous (infra#610).
+    const applicableRoots = roots.filter((r) => sqlScanLayoutFor(r) !== "none");
+    if (applicableRoots.length === 0) {
+      return { violations: [], matchedFiles: 0, notApplicable: true };
+    }
+    const { findings, scannedFiles } = await scanAllRepos(applicableRoots);
+    return {
+      violations: findings.map((f) => ({
+        file: f.file,
+        line: f.line,
+        message: `[${f.kind}] ${f.snippet}`,
+      })),
+      matchedFiles: scannedFiles,
+      notApplicable: false,
+    };
+  },
+};
+
+if (import.meta.main) {
+  const failed = reportResults(await runRepoChecks([check]));
+  process.exit(failed > 0 ? 1 : 0);
+}