@cosmicdrift/kumiko-guards 0.334.0 → 0.336.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.334.0",
+  "version": "0.336.0",
   "description": "AST-based security guards for Kumiko repos: direct-fs/fetch, tenant escalation, admin-API, escape hatches and related checks, run over a shared ts-morph project.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -28,7 +28,7 @@
     "kumiko-pre-push": "./src/pre-push.sh"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-repo-manifest": "0.334.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.336.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/_lib/framework-import.ts

@@ -0,0 +1,29 @@
+import * as path from "node:path";
+import { type Node, SyntaxKind } from "ts-morph";
+
+const FRAMEWORK_PACKAGE = "@cosmicdrift/kumiko-framework";
+// Inside the framework monorepo itself the helpers are imported relatively,
+// so a relative specifier counts when it resolves into the framework package.
+const FRAMEWORK_SOURCE_DIR_MARKER = "/packages/framework/src/";
+
+function isFrameworkModuleSpecifier(specifier: string, importingFile: string): boolean {
+  if (specifier === FRAMEWORK_PACKAGE || specifier.startsWith(`${FRAMEWORK_PACKAGE}/`)) {
+    return true;
+  }
+  if (!specifier.startsWith(".")) return false;
+  const resolved = path.resolve(path.dirname(importingFile), specifier);
+  return `${resolved}/`.includes(FRAMEWORK_SOURCE_DIR_MARKER);
+}
+
+// A text match on a function name lets a same-named local no-op clear an
+// escape-hatch finding, so the identifier must resolve to an import of
+// `exportedName` from the framework package. Aliased imports resolve too.
+export function isFrameworkImportOf(node: Node, exportedName: string): boolean {
+  if (!node.isKind(SyntaxKind.Identifier)) return false;
+  const decls = node.getSymbol()?.getDeclarations() ?? [];
+  return decls.some((decl) => {
+    if (!decl.isKind(SyntaxKind.ImportSpecifier) || decl.getName() !== exportedName) return false;
+    const specifier = decl.getImportDeclaration().getModuleSpecifierValue();
+    return isFrameworkModuleSpecifier(specifier, decl.getSourceFile().getFilePath());
+  });
+}

package/src/_lib/git-env.ts

@@ -1,13 +1,5 @@
-/**
- * Spawned git calls get an allowlisted environment, never `...process.env`.
- * A caller running as a pre-push hook would otherwise inherit `GIT_DIR`/
- * `GIT_WORK_TREE` from git, which git prefers over `cwd` — so an inherited
- * environment would answer for the hook's repo instead of the path being
- * asked about. `HOME` stays in, so the global config is still read.
- *
- * An allowlist (not a blocklist) so a future git env var neither of us has
- * thought of yet is excluded by construction, not by omission.
- */
+// Allowlist, not `...process.env`: git prefers an inherited GIT_DIR/GIT_WORK_TREE over cwd,
+// so a pre-push hook's env would answer for the hook's repo. HOME stays so global config loads.
 export const GIT_ENV_KEYS = ["PATH", "HOME", "TMPDIR", "TMP", "TEMP", "USER", "LOGNAME"] as const;
 
 /**

package/src/_lib/guard-kit.ts

@@ -125,6 +125,10 @@ export function relFromRepoRoot(
   return filePath.slice(filePath.indexOf(marker));
 }
 
+export function relativeToCwd(absolutePath: string): string {
+  return pathRelative(process.cwd(), absolutePath);
+}
+
 export function isAllowlisted(relPath: string, allowlist: readonly RegExp[]): boolean {
   return allowlist.some((re) => re.test(relPath));
 }
@@ -474,8 +478,13 @@ export function explainGuards(
 
 function guardKitVersion(): string {
   const pkgPath = resolve(import.meta.dir, "../../package.json");
-  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { readonly version?: string };
-  return pkg.version ?? "0.0.0";
+  // The version only decorates the banner; it must never abort a guard run.
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { readonly version?: string };
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
 }
 
 /**
@@ -494,12 +503,7 @@ export function guardKitPreflightError(guardCount: number, rootCount: number): s
   return undefined;
 }
 
-/**
- * Validates CLI args for one subcommand against the flags it actually
- * understands — every arg must match `known` exactly (not just a `--`-prefix
- * check, which let a single-dash typo or a stray positional through
- * unnoticed). An unknown arg must fail loud, never pass through silently.
- */
+// Exact match, not a `--` prefix check: single-dash typos and positionals must not slip through.
 export function cliFlagsError(
   subcommand: string,
   argv: readonly string[],

package/src/_lib/scan-scope.ts

@@ -164,7 +164,7 @@ function scanRoot(spec: ScanSpec, root: RepoRoot): RootScan {
   return { root, files, sourceSurface: sourceSurfaceHits.length };
 }
 
-function keepsRootKind(spec: ScanSpec, root: RepoRoot): boolean {
+export function keepsRootKind(spec: ScanSpec, root: RepoRoot): boolean {
   if (spec.kinds) return spec.kinds.includes(root.kind);
   return root.kind !== "tooling";
 }

package/src/_lib/sql-inventory.ts

@@ -108,8 +108,12 @@ export const BLOCKING_SQL_KINDS: ReadonlyArray<SqlInventoryKind> = ["unsafe", "a
 const TS_GLOB = new Bun.Glob("**/*.{ts,tsx}");
 
 // kumiko-platform deliberately returns no scan dirs (0 files) — its docs-samples tree needs its own allowlist review before this guard scans it (follow-up issue).
+export function isSqlScanExcluded(root: RepoRoot): boolean {
+  return root.name === "kumiko-platform";
+}
+
 export function sqlScanDirsFor(root: RepoRoot): readonly string[] {
-  if (root.name === "kumiko-platform") return [];
+  if (isSqlScanExcluded(root)) return [];
   return sourceRootDirs(root).map((dir) => dir.slice(root.absPath.length).replace(/^\/+/, ""));
 }
 

package/src/changes.json

@@ -1,4 +1,30 @@
 [
+  {
+    "version": "0.336.0",
+    "type": "improvement",
+    "title": "Guards reject --guard without --write-baseline and catch more raw-form-HTML, locale and timeout cases",
+    "detail": "Guards are stricter and more consistent: `guards --guard=<name>` without `--write-baseline` is rejected instead of silently running every guard, the raw-form-HTML check also catches tags after `=`, `[` or in spaceless ternaries, the German locale check flags lowercase \"organisation\", `test-timeouts` flags `setDefaultTimeout` and `describe.configure({ timeout })`, the no-framed-extension-sections guard correlates registry keys and usages by resolved value, and the fake-tests helper lookup is scope-aware. UI guards report repo-relative file paths. The pre-push worktree detection compares absolute git dirs."
+  },
+  {
+    "version": "0.336.0",
+    "type": "improvement",
+    "title": "secret-literal checks all fallbacks on a line; as-casts audit is quiet inside the shared runner",
+    "detail": "`secret-literal` now inspects every `?? \"literal\"` fallback on a line instead of only the first, so a hardcoded secret behind a trivial first fallback is flagged. The `as-casts` audit prints its per-site listings only when run standalone; inside the shared runner it prints just the counts and the baseline verdict.",
+    "migration": "A repo with a hardcoded secret fallback hidden behind an earlier trivial fallback on the same line can now fail the secret-literal guard. Replace the literal with a hard failure on a missing env value."
+  },
+  {
+    "version": "0.335.0",
+    "type": "improvement",
+    "title": "Stricter guard detection for raw-sql, test-template-drift, framed extension sections, runtime-isolation and test-stack-drift",
+    "detail": "Stricter guard detection; app repos that carried an undetected pattern can now turn red.\n- `guard-raw-sql`: only kumiko-platform is skipped. An app repo whose declared `sourceRoots` all do not exist now fails as vacuous (0 files scanned) instead of passing.\n- `test-template-drift`: `...defineAppE2eConfig(...)` spread next to `fullyParallel`, `retries`, `timeout`, `workers` or `expect`, and shorthand `{ viewport }` / `{ deviceScaleFactor }`, are flagged.\n- `no-framed-extension-sections`: an `extensionSectionComponents` registry held in a variable, shorthand or spread is resolved.\n- `runtime-isolation`: entries declared in package.json `kumiko.clientEntry` / `kumiko.clientEntries[].sourceFile` count as browser code.\n- `test-stack-drift`: `@no-server-stack:` only opts out when it sits in a comment, not in a string literal.\n- Direct `run-guards.ts` / `run-ui-guards.ts` / `run-repo-checks.ts` invocations exit with 1 instead of the failure count.",
+    "migration": "App repos that carried a previously undetected pattern can now fail their guards. Fix the reported sites; a vacuous raw-sql scan (all declared sourceRoots missing) must declare existing source roots."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Escape-hatch guards accept only real framework imports, a corrupt cast baseline is an error, hints name kumiko-guards guards",
+    "detail": "The escape-hatch guards now only accept `declareEscapeHatch` and `withUnsafeRawGrant` imported from the framework itself; a local function or an import from another module with the same name no longer satisfies them. A corrupt `.kumiko-cast-baseline.json` is now an error instead of being treated as an empty baseline. Guard hints point at `kumiko-guards guards`."
+  },
   {
     "version": "0.332.0",
     "type": "fix",

package/src/check-as-casts.ts

@@ -48,6 +48,7 @@ import {
   buildSharedProject,
   filesForGuard,
   type GuardOutcome,
+  type GuardViolation,
   runStandalone,
   type ScanSpec,
 } from "./_lib/guard-kit";
@@ -404,6 +405,11 @@ function groupByCategory(all: readonly Site[]): Map<Category, Site[]> {
   return byCat;
 }
 
+// The per-site listings are advisory and long; inside the shared runner (every consumer's
+// `bun run check`) they would bury the output of guards that can fail, so only a standalone
+// run of this file prints them.
+const PRINT_SITE_LISTINGS = import.meta.main;
+
 function reportCasts(all: readonly Site[], scanned: number): void {
   const byCat = groupByCategory(all);
   console.log(`as-Cast Audit: ${scanned} files checked, ${all.length} casts total.\n`);
@@ -411,6 +417,8 @@ function reportCasts(all: readonly Site[], scanned: number): void {
     const count = byCat.get(c)?.length ?? 0;
     console.log(`  ${c.padEnd(18)} ${count}`);
   }
+  // skip: site listings are printed only on a standalone run of this guard
+  if (!PRINT_SITE_LISTINGS) return;
 
   const suspects = CATS.filter((c) => c.startsWith("suspect-"));
 
@@ -546,26 +554,89 @@ function writeBaseline(all: readonly Site[]): void {
 // Per File:target: aktueller Count gegen baseline. Mehr → Regression.
 // Cast-Tausch (Cast A weg, Cast B mit anderem target hinzu) wird so erkannt
 // obwohl Total stabil bleibt. Nur Report — Warnung, kein Fail.
-function reportBaseline(all: readonly Site[]): void {
+// Merge-conflict markers, truncated writes and hand edits all land here; the
+// file is read once at the boundary so the comparison below can trust its shape.
+function isCountsByFile(value: unknown): value is Record<string, Record<string, number>> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return Object.values(value).every(
+    (targets) =>
+      typeof targets === "object" &&
+      targets !== null &&
+      !Array.isArray(targets) &&
+      Object.values(targets).every((count) => typeof count === "number"),
+  );
+}
+
+type BaselineLoad =
+  | { kind: "missing" }
+  | { kind: "format-drift"; format: unknown }
+  | { kind: "invalid"; reason: string }
+  | { kind: "ok"; baseline: Baseline };
+
+export function loadBaseline(file: string): BaselineLoad {
+  if (!existsSync(file)) return { kind: "missing" };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf-8"));
+  } catch (error) {
+    return { kind: "invalid", reason: error instanceof Error ? error.message : String(error) };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { kind: "invalid", reason: "expected a JSON object" };
+  }
+  const record: Record<string, unknown> = { ...parsed };
+  if (record["format"] !== BASELINE_FORMAT_VERSION) {
+    return { kind: "format-drift", format: record["format"] };
+  }
+  const { generated, totalSuspect, perFile } = record;
+  if (
+    typeof generated !== "string" ||
+    typeof totalSuspect !== "number" ||
+    !isCountsByFile(perFile)
+  ) {
+    return {
+      kind: "invalid",
+      reason: "expected { format, generated: string, totalSuspect: number, perFile: object }",
+    };
+  }
+  return {
+    kind: "ok",
+    baseline: { format: BASELINE_FORMAT_VERSION, generated, totalSuspect, perFile },
+  };
+}
+
+export function reportBaseline(
+  all: readonly Site[],
+  baselineFile: string = baselinePath,
+): GuardViolation[] {
   const repoLocalSuspects = repoLocal(suspectByFileAndTarget(all));
   const repoLocalTotal = totalOf(repoLocalSuspects);
 
-  if (!existsSync(baselinePath)) {
+  const loaded = loadBaseline(baselineFile);
+  if (loaded.kind === "missing") {
     console.log(
       "\n  No baseline found. Freeze one with `--write-baseline` first — warning, no fail until then.",
     );
-    return;
+    return [];
   }
-
-  const rawBaseline = JSON.parse(readFileSync(baselinePath, "utf-8")) as Partial<Baseline>;
-  if (rawBaseline.format !== BASELINE_FORMAT_VERSION) {
+  if (loaded.kind === "invalid") {
+    // A corrupt baseline must not read as "no regressions".
+    return [
+      {
+        file: baselineFile,
+        line: 1,
+        message: `Cannot read cast baseline ${baselineFile}: ${loaded.reason}. Fix the file (e.g. resolve merge-conflict markers) or regenerate it with \`bun packages/guards/src/check-as-casts.ts --write-baseline\`.`,
+      },
+    ];
+  }
+  if (loaded.kind === "format-drift") {
     console.log(
-      `\n  Baseline format drift: expected format=${BASELINE_FORMAT_VERSION}, read format=${rawBaseline.format ?? "<missing>"}.`,
+      `\n  Baseline format drift: expected format=${BASELINE_FORMAT_VERSION}, read format=${String(loaded.format ?? "<missing>")}.`,
     );
     console.log("  Run `bun packages/guards/src/check-as-casts.ts --write-baseline` once.");
-    return;
+    return [];
   }
-  const baseline = rawBaseline as Baseline;
+  const { baseline } = loaded;
 
   type Regression = { file: string; target: string; baseline: number; current: number };
   const regressions: Regression[] = [];
@@ -602,7 +673,7 @@ function reportBaseline(all: readonly Site[]): void {
         "    3. If a cleanup reduction in one file offsets an increase in another: " +
         "run `bun packages/guards/src/check-as-casts.ts --write-baseline` after committing",
     );
-    return;
+    return [];
   }
 
   console.log(`\n  ✓ Baseline (${baseline.totalSuspect}) — current ${repoLocalTotal}`);
@@ -611,17 +682,21 @@ function reportBaseline(all: readonly Site[]): void {
       `  ✓ ${reduced} suspect cast(s) reduced since baseline. Run \`--write-baseline\` if appropriate.`,
     );
   }
+  return [];
 }
 
 function analyseCasts(files: readonly SourceFile[], compareBaseline: boolean): GuardOutcome {
   const { all, scanned } = scanCasts(files);
   reportCasts(all, scanned);
   reportUnknownReasons(all);
-  if (compareBaseline) reportBaseline(all);
-  else console.log("\n  Baseline comparison skipped (--no-baseline).");
+  if (!compareBaseline) {
+    console.log("\n  Baseline comparison skipped (--no-baseline).");
+    return { violations: [] };
+  }
   // WARNUNG, kein Fail (coding-standards.md → "Type Assertions"): weder
-  // unbekannte @cast-boundary-Reasons noch Baseline-Regression blocken.
-  return { violations: [] };
+  // unbekannte @cast-boundary-Reasons noch Baseline-Regression blocken. Nur
+  // eine unlesbare Baseline schlägt fehl.
+  return { violations: reportBaseline(all) };
 }
 
 export const guard: AstGuard = {

package/src/check-real-provider-isolation.ts

@@ -133,6 +133,14 @@ function scanPackageJsonScripts(root: RepoRoot, findings: TextLineFinding[]): nu
   return scanned;
 }
 
+// A bare substring match would accept the entry inside a TOML comment or under
+// another key such as coveragePathIgnorePatterns, which leaves `bun test` unguarded.
+function ignoresRealTests(bunfigToml: string): boolean {
+  const withoutComments = bunfigToml.replace(/^\s*#.*$/gm, "");
+  const match = /^\s*pathIgnorePatterns\s*=\s*\[([^\]]*)\]/m.exec(withoutComments);
+  return match?.[1]?.includes(`"${REAL_TEST_IGNORE_ENTRY}"`) ?? false;
+}
+
 // The generated bunfig template (packages/testing/src/bunfig.ts) is what app
 // and library repos consume via `kumiko-testing bunfig` — the framework repo
 // hand-maintains its own root bunfig*.toml files and doesn't run this
@@ -150,7 +158,7 @@ function bunfigMissingRealExclusion(root: RepoRoot, findings: TextLineFinding[])
       continue;
     }
     scanned++;
-    if (!content.includes(REAL_TEST_IGNORE_ENTRY)) {
+    if (!ignoresRealTests(content)) {
       findings.push({
         file: rel,
         line: 1,

package/src/check-runtime-isolation.ts

@@ -64,13 +64,15 @@ import {
   runRepoChecks,
 } from "./_lib/guard-kit";
 import { frameworkTsConfigPath, type RepoRoot, resolveRepoRoots } from "./_lib/roots";
-import { type ScanSpec, scanFiles, scanRoots } from "./_lib/scan-scope";
+import { keepsRootKind, type ScanSpec, scanFiles } from "./_lib/scan-scope";
 import {
   classify,
   computeClientReachablePaths,
+  createDirectiveClassifier,
   findRuntimeIsolationViolations,
   isClientEntryPath,
   type Runtime,
+  readDeclaredClientEntries,
 } from "./runtime-isolation-classify";
 
 const SCAN: ScanSpec = { scope: "source", extensions: ["ts", "tsx"] };
@@ -141,11 +143,15 @@ function scanRoot(root: RepoRoot): {
       return !fp.includes("/node_modules/") && !fp.includes("/dist/");
     });
 
+  const declaredClientEntries = readDeclaredClientEntries(root.absPath);
   const workspaceCache = new Map<string, Runtime | null>();
+  const directiveOf = createDirectiveClassifier();
   const clientReachable = computeClientReachablePaths(scannedFiles, (sf) => {
     const rel = path.relative(root.absPath, sf.getFilePath());
-    if (isClientEntryPath(rel)) return true;
-    return classify(sf.getFilePath(), root.absPath, workspaceCache) === "client";
+    if (isClientEntryPath(rel, declaredClientEntries)) return true;
+    return (
+      classify(sf.getFilePath(), root.absPath, workspaceCache, undefined, directiveOf) === "client"
+    );
   });
 
   const { violations: allViolations, outsideRoot } = findRuntimeIsolationViolations(
@@ -153,6 +159,7 @@ function scanRoot(root: RepoRoot): {
     root.absPath,
     workspaceCache,
     clientReachable,
+    directiveOf,
   );
 
   return { allViolations, outsideRoot, scannedFiles: scannedFiles.length };
@@ -170,7 +177,7 @@ export const check: RepoCheck = {
     // The kind filter (scan-scope.ts keepsRootKind) excludes "tooling" roots by
     // default — that's a deliberate scope choice, not a vacuous scan, so it must
     // report notApplicable instead of matchedFiles: 0.
-    if (scanRoots(SCAN, [root]).length === 0) {
+    if (!keepsRootKind(SCAN, root)) {
       return { violations: [], matchedFiles: 0, notApplicable: true };
     }
     const rootAbsPath = root.absPath;

package/src/check-secret-literals.ts

@@ -42,7 +42,7 @@ const IS_TEST = /\.(?:test|integration)\.tsx?$/;
 const DEV_ENTRYPOINT = /(?:^|\/)bin\/server\.ts$/;
 
 // A `?? "literal"` / `|| "literal"` nullish/or fallback to a string literal.
-const STRING_FALLBACK = /(?:\?\?|\|\|)\s*(['"`])([^'"`\n]+)\1/;
+const STRING_FALLBACK = /(?:\?\?|\|\|)\s*(['"`])([^'"`\n]+)\1/g;
 // A secret-like identifier. Matched only against the text LEFT of the fallback
 // (assignee / property name): `cfg.title ?? "Secret Santa"` is a label, not a secret.
 const SECRET_NAME =
@@ -116,19 +116,24 @@ export function scanLinesForSecretLiterals(lines: readonly string[]): SecretLite
   for (let i = 0; i < lines.length; i++) {
     const raw = lines[i] ?? "";
     const code = maskedLines[i] ?? "";
-    const match = STRING_FALLBACK.exec(code);
-    if (!match) continue;
-    const literal = match[2];
-    if (!literal || literal.length < MIN_SECRET_LENGTH || TRIVIAL_LITERAL.test(literal)) continue;
-    const left = code.slice(0, match.index);
-    const name =
-      SECRET_NAME.exec(left)?.[0] ??
-      (SECRET_LITERAL_TOKEN.test(literal)
-        ? (LHS_NAME.exec(left)?.[1] ?? UNNAMED_PLACEHOLDER)
-        : undefined);
-    if (name === undefined) continue;
     if (raw.includes(IGNORE_TAG) || (lines[i - 1] ?? "").includes(IGNORE_TAG)) continue;
-    hits.push({ lineNumber: i + 1, name, literalLength: literal.length });
+    // Every fallback on the line is inspected; the name is read only from the text since the
+    // previous fallback, so an earlier assignee cannot lend its name to a later literal.
+    let previousEnd = 0;
+    for (const match of code.matchAll(STRING_FALLBACK)) {
+      const left = code.slice(previousEnd, match.index);
+      previousEnd = match.index + match[0].length;
+      const literal = match[2];
+      if (!literal || literal.length < MIN_SECRET_LENGTH || TRIVIAL_LITERAL.test(literal)) continue;
+      const name =
+        SECRET_NAME.exec(left)?.[0] ??
+        (SECRET_LITERAL_TOKEN.test(literal)
+          ? (LHS_NAME.exec(left)?.[1] ?? UNNAMED_PLACEHOLDER)
+          : undefined);
+      if (name === undefined) continue;
+      hits.push({ lineNumber: i + 1, name, literalLength: literal.length });
+      break;
+    }
   }
   return hits;
 }

package/src/cli.ts

@@ -45,6 +45,10 @@ async function main(): Promise<void> {
     process.exit(1);
   }
   const flags = process.argv.slice(3);
+  if (subcommand !== undefined && (flags.includes("--help") || flags.includes("-h"))) {
+    printHelp();
+    process.exit(0);
+  }
 
   if (subcommand === "list") {
     const flagsError = cliFlagsError("list", flags, SUBCOMMAND_FLAGS.list);

package/src/guard-access-denied-test.ts

@@ -13,7 +13,7 @@
  *
  * Usage:
  *   bun guards/guard-access-denied-test.ts
- *   Baseline: bun guards/run-guards.ts --write-security-baseline
+ *   Baseline: kumiko-guards guards --write-security-baseline
  */
 
 import * as path from "node:path";
@@ -117,7 +117,7 @@ export const guard: AstGuard = {
   name: "Access-Denied-Test Guard",
   scan: SCAN,
   security: true,
-  hint: "Role-restricted write handlers need a test that references the handler and asserts a caller without the role is rejected (AccessDeniedError / access_denied / 403). Existing gaps are frozen in the security baseline; after closing one: `bun guards/run-guards.ts --write-security-baseline`.",
+  hint: "Role-restricted write handlers need a test that references the handler and asserts a caller without the role is rejected (AccessDeniedError / access_denied / 403). Existing gaps are frozen in the security baseline; after closing one: `kumiko-guards guards --write-security-baseline`.",
   run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
     // consumer CI scans only its own repo, so a sibling repo's test must not count as coverage
     const violations: GuardViolation[] = findHandlersWithoutAccessDeniedTest(files, roots).map(

package/src/guard-admin-api.ts

@@ -34,12 +34,11 @@ const SCAN: ScanSpec = { scope: "source", extensions: ["ts"] };
 const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$)/;
 
 // Allowed callers: migration runners (sample-local, src/ and bin/) +
-// admin scripts + the definition itself + this guard script.
+// admin scripts + the definition itself.
 const ALLOWLIST: readonly RegExp[] = [
   /^samples\/[^/]+\/src\/migration\//,
   /^scripts\/migrations\//,
   /^packages\/framework\/src\/event-store\/admin-api\.ts$/,
-  /^scripts\/guard-admin-api\.ts$/,
 ];
 
 const GUARDED_CALLS = new Set(["appendRaw", "appendRawBatch"]);

package/src/guard-app-feature-structure.ts

@@ -40,8 +40,8 @@ export const guard: AstGuard = {
   name: "App-Feature-Structure Guard (App-Repos)",
   scan: SCAN,
   hint:
-    "Konvention: feature.ts nur Registrierung, Screens unter web/ (eine Datei pro Screen), Handler unter handlers/, " +
-    `Domain-Logik unter lib/. Custom-Screens brauchen // ${IGNORE_TAG} <Grund> (deklarative Screen-Typen sind der Default).`,
+    "Convention: feature.ts is registration only, screens live under web/ (one file per screen), handlers under handlers/, " +
+    `domain logic under lib/. Custom screens need // ${IGNORE_TAG} <reason> (declarative screen types are the default).`,
   run(files: readonly SourceFile[]) {
     const violations: GuardViolation[] = [];
     for (const sf of files) {
@@ -56,7 +56,7 @@ export const guard: AstGuard = {
             file: filePath,
             line: 1,
             message:
-              "web-Monolith am Feature-Root — Screens/Client-Def gehören unter web/ (index.ts + eine Datei pro Screen)",
+              "web monolith at feature root — screens/client def belong under web/ (index.ts + one file per screen)",
           });
         }
       }
@@ -74,7 +74,7 @@ export const guard: AstGuard = {
         violations.push({
           file: filePath,
           line: 1,
-          message: "JSX-Komponente am Feature-Root — unter web/ verschieben",
+          message: "JSX component at feature root — move it under web/",
         });
       }
 
@@ -85,7 +85,7 @@ export const guard: AstGuard = {
           violations.push({
             file: filePath,
             line: 1,
-            message: `feature.ts hat ${lines} Zeilen (max ${MAX_FEATURE_TS_LINES}) — Handler nach handlers/, Schemas nach schema/, Logik nach lib/`,
+            message: `feature.ts has ${lines} lines (max ${MAX_FEATURE_TS_LINES}) — move handlers to handlers/, schemas to schema/, logic to lib/`,
           });
         }
       }
@@ -99,11 +99,13 @@ export const guard: AstGuard = {
         // Nur r.screen-Kontext: das umgebende Call-Target muss auf .screen enden.
         const call = prop.getFirstAncestorByKind(SyntaxKind.CallExpression);
         if (call === undefined || !call.getExpression().getText().endsWith(".screen")) continue;
+        // Only the screen's own config declares its type; nested `{ type: "custom" }` objects are widget config.
+        if (prop.getParent() !== call.getArguments()[0]) continue;
         if (hasIgnoreTag(call, IGNORE_TAG) || hasIgnoreTag(prop, IGNORE_TAG)) continue;
         violations.push({
           file: filePath,
           line: prop.getStartLineNumber(),
-          message: `r.screen type:"custom" ohne Allowlist-Tag — deklarativen Screen-Typ nutzen oder // ${IGNORE_TAG} <Grund>`,
+          message: `r.screen type:"custom" without allowlist tag — use a declarative screen type or // ${IGNORE_TAG} <reason>`,
         });
       }
     }

package/src/guard-direct-fetch.ts

@@ -118,7 +118,7 @@ export const guard: AstGuard = {
   hint:
     "Replace raw fetch(...) with egress(policy)(...) from @cosmicdrift/kumiko-framework/http (framework#2147). " +
     'Same-origin path literal (`"/api/..."`) is allowed; otherwise put `// guard-allow: same-origin fetch` on the line above. ' +
-    "Local bindings named fetch are flagged (false positive — unblock via that marker or ALLOWLIST in infra/guards/guard-direct-fetch.ts). " +
+    "Local bindings named fetch are flagged (false positive — unblock via that marker). " +
     'Known gap: bracket access (globalThis["fetch"](...)).',
   run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
     const violations: Array<{ file: string; line: number; message: string }> = [];

package/src/guard-error-reasons.ts

@@ -60,6 +60,10 @@ const UNPROC_CALL_NAMES = new Set(["UnprocessableError", "failUnprocessable"]);
 // justification, not an error-reason code.
 const ACCESS_DECLARATION_NAMES = new Set(["openToAll", "escapeHatch"]);
 
+// Calls whose object-literal argument carries a prose `reason` for an
+// access grant / escape hatch.
+const ACCESS_DECLARATION_CALLS = new Set(["declareEscapeHatch", "withUnsafeRawGrant"]);
+
 interface Violation {
   readonly file: string;
   readonly line: number;
@@ -135,8 +139,8 @@ function scanFile(sf: SourceFile): Violation[] {
 }
 
 // A `reason` PropertyAssignment whose object literal is the initializer of
-// an `openToAll` / `escapeHatch` PropertyAssignment, or the sole argument
-// object of a bare `declareEscapeHatch(...)` call, is an access-declaration
+// an `openToAll` / `escapeHatch` PropertyAssignment, or an argument
+// object of a bare `declareEscapeHatch(...)` / `withUnsafeRawGrant(...)` call, is an access-declaration
 // justification, not an error-reason code.
 export function isAccessDeclarationReason(prop: Node): boolean {
   const objectLiteral = prop.getParent();
@@ -147,7 +151,7 @@ export function isAccessDeclarationReason(prop: Node): boolean {
   }
   if (owner?.isKind(SyntaxKind.CallExpression)) {
     const callee = owner.getExpression();
-    return callee.isKind(SyntaxKind.Identifier) && callee.getText() === "declareEscapeHatch";
+    return callee.isKind(SyntaxKind.Identifier) && ACCESS_DECLARATION_CALLS.has(callee.getText());
   }
   return false;
 }