@cosmicdrift/kumiko-guards 0.356.0 → 0.357.0

package/src/guard-pii-annotations.ts

@@ -1,25 +1,25 @@
 #!/usr/bin/env bun
 /**
- * Guard: PII-typische Entity-Feldnamen ohne Annotation, mit Baseline-
- * Regression-Guard wie check-complexity.ts.
+ * Guard: PII-typical entity field names without annotation, with a baseline
+ * regression guard like check-complexity.ts.
  *
  * Mirrors the boot heuristic from validatePiiAndRetention. Authors mark
  * fields with { pii: true }, { userOwned }, { tenantOwned: true },
  * { allowPlaintext: "reason" } (legacy) or { personal: ... } (0.210.0
  * successor to the four legacy subject annotations).
  *
- * `.kumiko-pii-annotations-baseline.json` im Repo-Root pinnt pro File die
- * eingefrorene Fund-Anzahl:
- *   - aktuell <= baseline pro File: PASS
- *   - aktuell >  baseline pro File: FAIL (neues unannotiertes PII-Feld)
- * Reduktionen updaten die Baseline NICHT automatisch — nach Annotations-
- * Commits `--write-baseline` aufrufen. Ohne Baseline-Datei bleibt der Guard
- * warning-only (Bootstrap: einmalig `--write-baseline`).
+ * `.kumiko-pii-annotations-baseline.json` in the repo root pins the frozen
+ * finding count per file:
+ *   - current <= baseline per file: PASS
+ *   - current >  baseline per file: FAIL (new unannotated PII field)
+ * Reductions do NOT update the baseline automatically — run `--write-baseline`
+ * after annotation commits. Without a baseline file the guard stays
+ * warning-only (bootstrap: run `--write-baseline` once).
  *
  * Usage:
- *   bun guards/guard-pii-annotations.ts                  # Vergleich gegen Baseline
- *   bun guards/guard-pii-annotations.ts --write-baseline # Baseline neu schreiben
- *   bun guards/guard-pii-annotations.ts --no-baseline    # Vergleich überspringen
+ *   bun guards/guard-pii-annotations.ts                  # compare against baseline
+ *   bun guards/guard-pii-annotations.ts --write-baseline # rewrite baseline
+ *   bun guards/guard-pii-annotations.ts --no-baseline    # skip comparison
  */
 import * as path from "node:path";
 import {
@@ -258,10 +258,10 @@ export const guard: AstGuard = {
   writeBaseline: (files) => piiBaseline.write(baselineCounts(scan(files).findings)),
 };
 
-// Flags werden NUR hier gelesen, nicht in run() — der Shared-Runner
-// (run-guards.ts) faehrt alle Guards mit derselben argv, ein
-// --write-baseline dort duerfte die Baseline nicht stillschweigend
-// neu schreiben.
+// Flags are read ONLY here, not in run() — the shared runner
+// (run-guards.ts) drives all guards with the same argv, and 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")) {

package/src/guard-primitives-discipline.ts

@@ -153,6 +153,7 @@ function isWebFile(absPath: string, scopeRoot: string): boolean {
 }
 
 function walk(dir: string, out: string[]): void {
+  // skip: not every scope has every candidate directory
   if (!fs.existsSync(dir)) return;
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const full = path.join(dir, entry.name);
@@ -205,6 +206,52 @@ function hasIgnore(currentLine: string, prevLine: string): boolean {
   return lineHasIgnoreTag(currentLine, IGNORE_TAG) || lineHasIgnoreTag(prevLine, IGNORE_TAG);
 }
 
+// Block-comment tracking (heuristic): `/* ... */` across multiple lines.
+// Single-line `//` and `*` (inside /* */) are skipped.
+function isCommentOnlyLine(trimmed: string, state: { inBlockComment: boolean }): boolean {
+  if (state.inBlockComment) {
+    if (trimmed.includes("*/")) state.inBlockComment = false;
+    return true;
+  }
+  if (trimmed.startsWith("/*") && !trimmed.includes("*/")) {
+    state.inBlockComment = true;
+    return true;
+  }
+  return trimmed.startsWith("//") || trimmed.startsWith("*");
+}
+
+type LineContext = Pick<Violation, "file" | "line" | "excerpt" | "scope">;
+
+function violationsOnLine(
+  codeOnly: string,
+  context: LineContext,
+  publicPage: boolean,
+): Violation[] {
+  const violations: Violation[] = [];
+  for (const { tag, counterpart, pattern } of TAG_PATTERNS) {
+    if (pattern.test(codeOnly)) violations.push({ ...context, kind: "tag", tag, counterpart });
+  }
+  for (const { call, counterpart, pattern } of CALL_PATTERNS) {
+    if (pattern.test(codeOnly)) {
+      violations.push({ ...context, kind: "call", tag: call, counterpart });
+    }
+  }
+  for (const { token, counterpart, pattern } of CLASS_PATTERNS) {
+    if (pattern.test(codeOnly)) {
+      violations.push({ ...context, kind: "class", tag: token, counterpart });
+    }
+  }
+  if (!publicPage && MX_AUTO_PATTERN.test(codeOnly) && MAX_W_PATTERN.test(codeOnly)) {
+    violations.push({
+      ...context,
+      kind: "class",
+      tag: SCREEN_CONTAINER_LABEL,
+      counterpart: SCREEN_CONTAINER_COUNTERPART,
+    });
+  }
+  return violations;
+}
+
 export function checkFile(
   file: string,
   scope: ScopeKind,
@@ -213,22 +260,13 @@ export function checkFile(
   const text = fs.readFileSync(file, "utf-8");
   const lines = text.split("\n");
   const violations: Violation[] = [];
-  const publicPage = isPublicPage(path.relative(root, file));
-  let inBlockComment = false;
+  const relativeFile = path.relative(root, file);
+  const publicPage = isPublicPage(relativeFile);
+  const commentState = { 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;
+    if (isCommentOnlyLine(trimmed, commentState)) 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.
@@ -237,56 +275,14 @@ export function checkFile(
     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,
-        });
-      }
-    }
-    if (!publicPage && MX_AUTO_PATTERN.test(codeOnly) && MAX_W_PATTERN.test(codeOnly)) {
-      violations.push({
-        file: path.relative(root, file),
-        line: i + 1,
-        kind: "class",
-        tag: SCREEN_CONTAINER_LABEL,
-        counterpart: SCREEN_CONTAINER_COUNTERPART,
-        excerpt: trimmed.length > 120 ? `${trimmed.slice(0, 117)}...` : trimmed,
-        scope,
-      });
-    }
+    const excerpt = trimmed.length > 120 ? `${trimmed.slice(0, 117)}...` : trimmed;
+    violations.push(
+      ...violationsOnLine(
+        codeOnly,
+        { file: relativeFile, line: i + 1, excerpt, scope },
+        publicPage,
+      ),
+    );
   }
   return violations;
 }
@@ -306,8 +302,8 @@ export const check: RepoCheck = {
   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.
+      // infra exits 1 here ("neither FRAMEWORK_ROOT, APP_ROOT nor any other
+      // repo root resolved") — the vacuity floor below reproduces that.
       return { violations: [], matchedFiles: 0, notApplicable: false };
     }
     // Pre-filter count (every file walk() found, before the web/-segment

package/src/guard-screen-conventions.ts

@@ -64,8 +64,10 @@ function checkMetrics(
   violations: GuardViolation[],
 ): void {
   const metricsProp = root.getProperty("metrics");
+  // skip: screens without a literal metrics array have no entries to check
   if (!metricsProp?.isKind(SyntaxKind.PropertyAssignment)) return;
   const init = metricsProp.getInitializer();
+  // skip: a computed metrics value cannot be checked statically
   if (!init?.isKind(SyntaxKind.ArrayLiteralExpression)) return;
   for (const el of init.getElements()) {
     if (hasIgnoreTag(el, IGNORE_TAG)) continue;

package/src/guard-table-ddl.ts

@@ -1,34 +1,34 @@
 #!/usr/bin/env bun
 /**
- * Table-DDL Guard (WARNUNG, kein Fail).
+ * Table-DDL Guard (WARNING, no fail).
  *
- * Findet Aufrufe von `unsafePushTables` / `unsafeCreateEntityTable` /
- * `unsafeEnsureEntityTable` außerhalb der erlaubten Pfade. Apps
- * deklarieren Tabellen via `r.entity()` (event-sourced) oder
- * `r.rawTable()` (deklarativer Bypass mit Audit-Marker) — direkte
- * `unsafe*`-Aufrufe umgehen das Event-Sourcing-System komplett.
+ * Finds calls of `unsafePushTables` / `unsafeCreateEntityTable` /
+ * `unsafeEnsureEntityTable` outside the allowed paths. Apps
+ * declare tables via `r.entity()` (event-sourced) or
+ * `r.rawTable()` (declarative bypass with audit marker) — direct
+ * `unsafe*` calls bypass the event-sourcing system entirely.
  *
  * Plan: kumiko-platform/docs/plans/architecture/table-ddl-guard.md
- * (Stufe 2). Stufe 1 hat die Symbole umbenannt damit jeder Aufruf
- * grep-bar ist; Stufe 3 hat `r.rawTable()` als saubere Alternative
- * eingeführt; Stufe 2 (dieser Check) erzwingt Konsistenz.
+ * (stage 2). Stage 1 renamed the symbols so every call is
+ * greppable; stage 3 introduced `r.rawTable()` as the clean alternative;
+ * stage 2 (this check) enforces consistency.
  *
- * Allowlist (Pfad-Regex, OR-verknüpft):
- *   - packages/framework/src/event-store/**          ES-Meta-Tabellen
+ * Allowlist (path regexes, OR-combined):
+ *   - packages/framework/src/event-store/**          ES meta tables
  *   - packages/framework/src/pipeline/event-consumer-state.ts
  *   - packages/framework/src/pipeline/projection-state.ts
- *   - packages/framework/src/stack/**                Test-Stack-Helper, pushEntityProjectionTables, Helper-Definitionen
- *   - **\/__tests__/**                               Test-Setup
- *   - **\/drizzle/**                                 drizzle-kit-Konfiguration
- *   - **\/bin/migrate.ts                             App-eigener Migrate-CLI
- *   - packages/guards/src/guard-table-ddl.ts          der Guard selbst
- *   - kumiko-framework/scripts/migrate-rename-table-ddl.ts  ts-morph-Rename
+ *   - packages/framework/src/stack/**                test-stack helpers, pushEntityProjectionTables, helper definitions
+ *   - **\/__tests__/**                               test setup
+ *   - **\/drizzle/**                                 drizzle-kit configuration
+ *   - **\/bin/migrate.ts                             app-owned migrate CLI
+ *   - packages/guards/src/guard-table-ddl.ts          the guard itself
+ *   - kumiko-framework/scripts/migrate-rename-table-ddl.ts  ts-morph rename
  *
- * Output: Warnung + Datei:Zeile + Code-Snippet. Blockt nie.
+ * Output: warning + file:line + code snippet. Never blocks.
  */
 
 import path from "node:path";
-import { type SourceFile, SyntaxKind } from "ts-morph";
+import { type Identifier, type Node, type SourceFile, SyntaxKind } from "ts-morph";
 import { type AstGuard, runStandalone, type ScanSpec } from "./_lib/guard-kit";
 
 const ROOT = process.cwd();
@@ -49,8 +49,8 @@ export const ALLOWLIST_PATTERNS: ReadonlyArray<RegExp> = [
   /\/__tests__\//,
   /\/drizzle\//,
   /\/bin\/migrate\.ts$/,
-  // Guards + Rename-Script dürfen die Symbole im Code nennen — beide
-  // sind Tooling, kein Runtime-Pfad.
+  // Guards + the rename script may name the symbols in code — both are
+  // tooling, not a runtime path.
   /\/packages\/guards\/src\/guard-table-ddl\.ts$/,
   /\/scripts\/migrate-rename-table-ddl\.ts$/,
 ];
@@ -66,6 +66,26 @@ export interface Finding {
   readonly snippet: string;
 }
 
+const NEVER_CALL_SITE_PARENT_KINDS: ReadonlySet<SyntaxKind> = new Set([
+  SyntaxKind.ImportSpecifier,
+  SyntaxKind.ExportSpecifier,
+  SyntaxKind.PropertyAssignment,
+  SyntaxKind.ShorthandPropertyAssignment,
+]);
+
+// The identifier names something other than a runtime call of the symbol: an
+// import/export specifier (the violation is the call-site, not "having the
+// name in scope"; the `as` alias case still flags the call), an object key,
+// the right-hand side of a property access (`obj.unsafePushTables` — a method
+// on an unrelated type), or a type-level member (`interface { unsafePushTables(): void }`).
+function isNotRuntimeCallSite(id: Identifier, parent: Node): boolean {
+  if (NEVER_CALL_SITE_PARENT_KINDS.has(parent.getKind())) return true;
+  if (parent.isKind(SyntaxKind.PropertyAccessExpression)) return parent.getNameNode() === id;
+  if (parent.isKind(SyntaxKind.PropertySignature)) return parent.getNameNode() === id;
+  if (parent.isKind(SyntaxKind.MethodSignature)) return parent.getNameNode() === id;
+  return false;
+}
+
 export function collectFindings(sf: SourceFile, repoRoot: string): Finding[] {
   const absPath = sf.getFilePath();
   if (isAllowed(absPath)) return [];
@@ -77,35 +97,9 @@ export function collectFindings(sf: SourceFile, repoRoot: string): Finding[] {
     const name = id.getText();
     if (!UNSAFE_NAMES.has(name)) continue;
 
-    // Skip the import/export specifier itself — the violation is the
-    // call-site, not "having the name in scope". An app that imports
-    // unsafe* without calling it is weird but not the bypass we care
-    // about (and the `as` alias case still flags the call below).
     const parent = id.getParent();
     if (!parent) continue;
-    const pk = parent.getKind();
-    if (pk === SyntaxKind.ImportSpecifier) continue;
-    if (pk === SyntaxKind.ExportSpecifier) continue;
-
-    // Skip property-access right-hand-side (`obj.unsafePushTables`):
-    // a method on some unrelated type that happens to share the name.
-    if (pk === SyntaxKind.PropertyAccessExpression) {
-      const pae = parent.asKindOrThrow(SyntaxKind.PropertyAccessExpression);
-      if (pae.getNameNode() === id) continue;
-    }
-    if (pk === SyntaxKind.PropertyAssignment) continue;
-    if (pk === SyntaxKind.ShorthandPropertyAssignment) continue;
-    // Type-level shadows: `interface { unsafePushTables(): void }` or
-    // `type T = { unsafePushTables: () => void }`. Different namespace,
-    // not the runtime call.
-    if (pk === SyntaxKind.PropertySignature) {
-      const ps = parent.asKindOrThrow(SyntaxKind.PropertySignature);
-      if (ps.getNameNode() === id) continue;
-    }
-    if (pk === SyntaxKind.MethodSignature) {
-      const ms = parent.asKindOrThrow(SyntaxKind.MethodSignature);
-      if (ms.getNameNode() === id) continue;
-    }
+    if (isNotRuntimeCallSite(id, parent)) continue;
 
     const line = id.getStartLineNumber();
     const raw = (lines[line - 1] ?? "").trim();
@@ -124,19 +118,19 @@ function report(findings: readonly Finding[], scanned: number): void {
   console.log(`Table-DDL Guard: ${scanned} files checked.`);
   if (findings.length === 0) {
     console.log("  No bypass calls outside the allowlist.");
-    return;
-  }
-  console.log(`  ${findings.length} bypass call(s) outside the allowlist:`);
-  for (const f of findings) {
-    console.log(`    ${f.file}:${f.line}  ${f.symbol}`);
-    console.log(`      ${f.snippet}`);
+  } else {
+    console.log(`  ${findings.length} bypass call(s) outside the allowlist:`);
+    for (const f of findings) {
+      console.log(`    ${f.file}:${f.line}  ${f.symbol}`);
+      console.log(`      ${f.snippet}`);
+    }
+    console.log("");
+    console.log("  Rule: unsafe* calls are reserved for framework-internal code (event-store,");
+    console.log("  pipeline-state, stack), test setup (__tests__, drizzle/), app migrate CLIs");
+    console.log("  (bin/migrate.ts). Apps declare tables via r.entity() or r.rawTable().");
+    console.log("  Plan: kumiko-platform/docs/plans/architecture/table-ddl-guard.md");
+    console.log("  Warning, no fail.");
   }
-  console.log("");
-  console.log("  Rule: unsafe* calls are reserved for framework-internal code (event-store,");
-  console.log("  pipeline-state, stack), test setup (__tests__, drizzle/), app migrate CLIs");
-  console.log("  (bin/migrate.ts). Apps declare tables via r.entity() or r.rawTable().");
-  console.log("  Plan: kumiko-platform/docs/plans/architecture/table-ddl-guard.md");
-  console.log("  Warning, no fail.");
 }
 
 export const guard: AstGuard = {
@@ -150,8 +144,8 @@ export const guard: AstGuard = {
       findings.push(...collectFindings(sf, ROOT));
     }
     report(findings, scanned);
-    // Warnung, kein Fail (siehe Modul-Header): Bypass-Aufrufe werden
-    // gemeldet, blocken den Guard-Run aber nie.
+    // Warning, no fail (see module header): bypass calls are reported but
+    // never block the guard run.
     return { violations: [] };
   },
 };

package/src/guard-tenant-escalation.ts

@@ -39,7 +39,7 @@
  */
 
 import * as path from "node:path";
-import { type Node, type SourceFile, SyntaxKind } from "ts-morph";
+import { type CallExpression, type Node, type SourceFile, SyntaxKind } from "ts-morph";
 import { ALL_REPO_KINDS, type AstGuard, runStandalone, type ScanSpec } from "./_lib/guard-kit";
 import { literalStringOf, mentionsAsWord, nameForms } from "./_lib/handler-name-forms";
 import { TEST_FILE_RE } from "./_lib/test-file";
@@ -187,6 +187,45 @@ const PLATFORM_WIDE_ACCESS = /\baccess\.(?:systemAdmin|system|privileged)\b/;
 
 type GlobalUserWrite = { name: string; file: string; line: number };
 
+function globalUserWriteMissingCheck(
+  call: CallExpression,
+  filePath: string,
+): GlobalUserWrite | undefined {
+  if (call.getExpression().getText() !== "defineWriteHandler") return undefined;
+  const arg = call.getArguments()[0];
+  if (!arg || arg.getKind() !== SyntaxKind.ObjectLiteralExpression) return undefined;
+  const obj = arg.asKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+  // `name` is only used for the violation message, not the security
+  // check itself — a factory-built handler with a non-literal name
+  // expression (`name: enable ? "enable" : "disable"`) must not skip
+  // Check C just because literalStringOf() can't resolve it.
+  const name = literalStringOf(obj.getProperty("name"));
+  const schema = obj.getProperty("schema");
+  const accessProp = obj.getProperty("access");
+  // No `access` key at all = deny-all (engine/access.ts: undefined
+  // returns false), so there is nothing to reach across a tenant.
+  if (!schema || !accessProp) return undefined;
+  // Presets that resolve to platform-wide actors only (engine/
+  // config-helpers `access`): no tenant boundary exists to cross.
+  // Everything else — access.admin, and the openToAll handlers that
+  // gate on isAdminActor at runtime (#1556's shape) — is reachable by
+  // a tenant-scoped TenantAdmin.
+  if (PLATFORM_WIDE_ACCESS.test(accessProp.getText())) return undefined;
+  if (!TARGETS_OTHER_USER.test(resolvedSchemaText(schema))) return undefined;
+  const body = call.getText();
+  // Must actually touch a *user* table — otherwise a handler reading
+  // ctx.db.raw against an unrelated global table (plans, audit log,
+  // invitations) gets flagged with a "reads a global user row" message
+  // that doesn't apply to it (false-positive on clean code).
+  if (!body.includes("ctx.db.raw") || !/\buserTable\b/.test(body)) return undefined;
+  if (MEMBERSHIP_GATE.test(body) || CROSS_TENANT_HELPER_GATE.test(body)) return undefined;
+  return {
+    name: name ?? path.basename(filePath),
+    file: filePath,
+    line: call.getStartLineNumber(),
+  };
+}
+
 export function findGlobalUserWritesMissingMembershipCheck(
   files: readonly SourceFile[],
 ): GlobalUserWrite[] {
@@ -194,39 +233,8 @@ export function findGlobalUserWritesMissingMembershipCheck(
   for (const sf of files) {
     if (TEST_FILE_RE.test(sf.getFilePath())) continue;
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-      if (call.getExpression().getText() !== "defineWriteHandler") continue;
-      const arg = call.getArguments()[0];
-      if (!arg || arg.getKind() !== SyntaxKind.ObjectLiteralExpression) continue;
-      const obj = arg.asKindOrThrow(SyntaxKind.ObjectLiteralExpression);
-      // `name` is only used for the violation message, not the security
-      // check itself — a factory-built handler with a non-literal name
-      // expression (`name: enable ? "enable" : "disable"`) must not skip
-      // Check C just because literalStringOf() can't resolve it.
-      const name = literalStringOf(obj.getProperty("name"));
-      const schema = obj.getProperty("schema");
-      const accessProp = obj.getProperty("access");
-      // No `access` key at all = deny-all (engine/access.ts: undefined
-      // returns false), so there is nothing to reach across a tenant.
-      if (!schema || !accessProp) continue;
-      // Presets that resolve to platform-wide actors only (engine/
-      // config-helpers `access`): no tenant boundary exists to cross.
-      // Everything else — access.admin, and the openToAll handlers that
-      // gate on isAdminActor at runtime (#1556's shape) — is reachable by
-      // a tenant-scoped TenantAdmin.
-      if (PLATFORM_WIDE_ACCESS.test(accessProp.getText())) continue;
-      if (!TARGETS_OTHER_USER.test(resolvedSchemaText(schema))) continue;
-      const body = call.getText();
-      // Must actually touch a *user* table — otherwise a handler reading
-      // ctx.db.raw against an unrelated global table (plans, audit log,
-      // invitations) gets flagged with a "reads a global user row" message
-      // that doesn't apply to it (false-positive on clean code).
-      if (!body.includes("ctx.db.raw") || !/\buserTable\b/.test(body)) continue;
-      if (MEMBERSHIP_GATE.test(body) || CROSS_TENANT_HELPER_GATE.test(body)) continue;
-      out.push({
-        name: name ?? path.basename(sf.getFilePath()),
-        file: sf.getFilePath(),
-        line: call.getStartLineNumber(),
-      });
+      const write = globalUserWriteMissingCheck(call, sf.getFilePath());
+      if (write) out.push(write);
     }
   }
   return out;

package/src/guard-test-stack-drift.ts

@@ -29,9 +29,9 @@ import { type ScanSpec, scanFiles } from "./_lib/scan-scope";
 
 const ROOT = process.cwd();
 
-// Beide Suffixe: `.integration.ts` (legacy) + `.integration.test.ts` (canonical
-// nach bun-test-cutover). Transition-safe — matcht main (legacy) und migrierte
-// Branches gleichermaßen.
+// Both suffixes: `.integration.ts` (legacy) + `.integration.test.ts` (canonical
+// after the bun-test cutover). Transition-safe — matches main (legacy) and
+// migrated branches alike.
 const SCAN: ScanSpec = {
   scope: "tests",
   extensions: ["ts"],
@@ -66,7 +66,7 @@ export function isIntegrationTestFile(filePath: string): boolean {
 
 export interface Violation {
   file: string;
-  reason: string;
+  detail: string;
   forbiddenCalls: Array<{ name: string; line: number }>;
 }
 
@@ -127,7 +127,7 @@ export function scanFile(sf: SourceFile): Violation | null {
 
   return {
     file: path.relative(ROOT, sf.getFilePath()),
-    reason: "calls pipeline internals without buildServer/setupTestStack",
+    detail: "calls pipeline internals without buildServer/setupTestStack",
     forbiddenCalls: forbiddenHits,
   };
 }
@@ -156,7 +156,7 @@ export const check: RepoCheck = {
       const v = scanFile(sf);
       if (v === null) continue;
       for (const c of v.forbiddenCalls) {
-        violations.push({ file: v.file, line: c.line, message: `${v.reason}: ${c.name}(...)` });
+        violations.push({ file: v.file, line: c.line, message: `${v.detail}: ${c.name}(...)` });
       }
     }
 

package/src/guard-test-timeouts.ts

@@ -106,11 +106,11 @@ function isSleepStatement(node: Node): boolean {
   return false;
 }
 
-// Nested loops are their own finding — skipping them keeps one sleep from
-// being counted once per enclosing loop.
 function bodySleeps(loop: Node): boolean {
   let found = false;
   loop.forEachDescendant((node, traversal) => {
+    // skip: nested loops are their own finding, so one sleep is not counted
+    // once per enclosing loop
     if (isLoop(node)) {
       traversal.skip();
       return;
@@ -230,8 +230,9 @@ export function scanTimeouts(
   const findings: Finding[] = [];
   const add = (node: Node, message: string): void => {
     const reported = withExceptionNote(node, message);
-    if (reported === undefined) return;
-    findings.push({ file, line: node.getStartLineNumber(), message: reported });
+    if (reported !== undefined) {
+      findings.push({ file, line: node.getStartLineNumber(), message: reported });
+    }
   };
   const aliases = testFrameworkAliases(sf);
   for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {

package/src/guard-text-field-stance.ts

@@ -1,27 +1,27 @@
 #!/usr/bin/env bun
 /**
- * Guard: `createTextField`/`createLongTextField`-Aufrufe ohne `personal`-
- * Haltung, mit Baseline-Regression-Guard wie guard-pii-annotations.ts.
+ * Guard: `createTextField`/`createLongTextField` calls without a `personal`
+ * stance, with a baseline regression guard like guard-pii-annotations.ts.
  *
- * kumiko-framework#2810: `createTextField`/`createLongTextField` sollen
- * fail-closed werfen, wenn kein `personal` (Muster #2558) deklariert ist.
- * Workspace-weit fehlt `personal` an hunderten Call-Sites — ein Throw würde
- * den Build sofort brechen. Dieser Guard deckt die Vollmenge (jeder Aufruf)
- * ab, `guard-pii-annotations.ts` nur die Namens-Heuristik (PII-verdächtige
- * Feldnamen) — die beiden Baselines sind bewusst getrennt.
+ * kumiko-framework#2810: `createTextField`/`createLongTextField` should
+ * throw fail-closed when no `personal` (pattern #2558) is declared.
+ * Workspace-wide `personal` is missing at hundreds of call sites — a throw would
+ * break the build immediately. This guard covers the full set (every call),
+ * `guard-pii-annotations.ts` only the name heuristic (PII-suspicious
+ * field names) — the two baselines are deliberately separate.
  *
- * `.kumiko-text-field-stance-baseline.json` im Repo-Root pinnt pro File die
- * eingefrorene Fund-Anzahl:
- *   - aktuell <= baseline pro File: PASS
- *   - aktuell >  baseline pro File: FAIL (neuer Aufruf ohne personal-Haltung)
- * Reduktionen updaten die Baseline NICHT automatisch — nach Annotations-
- * Commits `--write-baseline` aufrufen. Ohne Baseline-Datei bleibt der Guard
- * warning-only (Bootstrap: einmalig `--write-baseline`).
+ * `.kumiko-text-field-stance-baseline.json` in the repo root pins the frozen
+ * finding count per file:
+ *   - current <= baseline per file: PASS
+ *   - current >  baseline per file: FAIL (new call without a personal stance)
+ * Reductions do NOT update the baseline automatically — run `--write-baseline`
+ * after annotation commits. Without a baseline file the guard stays
+ * warning-only (bootstrap: run `--write-baseline` once).
  *
  * Usage:
- *   bun guards/guard-text-field-stance.ts                  # Vergleich gegen Baseline
- *   bun guards/guard-text-field-stance.ts --write-baseline # Baseline neu schreiben
- *   bun guards/guard-text-field-stance.ts --no-baseline    # Vergleich überspringen
+ *   bun guards/guard-text-field-stance.ts                  # compare against baseline
+ *   bun guards/guard-text-field-stance.ts --write-baseline # rewrite baseline
+ *   bun guards/guard-text-field-stance.ts --no-baseline    # skip comparison
  */
 import * as path from "node:path";
 import {
@@ -227,10 +227,10 @@ export const guard: AstGuard = {
   writeBaseline: (files) => textFieldStanceBaseline.write(baselineCounts(scan(files).findings)),
 };
 
-// Flags werden NUR hier gelesen, nicht in run() — der Shared-Runner
-// (run-guards.ts) faehrt alle Guards mit derselben argv, ein
-// --write-baseline dort duerfte die Baseline nicht stillschweigend
-// neu schreiben.
+// Flags are read ONLY here, not in run() — the shared runner
+// (run-guards.ts) drives all guards with the same argv, and 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")) {