@cosmicdrift/kumiko-guards 0.386.0 → 0.388.0

package/src/check-complexity.ts

@@ -21,14 +21,14 @@
  *
  * Opt-out: `// kumiko-lint-ignore complexity-budget <reason>` on the function
  * line, the line above, or (for JSDoc-documented functions) the line above
- * the JSDoc block.
+ * the JSDoc block. The opt-out does NOT hold above HARD_COMPLEXITY_CAP: such a
+ * function in the repo's own files always fails, regardless of baseline or tag.
  *
  * Usage:
  *   bun guards/check-complexity.ts                  # compare against baseline
  *   bun guards/check-complexity.ts --write-baseline # rewrite baseline
  *   bun guards/check-complexity.ts --no-baseline    # skip comparison
- *
- * Rule: issue kumiko-framework#1282
+ *   bun guards/check-complexity.ts --all            # list every hotspot, not the first 30
  */
 
 import * as path from "node:path";
@@ -60,6 +60,7 @@ const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$)/;
 
 const COMPLEXITY_THRESHOLD = 15;
 const MAX_REPORTED = 30;
+export const HARD_COMPLEXITY_CAP = 40;
 const BUDGET_TAG = "kumiko-lint-ignore complexity-budget";
 
 const FUNCTION_KINDS = [
@@ -154,26 +155,49 @@ export function computeComplexity(fn: Node): number {
   return complexity;
 }
 
-export function collectHotspots(
+export interface FunctionMetric extends Hotspot {
+  budgetTagged: boolean;
+}
+
+// Single walk per file: complexity is computed once and feeds both the
+// hotspot list and the hard cap.
+export function collectFunctionMetrics(
   sf: SourceFile,
   roots: readonly RepoRoot[] = resolveRepoRoots(),
-): Hotspot[] {
+): FunctionMetric[] {
   const file = relFromRepoRoot(sf.getFilePath(), roots);
-  const hotspots: Hotspot[] = [];
+  const metrics: FunctionMetric[] = [];
   for (const kind of FUNCTION_KINDS) {
     for (const fn of sf.getDescendantsOfKind(kind)) {
       const complexity = computeComplexity(fn);
       if (complexity < COMPLEXITY_THRESHOLD) continue;
-      if (hasBudgetTag(fn)) continue;
-      hotspots.push({
+      metrics.push({
         file,
         line: fn.getStartLineNumber(),
         name: functionName(fn),
         complexity,
+        budgetTagged: hasBudgetTag(fn),
       });
     }
   }
-  return hotspots;
+  return metrics;
+}
+
+export function hotspotsOf(metrics: readonly FunctionMetric[]): Hotspot[] {
+  return metrics
+    .filter((m) => !m.budgetTagged)
+    .map(({ file, line, name, complexity }) => ({ file, line, name, complexity }));
+}
+
+export function capBreachesOf(metrics: readonly FunctionMetric[]): FunctionMetric[] {
+  return metrics.filter((m) => m.complexity > HARD_COMPLEXITY_CAP && isLocalFinding(m));
+}
+
+export function collectHotspots(
+  sf: SourceFile,
+  roots: readonly RepoRoot[] = resolveRepoRoots(),
+): Hotspot[] {
+  return hotspotsOf(collectFunctionMetrics(sf, roots));
 }
 
 const BASELINE_FILE = ".kumiko-complexity-baseline.json";
@@ -201,26 +225,37 @@ function scan(
   roots: readonly RepoRoot[] = resolveRepoRoots(),
 ): {
   hotspots: Hotspot[];
+  capBreaches: FunctionMetric[];
   scanned: number;
 } {
-  const hotspots: Hotspot[] = [];
+  const metrics: FunctionMetric[] = [];
   let scanned = 0;
   for (const sf of files) {
     if (EXCLUDE.test(sf.getFilePath())) continue;
     scanned++;
-    hotspots.push(...collectHotspots(sf, roots));
+    metrics.push(...collectFunctionMetrics(sf, roots));
   }
-  hotspots.sort((a, b) => b.complexity - a.complexity);
-  return { hotspots, scanned };
+  const hotspots = hotspotsOf(metrics).sort((a, b) => b.complexity - a.complexity);
+  const capBreaches = capBreachesOf(metrics).sort((a, b) => b.complexity - a.complexity);
+  return { hotspots, capBreaches, scanned };
 }
 
-function report(hotspots: readonly Hotspot[], scanned: number): void {
+function report(
+  hotspots: readonly Hotspot[],
+  scanned: number,
+  capBreaches: readonly FunctionMetric[],
+  reportLimit: number,
+): void {
   console.log(`Complexity Check: ${scanned} files checked.`);
   console.log(`  Hotspots (complexity >= ${COMPLEXITY_THRESHOLD}): ${hotspots.length}`);
+  console.log(`  Above hard cap (complexity > ${HARD_COMPLEXITY_CAP}): ${capBreaches.length}`);
+  for (const b of capBreaches) {
+    console.log(`    CAP ${b.file}:${b.line}  ${b.name}()  complexity=${b.complexity}`);
+  }
   if (hotspots.length === 0) {
     console.log("  Nothing to report.");
   } else {
-    const shown = hotspots.slice(0, MAX_REPORTED);
+    const shown = hotspots.slice(0, reportLimit);
     for (const h of shown) {
       console.log(`    ${h.file}:${h.line}  ${h.name}()  complexity=${h.complexity}`);
     }
@@ -233,12 +268,25 @@ function report(hotspots: readonly Hotspot[], scanned: number): void {
   }
 }
 
+type Ratchet = ReturnType<typeof baselineRatchet>;
+
 const complexityBaseline = baselineRatchet({
   file: path.join(ROOT, BASELINE_FILE),
   formatVersion: BASELINE_FORMAT_VERSION,
   unit: "Complexity-Hotspot(s)",
 });
 
+function capViolations(capBreaches: readonly FunctionMetric[]): GuardViolation[] {
+  return capBreaches.map((b) => ({
+    file: b.file,
+    line: b.line,
+    neverFrozen: true,
+    message:
+      `${b.name}() has complexity ${b.complexity}, above the hard cap of ${HARD_COMPLEXITY_CAP}. ` +
+      `A "${BUDGET_TAG}" tag and the baseline do not apply above the cap — split the function.`,
+  }));
+}
+
 // `scan` sorts by complexity descending, so the first hit for a file is its
 // worst function — the one the violation should point at, not whichever
 // hotspot happens to come first in the file.
@@ -246,9 +294,9 @@ export function resolveHotspotLine(hotspots: readonly Hotspot[], file: string):
   return hotspots.find((h) => h.file === file)?.line ?? 1;
 }
 
-function checkBaseline(scanned: readonly Hotspot[]): GuardViolation[] {
+function checkBaseline(scanned: readonly Hotspot[], ratchet: Ratchet): GuardViolation[] {
   const hotspots = localHotspots(scanned);
-  return complexityBaseline.check(
+  return ratchet.check(
     countHotspotsByFile(hotspots),
     `Split the function, or allow it with "// ${BUDGET_TAG} <reason>".`,
     {
@@ -258,18 +306,21 @@ function checkBaseline(scanned: readonly Hotspot[]): GuardViolation[] {
   );
 }
 
-function analyse(
+export function analyse(
   files: readonly SourceFile[],
   roots: readonly RepoRoot[],
   compareBaseline: boolean,
+  options: { ratchet?: Ratchet; reportLimit?: number } = {},
 ): GuardOutcome {
-  const { hotspots, scanned } = scan(files, roots);
-  report(hotspots, scanned);
+  const { ratchet = complexityBaseline, reportLimit = MAX_REPORTED } = options;
+  const { hotspots, capBreaches, scanned } = scan(files, roots);
+  report(hotspots, scanned, capBreaches, reportLimit);
+  const hardViolations = capViolations(capBreaches);
   if (!compareBaseline) {
     console.log("  Baseline comparison skipped (--no-baseline).");
-    return { violations: [] };
+    return { violations: hardViolations };
   }
-  return { violations: checkBaseline(hotspots) };
+  return { violations: [...hardViolations, ...checkBaseline(hotspots, ratchet)] };
 }
 
 export const guard: AstGuard = {
@@ -281,8 +332,8 @@ export const guard: AstGuard = {
   hint: 'after a deliberate change: `kumiko-guards guards --write-baseline --guard="Complexity Check"`',
   run: (files, roots = resolveRepoRoots()) => analyse(files, roots, true),
   writeBaseline: (files) => {
-    const { hotspots, scanned } = scan(files);
-    report(hotspots, scanned);
+    const { hotspots, capBreaches, scanned } = scan(files);
+    report(hotspots, scanned, capBreaches, MAX_REPORTED);
     complexityBaseline.write(countHotspotsByFile(localHotspots(hotspots)));
   },
 };
@@ -292,17 +343,23 @@ export const guard: AstGuard = {
 // silently rewrite the baseline.
 if (import.meta.main) {
   const args = process.argv.slice(2);
+  const reportLimit = args.includes("--all") ? Number.POSITIVE_INFINITY : MAX_REPORTED;
   if (args.includes("--write-baseline")) {
     const project = buildSharedProject([guard]);
-    const { hotspots, scanned } = scan(filesForGuard(project, guard));
-    report(hotspots, scanned);
+    const { hotspots, capBreaches, scanned } = scan(filesForGuard(project, guard));
+    report(hotspots, scanned, capBreaches, reportLimit);
     complexityBaseline.write(countHotspotsByFile(localHotspots(hotspots)));
     process.exit(0);
   }
   if (args.includes("--no-baseline")) {
     const project = buildSharedProject([guard]);
-    analyse(filesForGuard(project, guard), resolveRepoRoots(), false);
-    process.exit(0);
+    const { violations } = analyse(filesForGuard(project, guard), resolveRepoRoots(), false, {
+      reportLimit,
+    });
+    process.exit(violations.length > 0 ? 1 : 0);
   }
-  runStandalone(guard);
+  runStandalone({
+    ...guard,
+    run: (files, roots = resolveRepoRoots()) => analyse(files, roots, true, { reportLimit }),
+  });
 }

package/src/check-licenses.ts

@@ -107,14 +107,30 @@ export function loadLicenseExceptions(
   });
 }
 
+function normalizeLicenseId(license: string): string {
+  return license.replace(/[()]/g, "").trim().toUpperCase();
+}
+
+function exceptionMatchesPackage(e: LicenseException, pkg: InstalledPackage): boolean {
+  if (!matchesPackageName(e.package, pkg.name)) return false;
+  // A package without a license field has nothing to contradict the recorded license.
+  if (pkg.license !== null && normalizeLicenseId(e.license) !== normalizeLicenseId(pkg.license)) {
+    return false;
+  }
+  return (
+    e.version === "*" || e.version === pkg.version || Bun.semver.satisfies(pkg.version, e.version)
+  );
+}
+
+// A renewed repo exception must win over an expired bundled one for the same package, so prefer a
+// still-valid match and only fall back to an expired one for the "expired" hint.
 function findException(
   pkg: InstalledPackage,
   exceptions: readonly LicenseException[],
+  nowMs: number,
 ): LicenseException | undefined {
-  return exceptions.find((e) => {
-    if (!matchesPackageName(e.package, pkg.name)) return false;
-    return e.version === "*" || e.version === pkg.version || /^[\^~]/.test(e.version);
-  });
+  const matching = exceptions.filter((e) => exceptionMatchesPackage(e, pkg));
+  return matching.find((e) => isExceptionValid(e.expires, nowMs).valid) ?? matching[0];
 }
 
 function splitExpression(expr: string, operator: "OR" | "AND"): string[] {
@@ -132,9 +148,10 @@ function matchesDenylist(license: string): boolean {
 export function judgeLicense(
   pkg: InstalledPackage,
   exceptions: readonly LicenseException[],
+  nowMs: number = Date.now(),
 ): Verdict {
   const license = pkg.license;
-  const exception = findException(pkg, exceptions);
+  const exception = findException(pkg, exceptions, nowMs);
   if (!license) return { kind: "unknown", raw: null, exception };
 
   const andParts = splitExpression(license, "AND");
@@ -181,7 +198,7 @@ export function evaluateLicenses(
   exceptions: readonly LicenseException[],
   nowMs: number = Date.now(),
 ): LicenseEvaluation {
-  const judged = packages.map((pkg) => ({ pkg, verdict: judgeLicense(pkg, exceptions) }));
+  const judged = packages.map((pkg) => ({ pkg, verdict: judgeLicense(pkg, exceptions, nowMs) }));
   const blocked = judged.filter(
     ({ verdict }) => verdict.kind !== "ok" && !hasValidException(verdict, nowMs),
   );

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 /**
- * Real-Provider-Isolation-Guard (stack-agnostisch, #3118).
+ * Real-Provider-Isolation-Guard (stack-agnostic).
  *
  * Real-provider specs (`*.real.test.ts`, `*.real.spec.ts`) hit live third-party
  * services and must only ever run opt-in (manually or scheduled) via `bun run test:real` /

package/src/check-runtime-isolation.ts

@@ -43,8 +43,8 @@
 // A file/import edge classified "client" importing "runtime" can be a real
 // finding this guard needs to see, but can also be a known, reviewed
 // exception (e.g. samples/recipes are worked examples, not the framework's
-// own production surface — see kumiko-framework#2337 for the one currently
-// frozen here). Exceptions are tracked via a per-repo baseline file
+// own production surface — one exception is currently frozen here).
+// Exceptions are tracked via a per-repo baseline file
 // (`.kumiko-runtime-isolation-baseline.json`, same `baselineRatchet`
 // mechanism as check-complexity/etc.), not a
 // hardcoded list in this source file: a consumer repo can freeze or clear

package/src/check-security.ts

@@ -157,7 +157,8 @@ export async function runSecurityCheck(options: {
   const advisories: AuditAdvisory[] = parseAuditReport(raw);
 
   const evaluation = evaluateSecurity(advisories, exceptions, nowMs);
-  const expiringUrgent = findExpiringSoon(exceptions, EXPIRY_BLOCK_DAYS, nowMs);
+  // Only exceptions that suppressed an advisory in this run block; unused bundled ones must not break consumer CI.
+  const expiringUrgent = findExpiringSoon(evaluation.usedExceptions, EXPIRY_BLOCK_DAYS, nowMs);
   printReport(evaluation, exceptions, expiringUrgent, nowMs);
 
   if (options.reportOnly) return 0;

package/src/check-single-runtime-instance.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 /**
- * Single-Runtime-Instance Guard (kumiko-studio#229).
+ * Single-Runtime-Instance Guard.
  *
  * A Kumiko runtime library resolved at two versions in one bun.lock (a nested
  * copy under a feature package next to the top-level install) loads twice in

package/src/dependency-license-exceptions.json

@@ -41,30 +41,6 @@
       "reviewedBy": "Marc, 2026-05-06",
       "expires": "2027-05-06"
     },
-    {
-      "package": "@cosmicdriftgamestudio/*",
-      "version": "*",
-      "license": "UNLICENSED",
-      "reason": "Eigene private CDGS-Workspace-Packages (kumiko-guards, später kumiko-ai-*, kumiko-designer etc.). UNLICENSED = proprietary, kein Public-License-Risk weil intern in der Org bleibt (GH-Packages access:restricted).",
-      "reviewedBy": "Marc, 2026-05-06",
-      "expires": "2030-05-06"
-    },
-    {
-      "package": "@cosmicdrift/*",
-      "version": "*",
-      "license": "BUSL-1.1",
-      "reason": "Eigene Public-Workspace-Packages (kumiko-framework + 6 weitere). Wir sind der Licensor — BUSL-1.1 ist unser eigener Lizenz-Choice für die public NPM-Pakete. Der License-Check denied BUSL-1.1 als generic-Pattern (für Third-Party-Deps korrekt), aber für eigene Packages ist's der designierte Lizenz.",
-      "reviewedBy": "Marc, 2026-05-06",
-      "expires": "2030-05-06"
-    },
-    {
-      "package": "create-kumiko-app",
-      "version": "*",
-      "license": "BUSL-1.1",
-      "reason": "Unscoped Workspace-Paket — `bun create kumiko-app` resolved zu `bunx create-kumiko-app`, daher KEIN @cosmicdrift/-Scope möglich. Analog zur @cosmicdrift/*-Exception unser eigener Lizenz-Choice; eigene Eintrag weil Wildcard-Pattern unscoped Pakete nicht matched.",
-      "reviewedBy": "Marc, 2026-06-21",
-      "expires": "2030-06-21"
-    },
     {
       "package": "khroma",
       "version": "*",

package/src/guard-admin-api.ts

@@ -3,11 +3,10 @@
  * Guard: blocks calls to the event-store admin API (`appendRaw`/`appendRawBatch`)
  * outside allowed paths.
  *
- * The admin API is a Marten bypass for legacy data imports (prod-readiness
- * wave 3, step 3.1). It BYPASSES the pipeline — no projections, no
- * postSave hooks, no SSE/search/audit. Used accidentally from application
- * code, that causes state inconsistencies that surface very late (at the
- * next projection rebuild, or never).
+ * The admin API is a Marten bypass for legacy data imports. It BYPASSES the
+ * pipeline — no projections, no postSave hooks, no SSE/search/audit. Used
+ * accidentally from application code, that causes state inconsistencies that
+ * surface very late (at the next projection rebuild, or never).
  *
  * Second line of defense next to the deep-import path: even if someone pulls
  * `@kubiko/framework/event-store/admin-api` directly, this guard catches it
@@ -114,7 +113,7 @@ function findEnclosingName(call: CallExpression): string {
 export const guard: AstGuard = {
   name: "Admin-API Guard",
   scan: SCAN,
-  // App repos are not exempt — appendRaw/appendRawBatch bypasses the pipeline there too (infra#502).
+  // App repos are not exempt — appendRaw/appendRawBatch bypasses the pipeline.
   security: true,
   hint: "Admin API (appendRaw/appendRawBatch) bypasses the pipeline — only allowed in samples/*/migration/ or scripts/migrations/. For domain events: ctx.appendEvent / write handler.",
   run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {

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

@@ -13,8 +13,6 @@
 // ponytail: the handler file convention (*.query.ts/*.write.ts under handlers/)
 // is not enforced yet — add it once the registration API shapes are
 // inventoried and stable.
-//
-// Part of App-Mounting 2.0 (infra#208).
 
 import * as path from "node:path";
 import { type SourceFile, SyntaxKind } from "ts-morph";
@@ -118,6 +116,8 @@ function checkCustomScreens(sf: SourceFile, violations: GuardViolation[]): void
 const DIRECTIVE_HEAD_CHARS = 600;
 const FEATURE_RELATIVE_PATH = /(?:src\/features|packages\/bundled-features\/src)\/[^/]+\/(.+)$/;
 
+const PATH_IMPLIED_RUNTIME_DIRS = ["dev/", "scripts/"];
+
 // 4. runtime-client marker instead of the path
 function clientMarkerViolation(sf: SourceFile): GuardViolation | undefined {
   const filePath = sf.getFilePath();
@@ -127,13 +127,13 @@ function clientMarkerViolation(sf: SourceFile): GuardViolation | undefined {
     directiveInHead(sf.getFullText().slice(0, DIRECTIVE_HEAD_CHARS)) === "client";
   if (!hasClientMarker || isIgnoredFile(sf)) return undefined;
   const underWeb = featureRelative.startsWith("web/") || /^web\.tsx?$/.test(featureRelative);
-  return {
-    file: filePath,
-    line: 1,
-    message: underWeb
-      ? "redundant @runtime client marker — files under web/ are client by path"
-      : "client code outside web/ — move it under web/ (bun kumiko codemod feature-layout . --write)",
-  };
+  const runtimeFromPath = PATH_IMPLIED_RUNTIME_DIRS.some((dir) => featureRelative.startsWith(dir));
+  const message = underWeb
+    ? "redundant @runtime client marker — files under web/ are client by path"
+    : runtimeFromPath
+      ? "@runtime client marker under dev/ or scripts/ — the path already sets the runtime; remove the marker (bun kumiko codemod feature-layout . --write)"
+      : "client code outside web/ — move it under web/ (bun kumiko codemod feature-layout . --write)";
+  return { file: filePath, line: 1, message };
 }
 
 export const guard: AstGuard = {

package/src/guard-comment-issue-ref-only.ts

@@ -0,0 +1,223 @@
+#!/usr/bin/env bun
+/**
+ * Comment Issue-Ref Guard: a comment that holds only an issue or PR reference or a planning
+ * label (`#1234`, `fw#1234`, `Phase 3`, `S2.H1`) and no explanatory word is a violation.
+ * The number belongs in the commit message; the comment has to carry the reason. Existing
+ * hits are frozen per file in `.kumiko-comment-issue-ref-baseline.json` and may not grow;
+ * without a baseline file (consumer repos) the guard only warns.
+ *
+ * Consecutive own-line `//` comments count as one paragraph, so a reference on the last
+ * line of an explaining paragraph is not a hit.
+ */
+
+import path from "node:path";
+import type { SourceFile } from "ts-morph";
+import { COMMENT_KIND_LINE, type CommentTrivia, scanCommentTrivia } from "./_lib/comment-trivia";
+import {
+  ALL_REPO_KINDS,
+  type AstGuard,
+  baselineRatchet,
+  buildSharedProject,
+  filesForGuard,
+  isLocalFinding,
+  relFromRepoRoot,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
+import { lineHasIgnoreTag } from "./_lib/ignore-tag";
+import { resolveRepoRoots } from "./_lib/roots";
+
+const ROOT = process.cwd();
+const GUARD_NAME = "comment-issue-ref-only";
+const IGNORE_TAG = "kumiko-lint-ignore comment-issue-ref-only";
+
+const SCAN: ScanSpec = {
+  scope: "source",
+  kinds: ALL_REPO_KINDS,
+  extensions: ["ts", "tsx"],
+  frameworkWithin: ["packages/*/src/**"],
+};
+
+const EXCLUDE = /(\.d\.(ts|tsx)$|\/dist\/)/;
+
+// `fw#12`, `#1234`, `kumiko-framework#3`, `oven-sh/bun#5`; `'` is an HTML entity.
+const REFERENCE_RE = /(?<!&)[\w./-]*#\d+(?![\w])/g;
+// Not preceded by a path/word character and not followed by `/`, `-` or `.ext`, so file names such
+// as `round2.ts` or `phase1.sql` are not planning labels, while a sentence-final "Phase 2." is.
+const PLANNING_WORD_RE =
+  /(?<![\w./-])(?:phase|round|welle|wave|sprint)[- ]?\d+(?:\.\d+)*[a-z]?(?![\w/-]|\.\w)|(?<![\w./-])bug-bash(?:[- ]\d+)?(?![\w/-]|\.\w)/gi;
+// Dotted plan labels such as S2.H1, T1.5c, B1.5. Case-sensitive and without V so
+// that version numbers (v1.2, V20.1) never count.
+const DOTTED_LABEL_RE = /(?<![\w./-])[A-UW-Z]\d{1,2}(?:\.(?:\d+[a-z]?|[A-Z]\d+))+\b/g;
+const WORD_RE = /[\p{L}_$][\p{L}\p{N}_$'-]*/gu;
+const MIN_EXPLANATORY_WORD_LENGTH = 3;
+
+// Words that only frame a reference ("see #12", "fix for fw#3", "part of Phase 2").
+const FRAMING_WORDS: ReadonlySet<string> = new Set([
+  "see",
+  "siehe",
+  "vgl",
+  "ref",
+  "refs",
+  "issue",
+  "issues",
+  "fix",
+  "fixes",
+  "fixed",
+  "for",
+  "from",
+  "per",
+  "part",
+  "the",
+  "and",
+  "und",
+  "via",
+  "follow",
+  "followup",
+  "follow-up",
+  "tracking",
+  "tracked",
+  "todo",
+  "fixme",
+  "closes",
+  "resolves",
+  "related",
+  "also",
+  "nach",
+  "aus",
+  "laut",
+]);
+
+function commentBody(text: string): string {
+  return text
+    .replace(/^\/\*\*?|\*\/$/g, "")
+    .split("\n")
+    .map((line) => line.replace(/^\s*(?:\/\/+|\*)?/, ""))
+    .join("\n");
+}
+
+function referenceTokensIn(body: string): number {
+  return (
+    (body.match(REFERENCE_RE)?.length ?? 0) +
+    (body.match(PLANNING_WORD_RE)?.length ?? 0) +
+    (body.match(DOTTED_LABEL_RE)?.length ?? 0)
+  );
+}
+
+function isExplanatoryWord(word: string): boolean {
+  return word.length >= MIN_EXPLANATORY_WORD_LENGTH && !FRAMING_WORDS.has(word.toLowerCase());
+}
+
+/** True when the comment carries a reference or planning label and no explanatory word besides it. */
+export function isIssueRefOnlyComment(commentText: string): boolean {
+  if (lineHasIgnoreTag(commentText, IGNORE_TAG)) return false;
+  const body = commentBody(commentText);
+  if (referenceTokensIn(body) === 0) return false;
+  const rest = body
+    .replace(REFERENCE_RE, " ")
+    .replace(PLANNING_WORD_RE, " ")
+    .replace(DOTTED_LABEL_RE, " ");
+  return !(rest.match(WORD_RE) ?? []).some(isExplanatoryWord);
+}
+
+type CommentParagraph = { readonly start: number; readonly text: string };
+
+function startsOwnLine(fullText: string, start: number): boolean {
+  const lineStart = fullText.lastIndexOf("\n", start - 1) + 1;
+  return fullText.slice(lineStart, start).trim() === "";
+}
+
+function continuesLineParagraph(
+  fullText: string,
+  previous: CommentTrivia,
+  next: CommentTrivia,
+): boolean {
+  if (previous.kind !== COMMENT_KIND_LINE || next.kind !== COMMENT_KIND_LINE) return false;
+  if (!startsOwnLine(fullText, previous.start) || !startsOwnLine(fullText, next.start))
+    return false;
+  return /^[ \t]*\r?\n[ \t]*$/.test(
+    fullText.slice(previous.start + previous.text.length, next.start),
+  );
+}
+
+export function commentParagraphs(fullText: string): CommentParagraph[] {
+  const paragraphs: CommentParagraph[] = [];
+  let current: { start: number; parts: string[]; last: CommentTrivia } | undefined;
+  for (const comment of scanCommentTrivia(fullText)) {
+    if (current && continuesLineParagraph(fullText, current.last, comment)) {
+      current.parts.push(comment.text);
+      current.last = comment;
+      continue;
+    }
+    if (current) paragraphs.push({ start: current.start, text: current.parts.join("\n") });
+    current = { start: comment.start, parts: [comment.text], last: comment };
+  }
+  if (current) paragraphs.push({ start: current.start, text: current.parts.join("\n") });
+  return paragraphs;
+}
+
+export type IssueRefOnlySite = { readonly line: number; readonly text: string };
+
+export function findIssueRefOnlyComments(fullText: string): IssueRefOnlySite[] {
+  return commentParagraphs(fullText)
+    .filter((paragraph) => isIssueRefOnlyComment(paragraph.text))
+    .map((paragraph) => ({
+      line: fullText.slice(0, paragraph.start).split("\n").length,
+      text: paragraph.text,
+    }));
+}
+
+export function issueRefOnlyCounts(
+  files: readonly SourceFile[],
+  roots: ReadonlyArray<{ readonly absPath: string }> = resolveRepoRoots(),
+): { counts: Record<string, number>; firstLine: Record<string, number> } {
+  const counts: Record<string, number> = {};
+  const firstLine: Record<string, number> = {};
+  for (const sf of files) {
+    if (EXCLUDE.test(sf.getFilePath())) continue;
+    const sites = findIssueRefOnlyComments(sf.getFullText());
+    const first = sites[0];
+    if (first === undefined) continue;
+    const file = relFromRepoRoot(sf.getFilePath(), roots);
+    if (!isLocalFinding({ file })) continue;
+    counts[file] = sites.length;
+    firstLine[file] = first.line;
+  }
+  return { counts, firstLine };
+}
+
+const issueRefBaseline = baselineRatchet({
+  file: path.join(ROOT, ".kumiko-comment-issue-ref-baseline.json"),
+  formatVersion: 1,
+  unit: "issue-reference-only comment(s)",
+});
+
+const REMEDIATION =
+  "Replace the reference with the reason it stands for, or delete the comment; the number belongs in the commit message.";
+
+export const guard: AstGuard = {
+  name: GUARD_NAME,
+  scan: SCAN,
+  hint: `after removing hits: \`kumiko-guards guards --write-baseline --guard=${GUARD_NAME}\`; deliberate exception: // ${IGNORE_TAG} <reason>`,
+  run: (files, roots = resolveRepoRoots()) => {
+    const { counts, firstLine } = issueRefOnlyCounts(files, roots);
+    return {
+      violations: issueRefBaseline.check(counts, REMEDIATION, {
+        formatDriftRemediation: `Run \`kumiko-guards guards --write-baseline --guard=${GUARD_NAME}\` once.`,
+        resolveLine: (file) => firstLine[file] ?? 1,
+      }),
+    };
+  },
+  writeBaseline: (files, roots = resolveRepoRoots()) => {
+    issueRefBaseline.write(issueRefOnlyCounts(files, roots).counts);
+  },
+};
+
+if (import.meta.main) {
+  if (process.argv.slice(2).includes("--write-baseline")) {
+    const project = buildSharedProject([guard]);
+    guard.writeBaseline?.(filesForGuard(project, guard));
+    process.exit(0);
+  }
+  runStandalone(guard);
+}