@cosmicdrift/kumiko-guards 0.363.0 → 0.364.0

package/src/guard-comment-lang.ts

@@ -36,12 +36,16 @@ const SCAN: ScanSpec = {
 
 const EXCLUDE = /(\.d\.(ts|tsx)$|\/dist\/)/;
 
+// Case-sensitive lower case: an upper-case licence name or a capitalised name
+// must not count, and a single short marker that is also an English word is
+// not enough.
 const DE_MARKER_RE =
-  /\b(und|oder|für|wenn|nicht|dann|auch|noch|wird|sind|mit|zum|zur|bei|nach|ohne|über|kein|eine|einen|dieser|diese)\b/i;
+  /\b(und|oder|für|wenn|nicht|dann|auch|noch|wird|sind|mit|zum|zur|bei|nach|ohne|über|kein|eine|einen|dieser|diese)\b/g;
+const MIN_DE_MARKER_HITS = 2;
 const UMLAUT_RE = /[äöüÄÖÜß]/;
 
 export function isGermanComment(text: string): boolean {
-  return DE_MARKER_RE.test(text) || UMLAUT_RE.test(text);
+  return UMLAUT_RE.test(text) || (text.match(DE_MARKER_RE)?.length ?? 0) >= MIN_DE_MARKER_HITS;
 }
 
 export type Site = {
@@ -68,13 +72,8 @@ function germanCommentSite(
   };
 }
 
-// After these tokens a `/` is division, not the start of a regex literal.
-const DIVISION_PRECEDING_KINDS: ReadonlySet<ts.SyntaxKind> = new Set([
-  ts.SyntaxKind.Identifier,
-  ts.SyntaxKind.ThisKeyword,
-  ts.SyntaxKind.TrueKeyword,
-  ts.SyntaxKind.FalseKeyword,
-  ts.SyntaxKind.NullKeyword,
+// Tokens that end an operand without being identifiers or keywords.
+const OPERAND_END_PUNCTUATION_KINDS: ReadonlySet<ts.SyntaxKind> = new Set([
   ts.SyntaxKind.NumericLiteral,
   ts.SyntaxKind.BigIntLiteral,
   ts.SyntaxKind.StringLiteral,
@@ -88,6 +87,42 @@ const DIVISION_PRECEDING_KINDS: ReadonlySet<ts.SyntaxKind> = new Set([
   ts.SyntaxKind.MinusMinusToken,
 ]);
 
+// Reserved words after which an expression (so possibly a regex) starts.
+const EXPRESSION_INTRODUCING_KEYWORDS: ReadonlySet<ts.SyntaxKind> = new Set([
+  ts.SyntaxKind.ReturnKeyword,
+  ts.SyntaxKind.TypeOfKeyword,
+  ts.SyntaxKind.InstanceOfKeyword,
+  ts.SyntaxKind.InKeyword,
+  ts.SyntaxKind.CaseKeyword,
+  ts.SyntaxKind.VoidKeyword,
+  ts.SyntaxKind.DeleteKeyword,
+  ts.SyntaxKind.ThrowKeyword,
+  ts.SyntaxKind.NewKeyword,
+  ts.SyntaxKind.YieldKeyword,
+  ts.SyntaxKind.AwaitKeyword,
+  ts.SyntaxKind.ElseKeyword,
+  ts.SyntaxKind.DoKeyword,
+  ts.SyntaxKind.ExtendsKeyword,
+  ts.SyntaxKind.DefaultKeyword,
+]);
+
+function isIdentifierOrKeyword(kind: ts.SyntaxKind): boolean {
+  return (
+    kind === ts.SyntaxKind.Identifier ||
+    (kind >= ts.SyntaxKind.FirstKeyword && kind <= ts.SyntaxKind.LastKeyword)
+  );
+}
+
+// After an operand end a `/` is division, not the start of a regex literal.
+// Contextual keywords (`from`, `type`, `of`, ...) scan as keyword kinds but are
+// valid member and variable names, so every non-introducing keyword counts. A `!`
+// is the non-null postfix only when the token before it ended an operand.
+function isOperandEnd(kind: ts.SyntaxKind, previousEndedOperand: boolean): boolean {
+  if (kind === ts.SyntaxKind.ExclamationToken) return previousEndedOperand;
+  if (OPERAND_END_PUNCTUATION_KINDS.has(kind)) return true;
+  return isIdentifierOrKeyword(kind) && !EXPRESSION_INTRODUCING_KEYWORDS.has(kind);
+}
+
 const TRIVIA_KINDS: ReadonlySet<ts.SyntaxKind> = new Set([
   ts.SyntaxKind.SingleLineCommentTrivia,
   ts.SyntaxKind.MultiLineCommentTrivia,
@@ -101,11 +136,9 @@ const TRIVIA_KINDS: ReadonlySet<ts.SyntaxKind> = new Set([
 function rescanSlashAsRegex(
   scanner: ts.Scanner,
   kind: ts.SyntaxKind,
-  previousSignificant: ts.SyntaxKind | undefined,
+  previousEndedOperand: boolean,
 ): ts.SyntaxKind {
-  if (previousSignificant !== undefined && DIVISION_PRECEDING_KINDS.has(previousSignificant)) {
-    return kind;
-  }
+  if (previousEndedOperand) return kind;
   const reScanned = scanner.reScanSlashToken();
   return reScanned === ts.SyntaxKind.RegularExpressionLiteral ? reScanned : kind;
 }
@@ -135,7 +168,7 @@ export function scanGermanComments(fullText: string, file: string): Site[] {
 
   const templateBraceDepths: number[] = [];
   let braceDepth = 0;
-  let previousSignificant: ts.SyntaxKind | undefined;
+  let previousEndedOperand = false;
 
   let kind = scanner.scan();
   while (kind !== ts.SyntaxKind.EndOfFileToken) {
@@ -153,7 +186,7 @@ export function scanGermanComments(fullText: string, file: string): Site[] {
       }
       case ts.SyntaxKind.SlashToken:
       case ts.SyntaxKind.SlashEqualsToken:
-        kind = rescanSlashAsRegex(scanner, kind, previousSignificant);
+        kind = rescanSlashAsRegex(scanner, kind, previousEndedOperand);
         break;
       case ts.SyntaxKind.TemplateHead:
       case ts.SyntaxKind.TemplateMiddle:
@@ -173,7 +206,7 @@ export function scanGermanComments(fullText: string, file: string): Site[] {
       default:
         break;
     }
-    if (!TRIVIA_KINDS.has(kind)) previousSignificant = kind;
+    if (!TRIVIA_KINDS.has(kind)) previousEndedOperand = isOperandEnd(kind, previousEndedOperand);
     kind = scanner.scan();
   }
   return sites;
@@ -234,21 +267,20 @@ function gitOrFail(args: readonly string[], cwd: string, message: string): strin
 const REWRITE_HINT = `Translate new German comments to English (why, not what), or if deliberate:\n    // ${IGNORE_TAG} <reason>`;
 
 function runTouchedMode(
-  all: readonly Site[],
   argv: readonly string[],
   root: string,
-  repoLocalScannedFiles: number,
+  repoLocalScannedFiles: ReadonlySet<string>,
 ): number {
   const baseArg = argv.find((arg) => arg.startsWith(BASE_FLAG_PREFIX));
   const baseRef = baseArg ? baseArg.slice(BASE_FLAG_PREFIX.length) : "origin/main";
   if (baseRef.startsWith("-")) {
     throw new CommentLangFailure(
-      `--base must not start with "-" (${baseRef}): it would be read as a git option, not a ref.`,
+      `--base must not start with "-" (${baseRef}): it would be read as a git option, not a ref. Pass a ref name such as origin/main.`,
     );
   }
 
   // No repo-local file scanned at all must not read as clean (vacuous pass).
-  if (repoLocalScannedFiles === 0) {
+  if (repoLocalScannedFiles.size === 0) {
     console.log("  Touched mode: 0 repo-local files scanned — not applicable, no failure.");
     return 0;
   }
@@ -256,7 +288,7 @@ function runTouchedMode(
   const gitToplevel = gitOrFail(
     ["rev-parse", "--show-toplevel"],
     root,
-    "Touched mode: no git repository found.",
+    "Touched mode: no git repository found. Run it inside a git checkout.",
   ).trim();
   const mergeBase = gitOrFail(
     ["merge-base", baseRef, "HEAD"],
@@ -265,35 +297,37 @@ function runTouchedMode(
   ).trim();
   // -z: NUL-terminated and unquoted, so non-ASCII paths still match the lookup below.
   const touchedFiles = gitOrFail(
-    ["diff", "--name-only", "-z", "--diff-filter=ACMR", mergeBase],
+    ["diff", "--name-only", "-z", "--diff-filter=ACMR", mergeBase, "HEAD"],
     gitToplevel,
-    "Touched mode: git diff --name-only failed.",
+    "Touched mode: git diff --name-only failed. Check the git error below and that the base ref is reachable.",
   )
     .split("\0")
     .filter(Boolean);
 
-  // Sites are keyed relative to root, git output relative to the toplevel;
-  // a silent mismatch would read as "no violations".
-  const sitesByGitFile = new Map<string, Site[]>();
-  for (const site of all.filter(isLocalFinding)) {
-    const gitRelPath = path.relative(gitToplevel, path.resolve(root, site.file));
-    sitesByGitFile.set(gitRelPath, [...(sitesByGitFile.get(gitRelPath) ?? []), site]);
-  }
-
+  // The commits being pushed are checked, not the working tree: contents come from
+  // HEAD so line numbers match the `mergeBase..HEAD` diff. Scan scope is keyed
+  // relative to root, git output relative to the toplevel.
   const violations: Array<{ file: string; sites: Site[] }> = [];
   for (const file of touchedFiles) {
-    const candidates = sitesByGitFile.get(file);
-    if (!candidates || candidates.length === 0) continue;
+    const rootRelFile = path.relative(root, path.resolve(gitToplevel, file));
+    if (!repoLocalScannedFiles.has(rootRelFile)) continue;
     // --literal-pathspecs: filenames with glob magic must match themselves.
+    const headContent = gitOrFail(
+      ["--literal-pathspecs", "show", `HEAD:${file}`],
+      gitToplevel,
+      `Touched mode: git show HEAD:${file} failed. Check the git error below.`,
+    );
+    const candidates = scanGermanComments(headContent, rootRelFile);
+    if (candidates.length === 0) continue;
     const addedLines = parseAddedLineRanges(
       gitOrFail(
-        ["--literal-pathspecs", "diff", "--unified=0", mergeBase, "--", file],
+        ["--literal-pathspecs", "diff", "--unified=0", mergeBase, "HEAD", "--", file],
         gitToplevel,
-        `Touched mode: git diff --unified=0 failed for ${file}.`,
+        `Touched mode: git diff --unified=0 failed for ${file}. Check the git error below.`,
       ),
     );
     const touchedSites = sitesTouchedByAddedLines(candidates, addedLines);
-    if (touchedSites.length > 0) violations.push({ file, sites: touchedSites });
+    if (touchedSites.length > 0) violations.push({ file: rootRelFile, sites: touchedSites });
   }
 
   if (violations.length === 0) {
@@ -470,25 +504,27 @@ export function runCommentLangCli(
   try {
     const all: Site[] = [];
     let scanned = 0;
-    let repoLocalScanned = 0;
+    const repoLocalScanned = new Set<string>();
     for (const absPath of scanFiles(SCAN, resolveRepoRoots(root))) {
       if (EXCLUDE.test(absPath)) continue;
       scanned++;
       const file = path.relative(root, absPath);
-      if (isLocalFinding({ file })) repoLocalScanned++;
+      if (isLocalFinding({ file })) repoLocalScanned.add(file);
       all.push(...scanGermanComments(readFileSync(absPath, "utf-8"), file));
     }
 
     // Zero scanned files must not read as a clean pass (misresolved root, empty scope).
     if (scanned === 0) {
-      throw new CommentLangFailure("Scanned 0 files — repo root or scan scope did not resolve.");
+      throw new CommentLangFailure(
+        "Scanned 0 files — repo root or scan scope did not resolve. Run it from inside a repo checkout whose kumiko.json declares the source roots.",
+      );
     }
 
     console.log(
       `Comment-Language Audit: ${scanned} files checked, ${all.length} German comment(s) found.`,
     );
 
-    if (argv.includes("--touched")) return runTouchedMode(all, argv, root, repoLocalScanned);
+    if (argv.includes("--touched")) return runTouchedMode(argv, root, repoLocalScanned);
     if (argv.includes("--list")) {
       for (const site of all.slice(0, LIST_LIMIT)) {
         console.log(`  ${site.file}:${site.line}  ${site.snippet}`);

package/src/guard-direct-entity-writes.ts

@@ -461,6 +461,9 @@ export const guard: AstGuard = {
   name: "Direct-Entity-Writes Guard",
   scan: SCAN,
   security: true,
+  hint:
+    "Write ES-entity tables through the entity write handlers / event-store executor or inside an r.projection apply (tx receiver); a direct insert/update/delete lets the projection row drift from the event stream. " +
+    "For a BLOCKED scan, check that the scan still covers the files declaring r.entity / createEventStoreExecutor.",
   run(files) {
     // Merge both collections BEFORE the empty-set check — otherwise a repo
     // that only uses r.entity (no createEventStoreExecutor anymore) would

package/src/guard-pre-es-patterns.ts

@@ -163,6 +163,9 @@ const PATTERNS: readonly Pattern[] = [
 export const guard: AstGuard = {
   name: "Pre-ES-Patterns Guard",
   scan: SCAN,
+  hint:
+    "These APIs were removed with the event-sourcing migration. Use the events table with ctx.loadAggregate / queryProjection, ctx.appendEvent on aggregate streams, " +
+    'r.multiStreamProjection for cross-aggregate consumers, and configValue.created/updated/deleted events (aggregateType: "configValue") for config changes.',
   run(files) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
 

package/src/guard-public-exports-changelog.ts

@@ -270,7 +270,7 @@ function scanPackage(cwd: string, project: Project, pkg: PackageName): PackageSc
     pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
   } catch (e) {
     console.error(
-      `  ${pkg}: package.json unreadable (${e instanceof Error ? e.message : String(e)}).`,
+      `  ${pkg}: package.json unreadable (${e instanceof Error ? e.message : String(e)}). Fix the file so it is valid JSON.`,
     );
     return null;
   }
@@ -320,7 +320,9 @@ export type EvaluateResult = {
 
 function buildFinding(missing: MissingExport, version: string): UncoveredFinding {
   if (!isPackageName(missing.pkg)) {
-    throw new Error(`baseline package key not in scope: ${missing.pkg}`);
+    throw new Error(
+      `baseline package key not in scope: ${missing.pkg}. Remove the key from the baseline or re-freeze it with --write-baseline.`,
+    );
   }
   const pkg = missing.pkg;
   const changelogPath = owningChangelogPath(pkg, missing.key);
@@ -370,7 +372,7 @@ function findingsAgainstBaseline(
   for (const [pkg, keys] of Object.entries(baseline.packages)) {
     if (!isPackageName(pkg)) {
       console.error(
-        `  Baseline contains unknown package key "${pkg}", ignored (only framework|bundled-features).`,
+        `  Baseline contains unknown package key "${pkg}", ignored (only framework|bundled-features). Remove the key from the baseline or re-freeze it with --write-baseline.`,
       );
       continue;
     }
@@ -397,7 +399,9 @@ export function evaluatePublicExportsChangelog(args: {
   logOutOfScopeNotice();
   const scans = scanAllPackages(args.cwd, args.project);
   if (scans.length === 0 && args.mode === "check") {
-    console.error("  No package scanned: the guard would pass vacuously.");
+    console.error(
+      "  No package scanned: the guard would pass vacuously. Run it from a kumiko-framework checkout that contains the framework package.",
+    );
     return { scans, baselineStatus: "ok", findings: [vacuousFinding()] };
   }
 
@@ -441,11 +445,16 @@ export async function loadChangesetParser(frameworkRootAbsPath: string): Promise
     frameworkRootAbsPath,
     "packages/framework/src/engine/changeset-changes.ts",
   );
-  if (!existsSync(parserPath)) throw new Error(`changeset parser not found: ${parserPath}`);
+  if (!existsSync(parserPath))
+    throw new Error(
+      `changeset parser not found: ${parserPath}. Run the guard from a complete kumiko-framework checkout.`,
+    );
   const loaded: unknown = await import(pathToFileURL(parserPath).href);
   const parse = isRecord(loaded) ? loaded["parseChangesetChanges"] : undefined;
   if (!isChangesetParser(parse)) {
-    throw new Error(`${parserPath} does not export parseChangesetChanges as a function`);
+    throw new Error(
+      `${parserPath} does not export parseChangesetChanges as a function. Export it from that file.`,
+    );
   }
   return parse;
 }
@@ -560,7 +569,7 @@ export function writeBaseline(
   const frameworkScan = scans.find((s) => s.pkg === "framework");
   if (!frameworkScan) {
     console.error(
-      "  framework package.json missing: asOfVersion undetermined, baseline not written.",
+      "  framework package.json missing: asOfVersion undetermined, baseline not written. Run it from a kumiko-framework checkout.",
     );
     return 1;
   }
@@ -665,7 +674,9 @@ export async function runPublicExportsChangelogCli(
   }
   const tsConfigFilePath = frameworkTsConfigPath(cwd);
   if (tsConfigFilePath === undefined) {
-    console.error("  public-exports-changelog: framework tsconfig.json not found.");
+    console.error(
+      "  public-exports-changelog: framework tsconfig.json not found. Run it from a complete kumiko-framework checkout.",
+    );
     return 1;
   }
   const project = new Project({ tsConfigFilePath, skipAddingFilesFromTsConfig: true });
@@ -676,7 +687,9 @@ export async function runPublicExportsChangelogCli(
     try {
       pending = await loadPendingBreakingChanges(scanCwd);
     } catch (e) {
-      console.error(`  Cannot read open changesets: ${e instanceof Error ? e.message : String(e)}`);
+      console.error(
+        `  Cannot read open changesets: ${e instanceof Error ? e.message : String(e)}. Fix the changeset file named above.`,
+      );
       return 1;
     }
     return writeBaseline(scanCwd, project, join(scanCwd, BASELINE_FILE), pending);

package/src/guard-thin-wrappers.ts

@@ -377,6 +377,9 @@ const SCAN: ScanSpec = {
   frameworkWithin: ["packages/*/src/**"],
 };
 
+const WRAPPER_FIX =
+  "call the delegate directly, or mark a deliberate wrapper with // @wrapper-known <reason>";
+
 export const check: RepoCheck = {
   name: "Thin-Wrappers Guard",
   run(roots) {
@@ -403,12 +406,16 @@ export const check: RepoCheck = {
       scanned++;
       for (const f of collectFindings(sf)) {
         if (f.markerReason === null) {
-          warnings.push({ file: f.file, line: f.line, message: `${f.fnName} → ${f.callee}` });
+          warnings.push({
+            file: f.file,
+            line: f.line,
+            message: `${f.fnName} → ${f.callee}  (${WRAPPER_FIX})`,
+          });
         } else if (!isKnownReason(f.markerReason)) {
           warnings.push({
             file: f.file,
             line: f.line,
-            message: `${f.fnName} → ${f.callee}  (reason="${f.markerReason}")`,
+            message: `${f.fnName} → ${f.callee}  (reason="${f.markerReason}"; use a known reason from the list in this guard)`,
           });
         }
       }

package/src/guard-upgrade-state.ts

@@ -21,6 +21,7 @@
  *   bun guard-upgrade-state.ts
  */
 
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import {
@@ -84,19 +85,45 @@ export function isUpgradeJson(value: unknown): value is UpgradeJson {
   );
 }
 
-export function isPendingManualStep(value: unknown): value is PendingManualStep {
-  if (!isRecord(value)) return false;
-  return (
-    typeof value["id"] === "string" &&
-    value["id"].length > 0 &&
-    typeof value["version"] === "string" &&
-    typeof value["title"] === "string"
-  );
+// Same id scheme as manualEntryId in @cosmicdrift/kumiko-framework/upgrade-cli. Duplicated because
+// this package must stay installable without the framework; a test pins both to the same value.
+const MANUAL_ID_HASH_LENGTH = 8;
+
+export function manualEntryId(version: string, title: string): string {
+  const hash = createHash("sha256").update(title).digest("hex").slice(0, MANUAL_ID_HASH_LENGTH);
+  return `${version}:${hash}`;
 }
 
-function readPendingManual(parsed: unknown): readonly PendingManualStep[] {
+/** Markers written before entries carried an `id` get the id the CLI derives for them. */
+export function parsePendingManualStep(value: unknown): PendingManualStep | null {
+  if (!isRecord(value)) return null;
+  const { id, version, title } = value;
+  if (typeof version !== "string" || typeof title !== "string") return null;
+  return {
+    id: typeof id === "string" && id.length > 0 ? id : manualEntryId(version, title),
+    version,
+    title,
+  };
+}
+
+function readPendingManual(
+  parsed: unknown,
+): { readonly steps: readonly PendingManualStep[] } | { readonly error: string } {
   const raw = isRecord(parsed) ? parsed["pendingManual"] : undefined;
-  return Array.isArray(raw) ? raw.filter(isPendingManualStep) : [];
+  if (raw === undefined) return { steps: [] };
+  if (!Array.isArray(raw))
+    return { error: `${MARKER_REL} has a "pendingManual" that is not an array` };
+  const steps: PendingManualStep[] = [];
+  for (const [index, entry] of raw.entries()) {
+    const step = parsePendingManualStep(entry);
+    if (step === null) {
+      return {
+        error: `${MARKER_REL} has a malformed pendingManual entry at index ${index} (needs string "version" and "title")`,
+      };
+    }
+    steps.push(step);
+  }
+  return { steps };
 }
 
 export function readMarker(root: string): UpgradeMarker | { error: string } {
@@ -118,7 +145,9 @@ export function readMarker(root: string): UpgradeMarker | { error: string } {
       error: `${MARKER_REL} is missing a valid "version" field (expected semver x.y.z[-pre][+build]) — broken marker file`,
     };
   }
-  return { version, pendingManual: readPendingManual(parsed) };
+  const pendingManual = readPendingManual(parsed);
+  if ("error" in pendingManual) return pendingManual;
+  return { version, pendingManual: pendingManual.steps };
 }
 
 /** Pending changelog entries turned into guard violations — pure, testable without a subprocess. */

package/src/index.ts

@@ -1,3 +1,4 @@
+export { AGENT_DOCS_DIR, renderAgentDocs, writeAgentDocs } from "./_lib/agent-docs";
 export { gitEnv } from "./_lib/git-env";
 export {
   type AstGuard,

package/src/pre-push.sh

@@ -18,6 +18,9 @@
 #      sub-repo's own package.json `test` script — refuses the push if that
 #      script is missing.
 #
+# Before the checks below, the hook runs a gitleaks scan of origin/main..HEAD
+# when the binary is installed.
+#
 # Extension point: a tracked, executable scripts/pre-push-extra.sh runs
 # before the main check in every branch above, with KUMIKO_PUSH_REPO_ROOT
 # and KUMIKO_PUSH_PARENT_DIR available inline (never exported).
@@ -118,6 +121,22 @@ if [ -f "$REPO_ROOT/.kumiko/upgrade-state.json" ]; then
   fi
 fi
 
+# Secret scan: runs before check-wt.sh/bun check so a leaked credential is
+# caught in seconds, not after the long checks. A missing binary or a missing
+# origin/main only warns, so a machine without gitleaks is not locked out.
+# No --config: gitleaks reads a .gitleaks.toml in the repo root itself.
+if ! command -v gitleaks >/dev/null 2>&1; then
+  echo "[pre-push] gitleaks not installed — secret scan skipped. Install: brew install gitleaks" >&2
+elif ! git -C "$REPO_ROOT" rev-parse --verify --quiet origin/main >/dev/null 2>&1; then
+  echo "[pre-push] origin/main not found — secret scan skipped" >&2
+else
+  echo "[pre-push] gitleaks git origin/main..HEAD"
+  if ! (cd "$REPO_ROOT" && gitleaks git --no-banner --redact --log-opts="origin/main..HEAD" .); then
+    echo "[pre-push] gitleaks found secrets — refusing push" >&2
+    exit 1
+  fi
+fi
+
 # infra#559/#569: from a worktree, `--git-common-dir` resolves to the main
 # checkout's .git, so the branch below would scope `bun check` to the
 # canonical sibling path instead of this worktree — checking the wrong

package/src/run-repo-checks.ts

@@ -7,6 +7,7 @@ import { check as realProviderIsolation } from "./check-real-provider-isolation"
 import { check as runtimeIsolation } from "./check-runtime-isolation";
 import { check as secretLiterals } from "./check-secret-literals";
 import { check as singleRuntimeInstance } from "./check-single-runtime-instance";
+import { check as agentDocsDrift } from "./guard-agent-docs-drift";
 import { check as featureIntegrationTests } from "./guard-feature-integration-tests";
 import { check as noDirectProcessEnv } from "./guard-no-direct-process-env";
 import { check as primitivesDiscipline } from "./guard-primitives-discipline";
@@ -29,6 +30,7 @@ export const REPO_CHECKS = [
   upgradeState,
   realProviderIsolation,
   singleRuntimeInstance,
+  agentDocsDrift,
 ];
 
 export const REPO_CHECK_FLAGS: readonly string[] = ["--write-baseline"];