@cosmicdrift/kumiko-guards 0.385.0 → 0.387.0

package/LICENSE

@@ -1,57 +1,21 @@
-Business Source License 1.1
-
-Parameters
-
-Licensor:             Marc Frost
-
-Licensed Work:        @cosmicdrift/kumiko-guards
-                      The Licensed Work is © 2026 Marc Frost.
-
-Additional Use Grant: 
-You may use the Licensed Work in production for any purpose, including 
-commercially, EXCEPT for the Restricted Use. 
-
-"Restricted Use" is defined as using the Licensed Work to provide a platform 
-or service to third parties that allows them to host, deploy, or run their 
-own applications built with the Licensed Work. This includes, but is not 
-limited to: managed hosting services, software-as-a-service (SaaS) platforms, 
-platform-as-a-service (PaaS), developer platforms, or any multi-tenant 
-managed offering of the Licensed Work.
-
-This restriction does not apply to the Licensor, any entity controlled by, 
-controlling, or under common control with the Licensor ("Affiliates"), or 
-contractors acting on their behalf. The Licensor remains free to use the 
-Licensed Work for any purpose, including for the operation of kumiko.rocks.
-
-Change Date:          2030-05-05
-Change License:       Apache License, Version 2.0
-
-
-Terms
-
-The Licensor hereby grants you the right to copy, modify, create derivative works, 
-redistribute, and make non-production use of the Licensed Work. The Licensor may 
-make an Additional Use Grant, above, permitting limited production use.
-
-Effective on the Change Date, or the fourth anniversary of the first publicly 
-available distribution of the Licensed Work under this License, whichever comes 
-first, this License will convert to the Change License.
-
-This Business Source License governs use of the Licensed Work in all cases, except 
-as to any use that is explicitly granted in the Additional Use Grant above or 
-under the Change License after the Change Date.
-
-If your use of the Licensed Work does not comply with the requirements of this 
-License, you must cease use of the Licensed Work immediately.
-
-All copies of the Licensed Work, and all derivative works thereof, must include 
-this License.
-
-This License does not grant you any right, title, or interest in any trademark, 
-logo, or branding of the Licensor, except as required to comply with this License.
-
-TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN 
-“AS IS” BASIS. LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
-WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 
-TITLE, AND NON-INFRINGEMENT. IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES 
-ARISING OUT OF OR RELATED TO THIS LICENSE OR THE USE OF THE LICENSED WORK.
+MIT License
+
+Copyright (c) 2026 Marc Frost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.385.0",
+  "version": "0.387.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",
+  "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
   "repository": {
     "type": "git",
@@ -51,7 +51,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.385.0"
+    "@cosmicdrift/kumiko-framework": "0.387.0"
   },
   "peerDependenciesMeta": {
     "@cosmicdrift/kumiko-framework": {
@@ -59,6 +59,6 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.385.0"
+    "@cosmicdrift/kumiko-framework": "0.387.0"
   }
 }

package/src/_lib/comment-trivia.ts

@@ -0,0 +1,148 @@
+import { ts } from "ts-morph";
+
+export const COMMENT_KIND_LINE = "line";
+export const COMMENT_KIND_BLOCK = "block";
+
+export type CommentTrivia = {
+  readonly start: number;
+  readonly kind: typeof COMMENT_KIND_LINE | typeof COMMENT_KIND_BLOCK;
+  readonly text: string;
+};
+
+// 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,
+  ts.SyntaxKind.NoSubstitutionTemplateLiteral,
+  ts.SyntaxKind.TemplateTail,
+  ts.SyntaxKind.RegularExpressionLiteral,
+  ts.SyntaxKind.CloseParenToken,
+  ts.SyntaxKind.CloseBracketToken,
+  ts.SyntaxKind.CloseBraceToken,
+  ts.SyntaxKind.PlusPlusToken,
+  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,
+  ts.SyntaxKind.WhitespaceTrivia,
+  ts.SyntaxKind.NewLineTrivia,
+]);
+
+// The raw scanner always yields SlashToken for `/`; without the rescan a regex
+// body like /\{/ would shift braceDepth and end a template early. After an
+// operand the rescan would instead swallow `/ 2; // {` as a regex and hide the comment.
+function rescanSlashAsRegex(
+  scanner: ts.Scanner,
+  kind: ts.SyntaxKind,
+  previousEndedOperand: boolean,
+): ts.SyntaxKind {
+  if (previousEndedOperand) return kind;
+  const reScanned = scanner.reScanSlashToken();
+  return reScanned === ts.SyntaxKind.RegularExpressionLiteral ? reScanned : kind;
+}
+
+function closesTemplateSubstitution(
+  templateBraceDepths: readonly number[],
+  braceDepth: number,
+): boolean {
+  return (
+    templateBraceDepths.length > 0 &&
+    braceDepth === templateBraceDepths[templateBraceDepths.length - 1]
+  );
+}
+
+// Template substitutions can nest braces (object literals, arrow bodies, other
+// templates). The raw scanner tokenizes a `}` as a plain CloseBraceToken and
+// never resumes template mode, so reScanTemplateToken() must run once brace
+// depth returns to the level the substitution opened at.
+export function scanCommentTrivia(fullText: string): CommentTrivia[] {
+  const comments: CommentTrivia[] = [];
+  const scanner = ts.createScanner(
+    ts.ScriptTarget.Latest,
+    /* skipTrivia */ false,
+    ts.LanguageVariant.Standard,
+    fullText,
+  );
+
+  const templateBraceDepths: number[] = [];
+  let braceDepth = 0;
+  let previousEndedOperand = false;
+
+  let kind = scanner.scan();
+  while (kind !== ts.SyntaxKind.EndOfFileToken) {
+    switch (kind) {
+      case ts.SyntaxKind.SingleLineCommentTrivia:
+      case ts.SyntaxKind.MultiLineCommentTrivia:
+        comments.push({
+          start: scanner.getTokenStart(),
+          kind:
+            kind === ts.SyntaxKind.SingleLineCommentTrivia ? COMMENT_KIND_LINE : COMMENT_KIND_BLOCK,
+          text: scanner.getTokenText(),
+        });
+        break;
+      case ts.SyntaxKind.SlashToken:
+      case ts.SyntaxKind.SlashEqualsToken:
+        kind = rescanSlashAsRegex(scanner, kind, previousEndedOperand);
+        break;
+      case ts.SyntaxKind.TemplateHead:
+      case ts.SyntaxKind.TemplateMiddle:
+        templateBraceDepths.push(braceDepth);
+        break;
+      case ts.SyntaxKind.OpenBraceToken:
+        braceDepth++;
+        break;
+      case ts.SyntaxKind.CloseBraceToken:
+        if (closesTemplateSubstitution(templateBraceDepths, braceDepth)) {
+          templateBraceDepths.pop();
+          kind = scanner.reScanTemplateToken(false);
+          continue;
+        }
+        if (braceDepth > 0) braceDepth--;
+        break;
+      default:
+        break;
+    }
+    if (!TRIVIA_KINDS.has(kind)) previousEndedOperand = isOperandEnd(kind, previousEndedOperand);
+    kind = scanner.scan();
+  }
+  return comments;
+}

package/src/_lib/guard-kit.ts

@@ -339,7 +339,7 @@ export type RunResult = {
   readonly scanKinds?: readonly string[];
   /** Files the scan matched — the runner's own count, basis of the floor. */
   readonly matchedFiles?: number;
-  /** Roots whose declared sourceRoots hold no .ts/.tsx at all (D4, infra#427). */
+  /** Roots whose declared sourceRoots hold no .ts/.tsx at all. */
   readonly violatingRoots?: readonly string[];
   /** Violations excused by the per-repo security baseline — security guards only. */
   readonly frozenFindings?: number;
@@ -597,7 +597,7 @@ function guardKitVersion(): string {
 
 /**
  * Pure preflight verdict, injectable for tests: which of the two globally
- * silent-green cases (infra#2863) applies, if any. Not to be confused with a
+ * silent-green cases applies, if any. Not to be confused with a
  * single guard finding no target repos — that stays a per-guard `skipped`
  * line in `reportResults`.
  */

package/src/_lib/scan-scope.ts

@@ -35,7 +35,7 @@ export type RootScan = {
   readonly root: RepoRoot;
   /** Absolute paths handed to the guard, sorted. */
   readonly files: readonly string[];
-  /** All .ts/.tsx under the declared sourceRoots minus excludes, before extension/within filters — the D4 floor input. */
+  /** All .ts/.tsx under the declared sourceRoots minus excludes, before extension/within filters — the floor input. */
   readonly sourceSurface: number;
 };
 

package/src/_lib/sql-inventory.ts

@@ -58,7 +58,7 @@ export type SqlInventoryReport = {
   };
 };
 
-/** Paths where `.unsafe()` / `asRawClient()` are permitted (Phase 5 guard). */
+/** Paths where `.unsafe()` / `asRawClient()` are permitted. */
 export const RAW_SQL_ALLOWLIST: ReadonlyArray<RegExp> = [
   // Layout-agnostic: framework packages/... AND flat app src/... AND enterprise packages/<pkg>/...
   /(^|\/)(packages\/[^/]+\/)?src\/db\/queries\//,
@@ -107,7 +107,7 @@ const PATTERNS: ReadonlyArray<{
   { kind: "execute", re: /\.execute\s*\(/ },
 ];
 
-/** Only these kinds fail CI; delete_from/execute stay inventory-only (infra#610). */
+/** Only these kinds fail CI; delete_from/execute stay inventory-only. */
 export const BLOCKING_SQL_KINDS: ReadonlyArray<SqlInventoryKind> = ["unsafe", "asRawClient"];
 
 const TS_GLOB = new Bun.Glob("**/*.{ts,tsx}");

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.387.0",
+    "type": "improvement",
+    "title": "Comment Issue-Ref guard",
+    "detail": "The comment-issue-ref-only guard flags comments that consist only of an issue or PR reference or a planning label (`#1234`, `fw#1234`, `Phase 3`, `S2.H1`) with no explanatory word besides it. Consecutive own-line `//` comments count as one paragraph, so a reference at the end of an explaining paragraph passes. Hits are frozen per file in `.kumiko-comment-issue-ref-baseline.json` and may not grow; without the baseline file the guard only warns. Deliberate exceptions take `// kumiko-lint-ignore comment-issue-ref-only <reason>`.",
+    "migration": "Optional. Freeze existing hits with `kumiko-guards guards --write-baseline --guard=comment-issue-ref-only`."
+  },
   {
     "version": "0.385.0",
     "type": "improvement",

package/src/check-as-casts.ts

@@ -117,7 +117,7 @@ export function isConstAssertion(cast: AsExpression): boolean {
 // optional ParenthesizedExpression in between (depending on parenthesisation):
 //   `x as unknown as Y`     → AsExpr(target=Y) → AsExpr(target=unknown) → x
 //   `(x as unknown) as Y`   → AsExpr(target=Y) → ParenExpr → AsExpr(target=unknown) → x
-// Wir gehen durch Parens transparent durch.
+// Traverse parentheses transparently.
 function unwrapParens(node: Node | undefined): Node | undefined {
   while (node?.getKind() === SyntaxKind.ParenthesizedExpression) {
     node = node.asKindOrThrow(SyntaxKind.ParenthesizedExpression).getExpression();
@@ -277,7 +277,7 @@ function restOfLine(fullText: string, from: number): string {
 export function extractBoundaryReason(cast: AsExpression): string | null {
   const fullText = cast.getSourceFile().getFullText();
 
-  // (1) Leading comments des enclosing statement
+  // (1) Leading comments of the enclosing statement
   const stmt =
     cast.getFirstAncestorByKind(SyntaxKind.VariableStatement) ??
     cast.getFirstAncestorByKind(SyntaxKind.ExpressionStatement) ??
@@ -288,7 +288,7 @@ export function extractBoundaryReason(cast: AsExpression): string | null {
     if (reason !== null) return reason;
   }
 
-  // (2) Cast-Range selbst (multi-line casts, inline comments innerhalb)
+  // (2) Cast range itself (multi-line casts, inline comments inside)
   const inlineReason = boundaryReasonIn(fullText.slice(cast.getStart(), cast.getEnd()));
   if (inlineReason !== null) return inlineReason;
 
@@ -327,9 +327,8 @@ const FILE_DEFAULT_REASONS: ReadonlyArray<{
   boundaryReason: BoundaryReason;
 }> = [
   {
-    // feature-AST extractors: alle Casts gehen vom erased ts-morph-Parse-
-    // Result zu typed feature-Definitionen (EntityDefinition, RelationDef,
-    // NavDef, ConfigKeys, …). Per Konstruktion ein schema-walk.
+    // Feature-AST extractors cast erased ts-morph parse results to typed feature definitions
+    // (EntityDefinition, RelationDef, NavDef, ConfigKeys, …), so every cast is a schema walk.
     pattern: /\/engine\/feature-ast\//,
     boundaryReason: "schema-walk",
   },
@@ -605,7 +604,7 @@ function writeBaseline(all: readonly Site[]): void {
   legitRatchet.write(legitCountsByPackage(all));
 }
 
-// Per File:target: aktueller Count gegen baseline. Mehr → Regression.
+// Per file:target: current count against the baseline. More → regression.
 // A cast swap (cast A removed, cast B with a different target added) is detected
 // this way although the total stays stable.
 // Merge-conflict markers, truncated writes and hand edits all land here; the

package/src/check-complexity.ts

@@ -27,8 +27,6 @@
  *   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
  */
 
 import * as path from "node:path";

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-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/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";

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

@@ -0,0 +1,221 @@
+#!/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;
+const PLANNING_WORD_RE =
+  /\b(?:phase|round|welle|wave|sprint)[- ]?\d+(?:\.\d+)*[a-z]?\b|\bbug-bash(?:[- ]\d+)?\b/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 = /\b[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);
+}

package/src/guard-comment-lang.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
-import { ts } from "ts-morph";
+import { scanCommentTrivia } from "./_lib/comment-trivia";
 import { gitEnv } from "./_lib/git-env";
 import { ALL_REPO_KINDS, cliFlagsError, isLocalFinding } from "./_lib/guard-kit";
 import { lineHasIgnoreTag } from "./_lib/ignore-tag";
@@ -72,142 +72,11 @@ function germanCommentSite(
   };
 }
 
-// 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,
-  ts.SyntaxKind.NoSubstitutionTemplateLiteral,
-  ts.SyntaxKind.TemplateTail,
-  ts.SyntaxKind.RegularExpressionLiteral,
-  ts.SyntaxKind.CloseParenToken,
-  ts.SyntaxKind.CloseBracketToken,
-  ts.SyntaxKind.CloseBraceToken,
-  ts.SyntaxKind.PlusPlusToken,
-  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,
-  ts.SyntaxKind.WhitespaceTrivia,
-  ts.SyntaxKind.NewLineTrivia,
-]);
-
-// The raw scanner always yields SlashToken for `/`; without the rescan a regex
-// body like /\{/ would shift braceDepth and end a template early. After an
-// operand the rescan would instead swallow `/ 2; // {` as a regex and hide the comment.
-function rescanSlashAsRegex(
-  scanner: ts.Scanner,
-  kind: ts.SyntaxKind,
-  previousEndedOperand: boolean,
-): ts.SyntaxKind {
-  if (previousEndedOperand) return kind;
-  const reScanned = scanner.reScanSlashToken();
-  return reScanned === ts.SyntaxKind.RegularExpressionLiteral ? reScanned : kind;
-}
-
-function closesTemplateSubstitution(
-  templateBraceDepths: readonly number[],
-  braceDepth: number,
-): boolean {
-  return (
-    templateBraceDepths.length > 0 &&
-    braceDepth === templateBraceDepths[templateBraceDepths.length - 1]
-  );
-}
-
-// Template substitutions can nest braces (object literals, arrow bodies, other
-// templates). The raw scanner tokenizes a `}` as a plain CloseBraceToken and
-// never resumes template mode, so reScanTemplateToken() must run once brace
-// depth returns to the level the substitution opened at.
 export function scanGermanComments(fullText: string, file: string): Site[] {
   const sites: Site[] = [];
-  const scanner = ts.createScanner(
-    ts.ScriptTarget.Latest,
-    /* skipTrivia */ false,
-    ts.LanguageVariant.Standard,
-    fullText,
-  );
-
-  const templateBraceDepths: number[] = [];
-  let braceDepth = 0;
-  let previousEndedOperand = false;
-
-  let kind = scanner.scan();
-  while (kind !== ts.SyntaxKind.EndOfFileToken) {
-    switch (kind) {
-      case ts.SyntaxKind.SingleLineCommentTrivia:
-      case ts.SyntaxKind.MultiLineCommentTrivia: {
-        const site = germanCommentSite(
-          fullText,
-          file,
-          scanner.getTokenStart(),
-          scanner.getTokenText(),
-        );
-        if (site) sites.push(site);
-        break;
-      }
-      case ts.SyntaxKind.SlashToken:
-      case ts.SyntaxKind.SlashEqualsToken:
-        kind = rescanSlashAsRegex(scanner, kind, previousEndedOperand);
-        break;
-      case ts.SyntaxKind.TemplateHead:
-      case ts.SyntaxKind.TemplateMiddle:
-        templateBraceDepths.push(braceDepth);
-        break;
-      case ts.SyntaxKind.OpenBraceToken:
-        braceDepth++;
-        break;
-      case ts.SyntaxKind.CloseBraceToken:
-        if (closesTemplateSubstitution(templateBraceDepths, braceDepth)) {
-          templateBraceDepths.pop();
-          kind = scanner.reScanTemplateToken(false);
-          continue;
-        }
-        if (braceDepth > 0) braceDepth--;
-        break;
-      default:
-        break;
-    }
-    if (!TRIVIA_KINDS.has(kind)) previousEndedOperand = isOperandEnd(kind, previousEndedOperand);
-    kind = scanner.scan();
+  for (const comment of scanCommentTrivia(fullText)) {
+    const site = germanCommentSite(fullText, file, comment.start, comment.text);
+    if (site) sites.push(site);
   }
   return sites;
 }

package/src/guard-direct-fetch.ts

@@ -3,7 +3,7 @@
  * Guard: finds raw `fetch(` calls in server code outside the client-scoped
  * exceptions.
  *
- * `egress(policy)` (@cosmicdrift/kumiko-framework/http, framework#2147) is
+ * `egress(policy)` (@cosmicdrift/kumiko-framework/http) is
  * the single exported way for server code to speak outward — it enforces an
  * SSRF policy (external/internal/tenant-supplied) at the call site instead
  * of leaving that to convention. This guard fails on raw `fetch(` in server
@@ -45,7 +45,7 @@ const EXCLUDE =
   /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$|(?:^|\/)web\/|(?:^|\/)public\/)/;
 
 // Prefixed by RepoRoot.name (not kind): kind "app" is shared across
-// unregistered repos (infra#560).
+// unregistered repos.
 
 // packages/framework/src/http/egress.ts IS the egress() implementation.
 const ALLOWLIST = [/^kumiko-framework\/packages\/framework\/src\/http\/egress\.ts$/];
@@ -59,7 +59,7 @@ interface Violation {
 }
 
 // `self` omitted: Worker globals live under web/public (excluded); a local
-// `const self = this` binding was a systematic FP (infra#582).
+// `const self = this` binding was a systematic FP.
 const GLOBAL_FETCH_RECEIVERS = new Set(["globalThis", "window"]);
 
 // The marker is a per-line skip for a security guard, so it only counts with a

package/src/guard-feature-integration-tests.ts

@@ -115,7 +115,7 @@ function collectImportedFeatureIds(project: Project, roots: readonly RepoRoot[])
 }
 
 /**
- * Baseline from the infra#436 measurement: features with no integration
+ * Baseline from the measurement: features with no integration
  * test reaching their directory at all — only covered (if at all) by unit
  * tests (`feature.test.ts`). Pre-existing at the first sharp run, not
  * introduced by this change. Backfilling is its own scope per feature, not

package/src/guard-i18n-locale-mount.ts

@@ -6,7 +6,7 @@
  * guard-i18n-keys.ts only checks whether a used t() key is defined —
  * and has no concept of a "mount point". A mount that never calls
  * localeDeClient() (client) or localeDe() (server) slips through there
- * completely (kumiko-studio#191, publicstatus#365, infra#533).
+ * completely.
  *
  * Scope gate: the package.json closest to the file must point at
  * kumiko-locale-de (currently kumiko-studio, publicstatus, solon,
@@ -83,9 +83,9 @@ function gateFor(sf: SourceFile, cache: Map<string, Gate>): Gate | undefined {
   return gate;
 }
 
-// localeDeClient() (clientFeatures) matcht per Call-Text; `{ de: ... }` deckt
-// die rohe <LocaleProvider fallbackBundles={[{ de: bundle }, ...]}>-Komposition
-// ab, die keinen localeDeClient()-Call verwendet.
+// localeDeClient() in clientFeatures is matched by call text; `{ de: ... }` also
+// covers a raw <LocaleProvider fallbackBundles={[{ de: bundle }, ...]}> composition
+// that does not use a localeDeClient() call.
 function localeDeClientRef(node: Node): boolean {
   if (node.isKind(SyntaxKind.Identifier) && node.getText() === "localeDeClient") return true;
   if (node.isKind(SyntaxKind.CallExpression)) return localeDeClientRef(node.getExpression());

package/src/guard-i18n-locale-terminology.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 /**
- * Guard: locale bundle values must follow Mandant/Organización terminology (#2200, fw#2355).
+ * Guard: locale bundle values must follow Mandant/Organización terminology.
  *
  * German UI copy always says "Mandant" (never "Tenant"/"Organisation"); Spanish, French
  * and Italian always say "Organización"/"organisation"/"organizzazione" (never the
@@ -50,8 +50,8 @@ const RULES: Record<TerminologyLocale, LocaleRule> = {
   de: {
     preferred: "Mandant",
     // Tenants? covers plural; Organisation(en|s)? without trailing \b so
-    // compounds like Organisations-ID / Organisationsstruktur still match
-    // (infra#603). TenantAdmin stays safe: \b after Tenant fails on 'A'.
+    // compounds like Organisations-ID / Organisationsstruktur still match.
+    // TenantAdmin stays safe: \b after Tenant fails on 'A'.
     forbidden: [/\bTenants?\b/i, /\bOrganisation(en|s)?/i],
   },
   es: {

package/src/guard-i18n-ui-strings.ts

@@ -4,7 +4,7 @@
 // that the keys are defined — this guard closes the gap before that:
 // strings that never became keys, e.g. "Loading tenants…").
 //
-// Part of App-Mounting 2.0 (infra#208).
+// Part of App-Mounting 2.0.
 
 import { type CallExpression, type Node, type SourceFile, SyntaxKind } from "ts-morph";
 import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
@@ -13,7 +13,7 @@ import { hasIgnoreTag } from "./_lib/ignore-tag";
 // Web/public code only — server code (handler error texts) goes through the
 // error i18n pipeline and has its own guards.
 //
-// samples/ deliberately NOT scanned (tried in infra#478, rolled back): the
+// samples/ deliberately NOT scanned (tried and rolled back): the
 // showcase/gallery pages are dev docs about the framework API itself
 // ("Form.title / toolbarTitle", "children — auto from schema.navs"), not
 // app UI text a real user sees. 354 hits in the trial run, almost all such
@@ -21,7 +21,7 @@ import { hasIgnoreTag } from "./_lib/ignore-tag";
 // r.translations definitions); this guard stays scoped to app repos.
 //
 // src/features/**/feature.ts covers feature.ts registrar calls (r.nav/r.screen
-// object-literal arguments) — infra#504: those sit outside JSX and were a
+// object-literal arguments) — those sit outside JSX and were a
 // blind spot. Other server code (handlers/, lib/) has its own i18n pipeline
 // and is filtered out below by requiring an r.*-call ancestor.
 const SCAN: ScanSpec = {
@@ -131,7 +131,7 @@ function collectTernaryLogicText(node: Node): TextPiece[] {
   return textPieces(node);
 }
 
-// infra#711: a hop out of a helper is only taken while that helper call is
+// A hop out of a helper is only taken while that helper call is
 // itself an argument of the next call — a call nested deeper (inside an object
 // or array, e.g. `createTextField({ label })` under `createEntity({ fields })`)
 // builds a value instead of forwarding the registrar's argument. The full chain
@@ -220,7 +220,7 @@ function checkRegistrarLabelProperties(sf: SourceFile, violations: GuardViolatio
     if (!HUMAN_TEXT.test(value) || I18N_KEY_SHAPE.test(value)) continue;
     const callChain = registrarCallChain(prop);
     if (callChain === undefined) continue;
-    // The agent-doc slot (kumiko-framework#2615) is LLM metadata for the
+    // The agent-doc slot is LLM metadata for the
     // AI tool catalog: English by design, never rendered as UI text. The
     // slot is the options object handed to a call on the registrar
     // argument chain, so forwarding it through a `defineEntity*Handler`

package/src/guard-no-custom-primitives.ts

@@ -4,7 +4,7 @@
 // exist in the framework (usePrimitives() resp. widgets/) — app rebuilds
 // drift visually and cost every migration twice.
 //
-// Second rule (infra#748): raw form HTML (<input>/<select>/<textarea>/
+// Second rule: raw form HTML (<input>/<select>/<textarea>/
 // <label>) in app/feature web code, regardless of what the file imports —
 // an import gate here previously let the designer's raw <input>s pass just
 // by importing from @cosmicdrift/kumiko-renderer (types only) instead of
@@ -15,8 +15,6 @@
 // closed against an empty baseline while no baseline file exists —
 // otherwise the rule would stay silent in every app repo until someone
 // manually runs --write-baseline there.
-//
-// Part of App-Mounting 2.0 (infra#208).
 
 import { existsSync } from "node:fs";
 import * as path from "node:path";
@@ -93,7 +91,7 @@ const RAW_FORM_HTML_REMEDIATION =
   `or usePrimitives(). Real exception: // ${IGNORE_TAG} <reason>`;
 
 // The rule is new: measured backlog is 0 in every locally checked repo
-// (infra#748). Without a baseline file, check fail-closed against an empty
+// . Without a baseline file, check fail-closed against an empty
 // baseline instead of (as usual) warn-only until the first
 // `--write-baseline` — otherwise the rule would stay silent in every app
 // repo until it separately commits its own baseline file (every baseline

package/src/guard-no-direct-process-env.ts

@@ -59,7 +59,7 @@ export function isScannableBinFile(rel: string): boolean {
 // convention at all — "solon" is deliberately not on it) and intersected
 // with the resolved roots, so a restricted scope actually narrows what this
 // guard scans instead of always walking every repo regardless of scope
-// (infra#721 follow-up — a money-horse-scoped push must not fail on a
+// (follow-up — a money-horse-scoped push must not fail on a
 // finding in publicstatus).
 const CANDIDATE_ENV_TS_REPOS: ReadonlySet<string> = new Set([
   "kumiko-studio",
@@ -81,7 +81,7 @@ export function findDirectProcessEnv(roots?: ReadonlyArray<RepoRoot>): ProcessEn
 /**
  * Like findDirectProcessEnv, additionally reports the number of files read
  * and repos with bin/env.ts — without that an empty scan can't be told apart
- * from a clean one (infra#433).
+ * from a clean one.
  */
 export function scanDirectProcessEnv(roots: ReadonlyArray<RepoRoot> = resolveRepoRoots()): {
   readonly findings: ProcessEnvFinding[];

package/src/guard-no-inline-styles.ts

@@ -2,7 +2,7 @@
 // No inline CSS in app code: `style={...}` props and `React.CSSProperties`
 // style objects bypass theme tokens and dark mode. Use widgets/tokens.
 //
-// Part of App-Mounting 2.0 (infra#208).
+// Part of App-Mounting 2.0.
 
 import { type SourceFile, SyntaxKind } from "ts-morph";
 import {

package/src/guard-no-raw-hooks.ts

@@ -7,8 +7,6 @@
 // pattern that produces them.
 //
 // Local UI state via useState stays allowed.
-//
-// Part of App-Mounting 2.0 (infra#208).
 
 import { Node, type SourceFile, SyntaxKind } from "ts-morph";
 import {

package/src/guard-primitives-discipline.ts

@@ -96,7 +96,7 @@ type ScanScope = {
 
 // Framework checkout enforces bundled-features + samples. App-repo checkout
 // scans the app's web/ screens — primitives-discipline as a ratchet per app
-// repo (infra#224). Every other resolved repo (enterprise, platform, ...)
+// repo. Every other resolved repo (enterprise, platform, ...)
 // scans alongside the others in one run — flatMap all of them instead of
 // cascading, which would silently skip every root after the first, exactly
 // the silent-skip this guard fixes.

package/src/guard-raw-classname.ts

@@ -5,7 +5,7 @@
 // Layout utilities (flex/grid/gap/p-/m-/w-) and token classes
 // (bg-primary, text-status-ok, …) stay allowed.
 //
-// Part of App-Mounting 2.0 (infra#208). Enabled per app repo in the
+// Part of App-Mounting 2.0. Enabled per app repo in the
 // respective migration PR (ui-guards input in _app-test.yml).
 
 import { type JsxAttribute, type SourceFile, SyntaxKind } from "ts-morph";

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

@@ -9,7 +9,7 @@
  * <button>/<input>/<select>/<textarea>/<dialog>/<form> are deliberately NOT
  * in this guard: <button>/<input>/<select>/<textarea>/<dialog> are already
  * enforced by guard-primitives-discipline.ts (its own CI step, not this
- * bundle), and <form> is a documented exception (PR #488, agent-layer.tsx:71
+ * bundle), and <form> is a documented exception (agent-layer.tsx:71
  * uses a native <form onSubmit> on purpose) — adding either back here would
  * duplicate or contradict an existing rule.
  *

package/src/guard-restricted-symbols.ts

@@ -5,9 +5,8 @@
  *
  * `getUnscopedAggregateStreamMaxVersion` / `getUnscopedAggregateStreamTenant`
  * (packages/framework/src/event-store/event-store.ts) have no tenant
- * filter — they are an existence oracle for foreign tenants (see
- * kumiko-framework#1269). Legitimate only for seed-/system-internal code
- * that deliberately works across tenants.
+ * filter — they are an existence oracle for foreign tenants. Legitimate only
+ * for seed-/system-internal code that deliberately works across tenants.
  *
  * Usage:
  *   bun guards/guard-restricted-symbols.ts

package/src/guard-tailwind-scan-surface.ts

@@ -4,23 +4,22 @@
  * `packages/bundled-features/src/**` must already be reachable through the
  * real Tailwind `@source` scan surface (`packages/renderer/src` +
  * `samples/**\/src`, see `packages/renderer/src/web/styles.css`).
- * bundled-features itself is NOT part of that scan surface (infra#654, follow-up to
- * kumiko-framework#2498/#2496): expanding `@source` there was verified to
- * work in the monorepo build but makes the standalone npm-consumer case
- * (no monorepo-relative scan path — #359) falsely green. A class used only
- * in bundled-features silently drops out of the compiled CSS at runtime,
- * with no build/lint error.
+ * bundled-features itself is NOT part of that scan surface: expanding
+ * `@source` there was verified to work in the monorepo build but makes the
+ * standalone npm-consumer case (no monorepo-relative scan path) falsely
+ * green. A class used only in bundled-features silently drops out of the
+ * compiled CSS at runtime, with no build/lint error.
  *
- * V1 scope (per issue decision, deliberately not a Tailwind-CLI CSS
- * regen): only plain string-literal `className="..."` JSX attributes are
- * extracted on the bundled-features side — no `cn(...)`, no template
- * literals, no dynamic class maps. The allow-set (the real scan surface)
- * is read generously instead — every string/template-literal in those
- * files, not just `className` attributes — because Tailwind's own scanner
- * is a text scan, not JSX-attribute-aware; under-approximating the allow
- * side would turn into false positives on a guard that blocks CI. Tokens
- * compare WITH their modifier prefixes intact (`hover:mb-2` is its own
- * Tailwind candidate, distinct from `mb-2`).
+ * V1 scope, deliberately not a Tailwind-CLI CSS regen: only plain
+ * string-literal `className="..."` JSX attributes are extracted on the
+ * bundled-features side — no `cn(...)`, no template literals, no dynamic
+ * class maps. The allow-set (the real scan surface) is read generously
+ * instead — every string/template-literal in those files, not just
+ * `className` attributes — because Tailwind's own scanner is a text scan,
+ * not JSX-attribute-aware; under-approximating the allow side would turn
+ * into false positives on a guard that blocks CI. Tokens compare WITH their
+ * modifier prefixes intact (`hover:mb-2` is its own Tailwind candidate,
+ * distinct from `mb-2`).
  *
  * Baseline-regression guard: pins the
  * currently-known violation count per file. Reductions are allowed but
@@ -174,11 +173,11 @@ const tailwindScanSurfaceBaseline = (baselineRoot: string) =>
 // ships .tsx with `className` under its own scan surface (renderer/src +
 // samples/**/src) needs its own `@source` entry in the app's
 // styles.css — nothing else scans it. Missed cases so far: kumiko-designer
-// in studio (studio#289), kumiko-ai-agent in publicstatus (publicstatus#442)
-// — both fixed by hand, both silent (no build/lint error) until noticed
-// visually. This does not need ts-morph: it reads package.json + styles.css
-// + a plain text scan of the dependency's shipped .tsx files directly off
-// disk, independent of the scan-selected SourceFile list above.
+// in studio, kumiko-ai-agent in publicstatus — both fixed by hand, both
+// silent (no build/lint error) until noticed visually. This does not need
+// ts-morph: it reads package.json + styles.css + a plain text scan of the
+// dependency's shipped .tsx files directly off disk, independent of the
+// scan-selected SourceFile list above.
 const APP_STYLES_REL = "src/styles.css";
 const PACKAGE_SCOPE = /^@cosmicdrift(?:gamestudio)?\//;
 const CLASSNAME_ATTR = /\bclassName\s*=/;
@@ -390,14 +389,14 @@ export function scanSourceCoverage(roots: readonly RepoRoot[]): SourceCoverageFi
 }
 
 // Third, independent rule: an `@source` glob that is already present and
-// resolves on disk (studio#289's own fix) can still match nothing once the
-// referenced package is installed from a registry instead of a workspace
-// symlink — the symlink exposes the package's full source checkout (`src/`
-// included), a registry tarball only ships what its `package.json` `files`
-// allowlists. This is exactly the bug that got past the guard the first
-// time, so it's a hard violation, not a warning: no baseline/ratchet, every
-// finding fails the run directly (still only under baseline comparison —
-// `--no-baseline` reports it like the other rules but doesn't fail).
+// resolves on disk can still match nothing once the referenced package is
+// installed from a registry instead of a workspace symlink — the symlink
+// exposes the package's full source checkout (`src/`) included, a registry
+// tarball only ships what its `package.json` `files` allowlists. This is
+// exactly the bug that got past the guard the first time, so it's a hard
+// violation, not a warning: no baseline/ratchet, every finding fails the run
+// directly (still only under baseline comparison — `--no-baseline` reports it
+// like the other rules but doesn't fail).
 const NODE_MODULES_PKG_SEGMENT = /node_modules\/((?:@[^/]+\/)?[^/]+)\/([^/]+)/;
 
 export interface PublishedScanSurfaceFinding {

package/src/guard-tenant-escalation.ts

@@ -61,8 +61,8 @@ type RoleHandler = { name: string; file: string; line: number };
 // A `schema:` property that references an outlined const (`schema:
 // CancelInvitationSchema`) has no `role:`/`roles:` text of its own — the field
 // lives in the const's declaration. Resolving the identifier to its
-// declaration covers that ~43% of write handlers (#1556-adjacent bug: a
-// text-only check silently skips them). Falls back to the property's own text
+// declaration covers that ~43% of write handlers; a text-only check silently
+// skips them. Falls back to the property's own text
 // when the initializer isn't a resolvable identifier.
 function resolvedSchemaText(schemaProp: Node): string {
   const init = schemaProp.asKind(SyntaxKind.PropertyAssignment)?.getInitializer();
@@ -208,7 +208,7 @@ function globalUserWriteMissingCheck(
   // 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
+  // gate on isAdminActor at runtime (this 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;

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 /**
  * Guard: apps must not locally reimplement the e2e/screenshot template that
- * `@cosmicdrift/kumiko-testing` already owns (#3118). Flags, in Playwright
+ * `@cosmicdrift/kumiko-testing` already owns. Flags, in Playwright
  * configs and e2e/screenshot specs/helpers:
  *   (a) a `playwright*.config.ts` that imports `defineConfig` from
  *       `@playwright/test` directly instead of `defineAppE2eConfig` from

package/src/guard-test-timeouts.ts

@@ -23,7 +23,7 @@
  * the message.
  *
  * No baseline, no ratchet: any finding
- * fails. #3118's transition period (a `.kumiko-test-timeouts-baseline.json`
+ * fails. The transition period (a `.kumiko-test-timeouts-baseline.json`
  * grandfathering pre-existing sleep loops) is over — every consumer must fix
  * or mark the cause, not accumulate a pinned count.
  *

package/src/guard-write-handler-qns.ts

@@ -30,7 +30,7 @@ const SCAN: ScanSpec = {
   frameworkWithin: ["packages/*/src/**", "samples/**"],
 };
 
-// Tests nutzen absichtlich generische QNs wie dispatcher.write("x", {}).
+// Tests intentionally use generic QNs such as dispatcher.write("x", {}).
 const EXCLUDE = /(__tests__|\.test\.tsx$|\.integration\.tsx$|\/node_modules\/|\/dist\/)/;
 
 /**

package/src/run-guards.ts

@@ -25,6 +25,7 @@ import { guard as complexity } from "./check-complexity";
 import { guard as predicateExtraction } from "./check-predicates";
 import { guard as adminApi } from "./guard-admin-api";
 import { guard as appFeatureStructure } from "./guard-app-feature-structure";
+import { guard as commentIssueRefOnly } from "./guard-comment-issue-ref-only";
 import { guard as crossFeatureImports } from "./guard-cross-feature-imports";
 import { guard as directEntityWrites } from "./guard-direct-entity-writes";
 import { guard as directFetch } from "./guard-direct-fetch";
@@ -82,6 +83,7 @@ export const GUARDS = [
   testTimeouts,
   testTemplateDrift,
   fileSize,
+  commentIssueRefOnly,
 ];
 
 export const GUARD_FLAGS = [

package/src/run-ui-guards.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-// UI-guard bundle (App-Mounting 2.0, infra#208): one process, shared ts-morph
+// UI-guard bundle (App-Mounting 2.0): one process, shared ts-morph
 // Project over the UI enforcement guards.
 import {
   buildSharedProject,

package/src/runtime-isolation-classify.ts

@@ -108,7 +108,7 @@ export function classifyByPath(repoRelativePath: string): Runtime | null {
  * for `kumiko-build` entries (`resolveClientEntries` in kumiko-framework's
  * `packages/server-runtime/src/build-prod-bundle.ts`): `src/client.tsx`/
  * `src/client.ts` (single-entry) or `src/client-<suffix>.tsx?` (declared via
- * package.json `kumiko.clientEntries`, fw#2320 — no longer auto-discovered
+ * package.json `kumiko.clientEntries`; no longer auto-discovered
  * by this filename alone). Framework/enterprise packages never match —
  * their sources live under `packages/*\/src/`, not a repo-root `src/`. Kept
  * independent of the framework's own regex (cross-package import would be a