@cosmicdrift/kumiko-guards 0.391.1 → 0.392.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.391.1",
+  "version": "0.392.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": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -51,7 +51,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.391.1"
+    "@cosmicdrift/kumiko-framework": "0.392.0"
   },
   "peerDependenciesMeta": {
     "@cosmicdrift/kumiko-framework": {
@@ -59,6 +59,6 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.391.1"
+    "@cosmicdrift/kumiko-framework": "0.392.0"
   }
 }

package/src/_lib/doc-status.ts

@@ -0,0 +1,206 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import type { RepoRoot } from "./roots";
+
+export const DOC_STATUSES = [
+  "shipped",
+  "in-progress",
+  "blocked",
+  "parked",
+  "idea",
+  "unknown",
+  "superseded",
+  "reference",
+] as const;
+
+export type DocStatus = (typeof DOC_STATUSES)[number];
+
+export type DocFrontmatter = {
+  readonly status: DocStatus;
+  readonly verified: string;
+  readonly issue?: string;
+  readonly depends?: readonly string[];
+};
+
+export type StatusDoc = {
+  readonly relPath: string;
+  readonly frontmatter: DocFrontmatter | undefined;
+  readonly problems: readonly string[];
+};
+
+export const DOC_DIRS: readonly string[] = [
+  "docs/plans",
+  "docs/runbooks",
+  "docs/migration",
+  "docs/reference",
+];
+
+// templates/ would leak frontmatter into the files generated from them,
+// marketing/ is site copy, archive/ holds finished plans.
+const EXCLUDED_SEGMENTS: readonly string[] = ["templates", "node_modules", "marketing", "archive"];
+
+// Status overviews generated from the plan docs carry no frontmatter themselves.
+const GENERATED_PLAN_INDEXES = new Set(["docs/plans/STATUS.md", "docs/plans/ROADMAP.md"]);
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+function isDocStatus(value: string): value is DocStatus {
+  return DOC_STATUSES.some((status) => status === value);
+}
+
+function parseInlineList(raw: string | undefined): readonly string[] | undefined {
+  if (!raw) return undefined;
+  const inner = raw.startsWith("[") && raw.endsWith("]") ? raw.slice(1, -1) : raw;
+  const items = inner
+    .split(",")
+    .map((item) => item.trim().replace(/^["']|["']$/g, ""))
+    .filter((item) => item.length > 0);
+  return items.length > 0 ? items : undefined;
+}
+
+// Anchored on purpose: an unanchored `word#digits` would turn a doc path such
+// as `rfc#42.md` into a phantom issue reference.
+export function isDependsRef(ref: string): boolean {
+  return /^(?:[\w.-]+\/)?[\w.-]+#\d+(?:\s+\(.*\))?$/.test(ref) || /^[\w.-]+:.+\.md$/.test(ref);
+}
+
+type ParsedFrontmatter = Pick<StatusDoc, "frontmatter" | "problems">;
+
+function invalid(problem: string): ParsedFrontmatter {
+  return { frontmatter: undefined, problems: [problem] };
+}
+
+function readFields(
+  block: string,
+): { fields: Map<string, string>; dependsItems?: string[] } | string {
+  const fields = new Map<string, string>();
+  let lastKey: string | undefined;
+  let dependsItems: string[] | undefined;
+  for (const line of block.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    // Bullets before the `:` split, so `- repo:docs/x.md` never becomes a field.
+    if (trimmed.startsWith("- ")) {
+      if (lastKey !== "depends") {
+        return `block list item under '${lastKey ?? "<no field>"}', only 'depends' takes a list: ${trimmed}`;
+      }
+      dependsItems ??= [];
+      dependsItems.push(
+        trimmed
+          .slice(2)
+          .trim()
+          .replace(/^["']|["']$/g, ""),
+      );
+      continue;
+    }
+    const sep = line.indexOf(":");
+    if (sep < 0) return `frontmatter line without 'key: value': ${trimmed}`;
+    lastKey = line.slice(0, sep).trim();
+    fields.set(lastKey, line.slice(sep + 1).trim());
+  }
+  return { fields, dependsItems };
+}
+
+function statusDependentFieldProblems(status: string, fields: Map<string, string>): string[] {
+  const problems: string[] = [];
+  if (status === "shipped" && !fields.get("evidence")) {
+    problems.push(
+      "status 'shipped' needs evidence (PR, release or commit), otherwise use 'unknown'",
+    );
+  }
+  if (status === "superseded" && !fields.get("superseded-by")) {
+    problems.push("status 'superseded' needs superseded-by");
+  }
+  if ((status === "in-progress" || status === "blocked") && !fields.get("next")) {
+    problems.push(`status '${status}' needs next (one line)`);
+  }
+  return problems;
+}
+
+export function parseStatusFrontmatter(content: string): ParsedFrontmatter {
+  if (!content.startsWith("---\n"))
+    return invalid("no status frontmatter (file must start with '---')");
+  const end = content.indexOf("\n---", 4);
+  if (end < 0) return invalid("frontmatter is not closed (second '---' missing)");
+  const read = readFields(content.slice(4, end));
+  if (typeof read === "string") return invalid(read);
+  const { fields, dependsItems } = read;
+
+  const problems: string[] = [];
+  const status = fields.get("status") ?? "";
+  const verified = fields.get("verified") ?? "";
+  if (!isDocStatus(status)) {
+    problems.push(
+      `status '${status || "<empty>"}' is invalid, allowed: ${DOC_STATUSES.join(", ")}`,
+    );
+  }
+  if (!ISO_DATE.test(verified)) {
+    problems.push(`verified '${verified || "<empty>"}' is not an ISO date (YYYY-MM-DD)`);
+  }
+  problems.push(...statusDependentFieldProblems(status, fields));
+  if (problems.length > 0 || !isDocStatus(status)) return { frontmatter: undefined, problems };
+  return {
+    frontmatter: {
+      status,
+      verified,
+      issue: fields.get("issue"),
+      depends: dependsItems ?? parseInlineList(fields.get("depends")),
+    },
+    problems: [],
+  };
+}
+
+export function statusDocHygieneWarnings(doc: StatusDoc): readonly string[] {
+  const fm = doc.frontmatter;
+  if (!fm) return [];
+  const warnings: string[] = [];
+  if ((fm.status === "in-progress" || fm.status === "blocked") && !fm.issue?.trim()) {
+    warnings.push(
+      `status '${fm.status}' without issue: an active spec names its issue in the frontmatter`,
+    );
+  }
+  if (
+    (fm.status === "shipped" || fm.status === "superseded") &&
+    doc.relPath.startsWith("docs/plans/")
+  ) {
+    warnings.push("shipped/superseded doc in docs/plans/: move it to docs/archive/plans/");
+  }
+  for (const ref of fm.depends ?? []) {
+    if (!isDependsRef(ref)) {
+      warnings.push(`depends '${ref}' is neither 'repo#issue' nor 'repo:path.md'`);
+    }
+  }
+  return warnings;
+}
+
+function collectMarkdownFiles(dir: string, walkRoot: string, out: string[]): void {
+  for (const name of readdirSync(dir)) {
+    const abs = join(dir, name);
+    // Segments below the walk root only: a checkout under ~/marketing/ must not hide every doc.
+    if (
+      relative(walkRoot, abs)
+        .split("/")
+        .some((segment) => EXCLUDED_SEGMENTS.includes(segment))
+    ) {
+      continue;
+    }
+    if (statSync(abs).isDirectory()) collectMarkdownFiles(abs, walkRoot, out);
+    else if (name.endsWith(".md")) out.push(abs);
+  }
+}
+
+export function discoverStatusDocs(root: RepoRoot): StatusDoc[] {
+  const docs: StatusDoc[] = [];
+  for (const docDir of DOC_DIRS) {
+    const absDir = join(root.absPath, docDir);
+    if (!existsSync(absDir)) continue;
+    const files: string[] = [];
+    collectMarkdownFiles(absDir, absDir, files);
+    for (const absPath of files) {
+      const relPath = relative(root.absPath, absPath);
+      if (GENERATED_PLAN_INDEXES.has(relPath)) continue;
+      docs.push({ relPath, ...parseStatusFrontmatter(readFileSync(absPath, "utf-8")) });
+    }
+  }
+  return docs;
+}

package/src/_lib/dockerfile.ts

@@ -0,0 +1,116 @@
+export type DockerStage = { readonly lines: readonly string[] };
+
+export const NPM_AUTH_SECRET_ID = "npm_auth_token";
+
+const FROM_RE = /^\s*FROM\s/i;
+const BUN_INSTALL_RE = /^\s*RUN\s+.*\bbun\s+install\b/;
+const COPY_FROM_RE = /^\s*COPY\s+--from=/;
+const COPY_RE = /^\s*COPY\s+/;
+const COPY_CONTEXT_RE = /^\s*COPY\s+(?:--\S+\s+)*\.\/?\s+\S+\s*$/;
+const LEGACY_TOKEN_ARG_RE = /^\s*ARG\s+(\S+\s+)*NPM_AUTH_TOKEN(\s*=.*)?\s*$/;
+const LEGACY_TOKEN_ENV_RE = /^\s*ENV\s+.*\bNPM_AUTH_TOKEN\b/;
+
+// Docker line continuations (`\` at EOL) merged so a multi-line RUN/COPY
+// still matches as one logical instruction.
+export function joinContinuations(dockerfileText: string): string[] {
+  const out: string[] = [];
+  let buffer = "";
+  for (const raw of dockerfileText.split("\n")) {
+    const line = raw.replace(/\r$/, "");
+    buffer = buffer.length > 0 ? `${buffer} ${line}` : line;
+    if (/\\\s*$/.test(line)) {
+      buffer = buffer.replace(/\\\s*$/, "");
+      continue;
+    }
+    out.push(buffer);
+    buffer = "";
+  }
+  if (buffer.length > 0) out.push(buffer);
+  return out;
+}
+
+export function splitStages(lines: readonly string[]): DockerStage[] {
+  const stages: DockerStage[] = [];
+  let current: string[] | undefined;
+  for (const line of lines) {
+    if (FROM_RE.test(line)) {
+      if (current) stages.push({ lines: current });
+      current = [line];
+    } else if (current) {
+      current.push(line);
+    }
+  }
+  if (current) stages.push({ lines: current });
+  return stages;
+}
+
+export function linesBeforeFirstFrom(lines: readonly string[]): readonly string[] {
+  const firstFrom = lines.findIndex((line) => FROM_RE.test(line));
+  return firstFrom === -1 ? lines : lines.slice(0, firstFrom);
+}
+
+// The runtime stage's `bun install --production` never pulls devDependencies;
+// only a full install needs registry auth for every private package.
+export function isAuthedInstallLine(line: string): boolean {
+  return BUN_INSTALL_RE.test(line) && !/--production\b/.test(line);
+}
+
+// Identified by what it does, not by its `AS <name>` label.
+export function findBuildStage(stages: readonly DockerStage[]): DockerStage | undefined {
+  return stages.find((stage) => stage.lines.some(isAuthedInstallLine));
+}
+
+function isLegacyTokenArgOrEnv(line: string): boolean {
+  return LEGACY_TOKEN_ARG_RE.test(line) || LEGACY_TOKEN_ENV_RE.test(line);
+}
+
+// Covers a direct `ARG GITHUB_TOKEN` too, not only the NPM_AUTH_TOKEN
+// re-export: any build-arg carrying the token lands in the image history.
+export function declaresRegistryTokenAsArgOrEnv(
+  line: string,
+  tokenVariables: ReadonlySet<string>,
+): boolean {
+  if (isLegacyTokenArgOrEnv(line)) return true;
+  const declared = /^\s*(?:ARG|ENV)\s+(.*)$/.exec(line)?.[1];
+  if (declared === undefined) return false;
+  return [...tokenVariables].some((variable) =>
+    new RegExp(`(^|\\s)${variable}(=|\\s|$)`).test(declared),
+  );
+}
+
+export function declaresLegacyTokenArg(line: string): boolean {
+  return LEGACY_TOKEN_ARG_RE.test(line);
+}
+
+// A mount that only lands at /run/secrets passes BuildKit but 401s in the
+// install: the RUN must expose the secret under a variable the registry
+// config reads, via the mount's `env=` option or an inline assignment.
+export function mountsNpmAuthSecret(line: string, tokenVariables: ReadonlySet<string>): boolean {
+  return [...line.matchAll(/--mount=(\S+)/g)].some((match) => {
+    const options = (match[1] ?? "").split(",");
+    if (!options.includes("type=secret") || !options.includes(`id=${NPM_AUTH_SECRET_ID}`)) {
+      return false;
+    }
+    return [...tokenVariables].some(
+      (variable) => options.includes(`env=${variable}`) || new RegExp(`\\b${variable}=`).test(line),
+    );
+  });
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// `COPY . .` carries every file of the build context, so it counts for any name.
+export function isCopiedBeforeInstall(stage: DockerStage | undefined, filename: string): boolean {
+  if (!stage) return false;
+  const installIdx = stage.lines.findIndex(isAuthedInstallLine);
+  const relevant = installIdx === -1 ? stage.lines : stage.lines.slice(0, installIdx);
+  const fileToken = new RegExp(`(^|\\s|/)${escapeRegExp(filename)}(\\s|$)`);
+  return relevant.some(
+    (line) =>
+      !COPY_FROM_RE.test(line) &&
+      COPY_RE.test(line) &&
+      (fileToken.test(line) || COPY_CONTEXT_RE.test(line)),
+  );
+}

package/src/_lib/german-test-title.ts

@@ -0,0 +1,94 @@
+import { isGermanComment } from "../guard-comment-lang";
+
+// German words that essentially never occur in an English test title. Words that are also
+// English (die, was, am, an, in, so, man, also, will, bin, war, hat, all) are left out on purpose.
+const GERMAN_TITLE_WORDS: ReadonlySet<string> = new Set([
+  "der",
+  "das",
+  "den",
+  "dem",
+  "des",
+  "ein",
+  "eine",
+  "einen",
+  "einem",
+  "kann",
+  "wird",
+  "werden",
+  "nicht",
+  "wenn",
+  "oder",
+  "und",
+  "mit",
+  "ohne",
+  "bei",
+  "ist",
+  "sind",
+  "auf",
+  "zu",
+  "von",
+  "vom",
+  "zum",
+  "zur",
+  "im",
+  "vor",
+  "aus",
+  "als",
+  "sich",
+  "wie",
+  "auch",
+  "noch",
+  "nur",
+  "kein",
+  "keine",
+  "keinen",
+  "gibt",
+  "darf",
+  "muss",
+  "soll",
+  "liefert",
+  "wirft",
+  "setzt",
+  "zeigt",
+  "gewinnt",
+  "leer",
+  "leere",
+  "leerer",
+  "bleibt",
+  "macht",
+  "fehlt",
+  "schreibt",
+  "liest",
+  "sammelt",
+  "nennt",
+  "akzeptiert",
+  "ueber",
+  "uber",
+  "fuer",
+  "gegen",
+  "nach",
+  "dann",
+  "weil",
+  "statt",
+  "sowie",
+  "jede",
+  "jeder",
+  "jedes",
+]);
+
+const QUOTED_OR_CODE_RE = /`[^`]*`|"[^"]*"|'[^']*'/g;
+const WORD_RE = /[\p{L}]+/gu;
+
+function isUpperCaseAcronym(word: string): boolean {
+  return word.length > 1 && word === word.toUpperCase();
+}
+
+// Test titles are short, so one unambiguous German word is enough, unlike comments which
+// need an umlaut or two markers. Quoted text and code in backticks are fixture or identifier names.
+export function isGermanTestTitle(title: string): boolean {
+  if (isGermanComment(title)) return true;
+  const prose = title.replace(QUOTED_OR_CODE_RE, " ");
+  return (prose.match(WORD_RE) ?? []).some(
+    (word) => !isUpperCaseAcronym(word) && GERMAN_TITLE_WORDS.has(word.toLowerCase()),
+  );
+}

package/src/_lib/test-callee.ts

@@ -0,0 +1,34 @@
+import { Node, type SourceFile } from "ts-morph";
+
+const TEST_FRAMEWORK_MODULES: ReadonlySet<string> = new Set(["bun:test", "@playwright/test"]);
+
+export const TEST_DECLARATION_CALLEE =
+  /^(test|it|describe)(\.(skip|only|todo|if|each|failing|concurrent|serial|skipIf|runIf|todoIf))*$/;
+
+// Maps local names imported from the test framework to their exported name;
+// "" marks a namespace import (`import * as bt`), whose member access is stripped.
+export function testFrameworkAliases(sf: SourceFile): ReadonlyMap<string, string> {
+  const aliases = new Map<string, string>();
+  for (const decl of sf.getImportDeclarations()) {
+    if (!TEST_FRAMEWORK_MODULES.has(decl.getModuleSpecifierValue())) continue;
+    const namespaceImport = decl.getNamespaceImport();
+    if (namespaceImport !== undefined) aliases.set(namespaceImport.getText(), "");
+    for (const named of decl.getNamedImports()) {
+      const alias = named.getAliasNode();
+      if (alias !== undefined) aliases.set(alias.getText(), named.getName());
+    }
+  }
+  return aliases;
+}
+
+export function canonicalCalleeText(text: string, aliases: ReadonlyMap<string, string>): string {
+  const [head = "", ...rest] = text.split(".");
+  const imported = aliases.get(head);
+  if (imported === undefined) return text;
+  return (imported === "" ? rest : [imported, ...rest]).join(".");
+}
+
+// `test.each(rows)(…)` and `test.if(cond)(…)` call the result of a call.
+export function declarationBaseCallee(callee: Node): Node {
+  return Node.isCallExpression(callee) ? declarationBaseCallee(callee.getExpression()) : callee;
+}

package/src/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.392.0",
+    "type": "improvement",
+    "title": "app-dockerfile and doc-status run as public repo checks",
+    "detail": "kumiko-guards checks now includes app-dockerfile and doc-status, ported from the private infra guards package. app-dockerfile inspects deploy/Dockerfile: public/index.html or index.html must exist; with @cosmicdriftgamestudio/* dependencies the build stage copies a bunfig.toml or .npmrc scope entry before bun install and that RUN mounts the npm_auth_token BuildKit secret under the variable the registry config reads. The token as ARG/ENV (NPM_AUTH_TOKEN or the variable the registry config reads) is a warning for now and a violation next to a secret mount. Apps without private dependencies no longer need registry auth in the Dockerfile. doc-status requires valid status frontmatter for docs under docs/plans, runbooks, migration and reference; missing issue refs, finished plans outside the archive and malformed depends refs are warnings."
+  },
+  {
+    "version": "0.392.0",
+    "type": "improvement",
+    "title": "comment-lang scans every source root of the framework repo",
+    "detail": "The comment-language guard no longer limits the framework repo to packages/*/src and now also scans samples, scripts, bin, packages/*/bin, apps/*/src and packages/renderer/e2e. App and library repos are unchanged, they already scanned all their source roots."
+  },
+  {
+    "version": "0.392.0",
+    "type": "improvement",
+    "title": "New test-title and ignore-tag-reason guards, fewer comment-language false positives",
+    "detail": "test-title scans test, it and describe titles (including each/skip/only chains) for German text (an umlaut, two German function words, or one unambiguous German word) and issue references. ignore-tag-reason requires a kumiko-lint-ignore reason of at least three words that is not generic. Both start with a baseline of 0 and warn only in repos without a baseline. The comment-language guard now reports a comment only when a lowercase word contains an umlaut, an umlaut appears together with a German function word, or at least two German markers appear, so proper nouns with umlauts pass."
+  },
   {
     "version": "0.390.0",
     "type": "improvement",

package/src/guard-app-dockerfile.ts

@@ -0,0 +1,216 @@
+#!/usr/bin/env bun
+/**
+ * An app's `deploy/Dockerfile` must reach the private @cosmicdriftgamestudio registry through a
+ * BuildKit secret, never through an NPM_AUTH_TOKEN build-arg that lands in the image history.
+ *
+ * Per repo with `deploy/Dockerfile`:
+ *   - `public/index.html` or `index.html` exists.
+ *   - With @cosmicdriftgamestudio/* dependencies: bunfig.toml (`[install.scopes]`) or .npmrc
+ *     (registry line plus `_authToken`) for the scope is copied into the build stage before its
+ *     `bun install`, and that RUN mounts the `npm_auth_token` secret under a variable the
+ *     registry config reads (`env=` mount option or inline assignment).
+ *   - The token as ARG/ENV (NPM_AUTH_TOKEN or the variable the registry config reads) is a
+ *     warning; next to a secret mount it is a violation.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import {
+  type DockerStage,
+  declaresLegacyTokenArg,
+  declaresRegistryTokenAsArgOrEnv,
+  findBuildStage,
+  isAuthedInstallLine,
+  isCopiedBeforeInstall,
+  joinContinuations,
+  linesBeforeFirstFrom,
+  mountsNpmAuthSecret,
+  NPM_AUTH_SECRET_ID,
+  splitStages,
+} from "./_lib/dockerfile";
+import {
+  type GuardViolation,
+  type RepoCheck,
+  reportResults,
+  runRepoChecks,
+} from "./_lib/guard-kit";
+import type { RepoRoot } from "./_lib/roots";
+
+const DOCKERFILE_REL = "deploy/Dockerfile";
+const BUNFIG_REL = "bunfig.toml";
+const NPMRC_REL = ".npmrc";
+const PRIVATE_SCOPE = "@cosmicdriftgamestudio";
+const DEPENDENCY_FIELDS = ["dependencies", "devDependencies", "optionalDependencies"] as const;
+const SHELL_VARIABLE_RE = /\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?/g;
+
+export type AppDockerfileInput = {
+  readonly dockerfileText: string;
+  readonly hasPrivateScopeDependency: boolean;
+  readonly bunfigText: string | undefined;
+  readonly npmrcText: string | undefined;
+  readonly hasIndexHtml: boolean;
+};
+
+export type AppDockerfileFindings = {
+  readonly violations: readonly string[];
+  readonly warnings: readonly string[];
+};
+
+function hasBunfigScope(bunfigText: string | undefined): boolean {
+  if (bunfigText === undefined) return false;
+  let parsed: unknown;
+  try {
+    parsed = Bun.TOML.parse(bunfigText);
+  } catch {
+    return false;
+  }
+  const install = isPlainObject(parsed) ? parsed["install"] : undefined;
+  const scopes = isPlainObject(install) ? install["scopes"] : undefined;
+  return isPlainObject(scopes) && PRIVATE_SCOPE in scopes;
+}
+
+// A registry line without an auth token routes the scope to GitHub Packages
+// without credentials, which 401s the same way a missing line does.
+function hasNpmrcScope(npmrcText: string | undefined): boolean {
+  if (npmrcText === undefined) return false;
+  return (
+    new RegExp(`^\\s*${PRIVATE_SCOPE}:registry=`, "m").test(npmrcText) &&
+    /^\s*\/\/npm\.pkg\.github\.com\/:_authToken=/m.test(npmrcText)
+  );
+}
+
+function tokenVariablesOf(...configTexts: readonly (string | undefined)[]): Set<string> {
+  const variables = new Set<string>();
+  for (const text of configTexts) {
+    for (const match of (text ?? "").matchAll(SHELL_VARIABLE_RE)) {
+      if (match[1]) variables.add(match[1]);
+    }
+  }
+  return variables;
+}
+
+function registryAuthViolation(input: AppDockerfileInput, stage: DockerStage): string | undefined {
+  const bunfigReaches =
+    hasBunfigScope(input.bunfigText) && isCopiedBeforeInstall(stage, BUNFIG_REL);
+  const npmrcReaches = hasNpmrcScope(input.npmrcText) && isCopiedBeforeInstall(stage, NPMRC_REL);
+  if (bunfigReaches || npmrcReaches) return undefined;
+  return (
+    `no registry auth for "${PRIVATE_SCOPE}" reaches the build stage before \`bun install\`: ` +
+    `copy a bunfig.toml with an [install.scopes] entry (preferred) or an .npmrc with a ` +
+    `"${PRIVATE_SCOPE}:registry=" line and a "npm.pkg.github.com" _authToken line before the install`
+  );
+}
+
+function legacyArgPathIsComplete(lines: readonly string[], stage: DockerStage): boolean {
+  const installIdx = stage.lines.findIndex(isAuthedInstallLine);
+  const stageArgIdx = stage.lines.findIndex(declaresLegacyTokenArg);
+  return (
+    linesBeforeFirstFrom(lines).some(declaresLegacyTokenArg) &&
+    stageArgIdx !== -1 &&
+    stageArgIdx < installIdx
+  );
+}
+
+export function inspectAppDockerfile(input: AppDockerfileInput): AppDockerfileFindings {
+  const violations: string[] = [];
+  const warnings: string[] = [];
+  if (!input.hasIndexHtml) violations.push("neither public/index.html nor index.html exists");
+
+  const lines = joinContinuations(input.dockerfileText);
+  const tokenVariables = tokenVariablesOf(input.bunfigText, input.npmrcText);
+  const usesLegacyTokenPath = lines.some((line) =>
+    declaresRegistryTokenAsArgOrEnv(line, tokenVariables),
+  );
+  const buildStage = findBuildStage(splitStages(lines));
+  const installLine = buildStage?.lines.find(isAuthedInstallLine);
+  const mountsSecret =
+    installLine !== undefined && mountsNpmAuthSecret(installLine, tokenVariables);
+
+  if (mountsSecret && usesLegacyTokenPath) {
+    violations.push(
+      `the install mounts the ${NPM_AUTH_SECRET_ID} secret but the registry token is still declared as ARG/ENV, which bakes it into the image history`,
+    );
+  } else if (usesLegacyTokenPath) {
+    warnings.push(
+      `the registry token as ARG/ENV lands in the image history; mount the ${NPM_AUTH_SECRET_ID} BuildKit secret on the install RUN instead (managed Dockerfile template)`,
+    );
+  }
+
+  if (!input.hasPrivateScopeDependency) return { violations, warnings };
+  if (buildStage === undefined) {
+    violations.push(
+      "no stage runs a `bun install` without --production, so the private registry auth cannot be verified",
+    );
+    return { violations, warnings };
+  }
+  const authViolation = registryAuthViolation(input, buildStage);
+  if (authViolation !== undefined) violations.push(authViolation);
+  if (!mountsSecret && !legacyArgPathIsComplete(lines, buildStage)) {
+    const readers =
+      tokenVariables.size > 0
+        ? [...tokenVariables].join(" or ")
+        : "the variable bunfig.toml/.npmrc reads";
+    violations.push(
+      `the build-stage \`bun install\` does not mount the registry token: add --mount=type=secret,id=${NPM_AUTH_SECRET_ID},env=<var> with <var> = ${readers}`,
+    );
+  }
+  return { violations, warnings };
+}
+
+function readOptional(path: string): string | undefined {
+  return existsSync(path) ? readFileSync(path, "utf-8") : undefined;
+}
+
+function hasPrivateScopeDependency(repoPath: string): boolean {
+  const manifestText = readOptional(join(repoPath, "package.json"));
+  if (manifestText === undefined) return false;
+  let manifest: unknown;
+  try {
+    manifest = JSON.parse(manifestText);
+  } catch (error) {
+    throw new Error(`${join(repoPath, "package.json")}: invalid JSON`, { cause: error });
+  }
+  if (!isPlainObject(manifest)) return false;
+  return DEPENDENCY_FIELDS.some((field) => {
+    const deps = manifest[field];
+    return (
+      isPlainObject(deps) && Object.keys(deps).some((name) => name.startsWith(`${PRIVATE_SCOPE}/`))
+    );
+  });
+}
+
+function inspectRepo(root: RepoRoot): AppDockerfileFindings {
+  return inspectAppDockerfile({
+    dockerfileText: readFileSync(join(root.absPath, DOCKERFILE_REL), "utf-8"),
+    hasPrivateScopeDependency: hasPrivateScopeDependency(root.absPath),
+    bunfigText: readOptional(join(root.absPath, BUNFIG_REL)),
+    npmrcText: readOptional(join(root.absPath, NPMRC_REL)),
+    hasIndexHtml:
+      existsSync(join(root.absPath, "public/index.html")) ||
+      existsSync(join(root.absPath, "index.html")),
+  });
+}
+
+function asViolation(message: string): GuardViolation {
+  return { file: DOCKERFILE_REL, line: 1, message };
+}
+
+export const check: RepoCheck = {
+  name: "app-dockerfile",
+  hint: "Regenerate deploy/Dockerfile from the managed template and pass the registry token as the npm_auth_token BuildKit secret.",
+  run(roots) {
+    const appRoots = roots.filter((root) => existsSync(join(root.absPath, DOCKERFILE_REL)));
+    const findings = appRoots.map(inspectRepo);
+    return {
+      violations: findings.flatMap((finding) => finding.violations.map(asViolation)),
+      warnings: findings.flatMap((finding) => finding.warnings.map(asViolation)),
+      matchedFiles: appRoots.length,
+      notApplicable: appRoots.length === 0,
+    };
+  },
+};
+
+if (import.meta.main) {
+  const failed = reportResults(await runRepoChecks([check]));
+  process.exit(failed > 0 ? 1 : 0);
+}

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

@@ -41,7 +41,7 @@ const SCAN: ScanSpec = {
 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;
+export 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 =

package/src/guard-comment-lang.ts

@@ -31,7 +31,6 @@ const SCAN: ScanSpec = {
   scope: "source",
   kinds: ALL_REPO_KINDS,
   extensions: ["ts", "tsx"],
-  frameworkWithin: ["packages/*/src/**"],
 };
 
 const EXCLUDE = /(\.d\.(ts|tsx)$|\/dist\/)/;
@@ -41,11 +40,29 @@ const EXCLUDE = /(\.d\.(ts|tsx)$|\/dist\/)/;
 // 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/g;
+// Function words that never occur in English but are too rare in German
+// comments to justify a hit on their own; they only count next to an umlaut.
+const DE_WEAK_MARKER_RE =
+  /\b(ob|der|dessen|ein|jetzt|nur|sobald|schon|falls|sowie|bzw|beim|hier|keine|bewusst|zwei)\b/g;
 const MIN_DE_MARKER_HITS = 2;
 const UMLAUT_RE = /[äöüÄÖÜß]/;
+const WORD_RE = /\p{L}+/gu;
+const LOWER_CASE_WORD_RE = /^\p{Ll}/u;
+
+// A capitalised word with an umlaut is a proper noun or a fixture name ("Müller GmbH",
+// "Zürich"), so only a lower-case word carries the umlaut signal alone.
+function hasLowerCaseUmlautWord(text: string): boolean {
+  return (text.match(WORD_RE) ?? []).some(
+    (word) => LOWER_CASE_WORD_RE.test(word) && UMLAUT_RE.test(word),
+  );
+}
 
 export function isGermanComment(text: string): boolean {
-  return UMLAUT_RE.test(text) || (text.match(DE_MARKER_RE)?.length ?? 0) >= MIN_DE_MARKER_HITS;
+  const markerHits = text.match(DE_MARKER_RE)?.length ?? 0;
+  if (markerHits >= MIN_DE_MARKER_HITS) return true;
+  if (hasLowerCaseUmlautWord(text)) return true;
+  if (!UMLAUT_RE.test(text)) return false;
+  return markerHits + (text.match(DE_WEAK_MARKER_RE)?.length ?? 0) >= 1;
 }
 
 export type Site = {

package/src/guard-cross-feature-imports.ts

@@ -28,7 +28,7 @@
  * single-feature samples, framework internals) have no feature boundary
  * and are skipped.
  *
- * Escape hatch: `// kumiko-lint-ignore cross-feature-import [reason]`
+ * Escape hatch: `// kumiko-lint-ignore cross-feature-import <reason>`
  * on the same line as the import, or on the line directly above.
  *
  * Usage:
@@ -220,7 +220,7 @@ function findCrossFeatureViolations(sf: SourceFile): Omit<Violation, "file">[] {
 export const guard: AstGuard = {
   name: "Cross-Feature-Import Guard",
   scan: SCAN,
-  hint: `Import from the feature's barrel ("../<feature>") instead of its internals. Escape hatch: "// ${IGNORE_TAG} [reason]" on the import line.`,
+  hint: `Import from the feature's barrel ("../<feature>") instead of its internals. Escape hatch: "// ${IGNORE_TAG} <reason>" on the import line.`,
   run(files) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
 

package/src/guard-doc-status.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env bun
+/**
+ * Every doc under docs/{plans,runbooks,migration,reference} needs valid status frontmatter.
+ *
+ * status and verified are required; shipped needs evidence, superseded needs superseded-by,
+ * in-progress and blocked need next. Missing issue refs, finished plans outside the archive and
+ * malformed depends refs are warnings.
+ */
+import { discoverStatusDocs, statusDocHygieneWarnings } from "./_lib/doc-status";
+import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
+
+export const check: RepoCheck = {
+  name: "doc-status",
+  hint: "Frontmatter schema: status + verified (YYYY-MM-DD); shipped → evidence, superseded → superseded-by, in-progress|blocked → next.",
+  run(roots) {
+    const docs = roots.flatMap((root) => discoverStatusDocs(root));
+    return {
+      violations: docs.flatMap((doc) =>
+        doc.problems.map((message) => ({ file: doc.relPath, line: 1, message })),
+      ),
+      warnings: docs.flatMap((doc) =>
+        statusDocHygieneWarnings(doc).map((message) => ({ file: doc.relPath, line: 1, message })),
+      ),
+      matchedFiles: docs.length,
+      notApplicable: docs.length === 0,
+    };
+  },
+};
+
+if (import.meta.main) {
+  const failed = reportResults(await runRepoChecks([check]));
+  process.exit(failed > 0 ? 1 : 0);
+}

package/src/guard-ignore-tag-reason.ts

@@ -0,0 +1,128 @@
+#!/usr/bin/env bun
+/**
+ * Ignore-Tag-Reason Guard: every `kumiko-lint-ignore <slug> <reason>` comment states a real reason.
+ * A missing reason, a generic one (`todo`, `legacy`, ...) or one shorter than three words ("invite-flow")
+ * only silences a guard without telling the next reader why the exception is safe. Existing hits are
+ * frozen per file in `.kumiko-ignore-tag-reason-baseline.json` and may not grow; without a baseline
+ * file (consumer repos) the guard only warns. Documentation placeholders (`<reason>`) never count.
+ */
+
+import path from "node:path";
+import type { SourceFile } from "ts-morph";
+import { scanCommentTrivia } from "./_lib/comment-trivia";
+import { isGenericReason } from "./_lib/generic-reason";
+import {
+  ALL_REPO_KINDS,
+  type AstGuard,
+  baselineRatchet,
+  buildSharedProject,
+  filesForGuard,
+  isLocalFinding,
+  relFromRepoRoot,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
+import { resolveRepoRoots } from "./_lib/roots";
+
+const ROOT = process.cwd();
+const GUARD_NAME = "ignore-tag-reason";
+const MIN_REASON_WORDS = 3;
+
+const SCAN: ScanSpec = {
+  scope: "source+tests",
+  kinds: ALL_REPO_KINDS,
+  extensions: ["ts", "tsx"],
+};
+
+const EXCLUDE = /(\.d\.(ts|tsx)$|\/dist\/)/;
+const COMMENT_MARKER_PREFIX_RE = /^\s*(?:\/\/+|\/\*+|\*+)?\s*/;
+const COMMENT_CLOSE_SUFFIX_RE = /\s*\*\/\s*\}?\s*$/;
+const TAG_LINE_RE = /^kumiko-lint-ignore\s+(\S+)(?:\s+(.*))?$/;
+
+export type WeakIgnoreReason = {
+  readonly line: number;
+  readonly slug: string;
+  readonly reason: string;
+};
+
+function isPlaceholder(text: string): boolean {
+  return text.startsWith("<");
+}
+
+function isWeakReason(reason: string): boolean {
+  return isGenericReason(reason) || reason.split(/\s+/).filter(Boolean).length < MIN_REASON_WORDS;
+}
+
+export function findWeakIgnoreReasons(fullText: string): WeakIgnoreReason[] {
+  const sites: WeakIgnoreReason[] = [];
+  for (const comment of scanCommentTrivia(fullText)) {
+    const firstLine = fullText.slice(0, comment.start).split("\n").length;
+    for (const [offset, rawLine] of comment.text.split("\n").entries()) {
+      const body = rawLine
+        .replace(COMMENT_MARKER_PREFIX_RE, "")
+        .replace(COMMENT_CLOSE_SUFFIX_RE, "");
+      const match = TAG_LINE_RE.exec(body.trim());
+      const slug = match?.[1] ?? "";
+      const reason = (match?.[2] ?? "").trim();
+      const isCheckable = match !== null && !isPlaceholder(slug) && !isPlaceholder(reason);
+      if (isCheckable && isWeakReason(reason)) {
+        sites.push({ line: firstLine + offset, slug, reason });
+      }
+    }
+  }
+  return sites;
+}
+
+export function weakIgnoreReasonCounts(
+  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 = findWeakIgnoreReasons(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 weakReasonBaseline = baselineRatchet({
+  file: path.join(ROOT, ".kumiko-ignore-tag-reason-baseline.json"),
+  formatVersion: 1,
+  unit: "ignore tag(s) without a real reason",
+});
+
+const REMEDIATION = `Write why the exception is safe in at least ${MIN_REASON_WORDS} words after the slug: // kumiko-lint-ignore <slug> <reason>.`;
+
+export const guard: AstGuard = {
+  name: GUARD_NAME,
+  scan: SCAN,
+  hint: `after fixing hits: \`kumiko-guards guards --write-baseline --guard=${GUARD_NAME}\``,
+  run: (files, roots = resolveRepoRoots()) => {
+    const { counts, firstLine } = weakIgnoreReasonCounts(files, roots);
+    return {
+      violations: weakReasonBaseline.check(counts, REMEDIATION, {
+        formatDriftRemediation: `Run \`kumiko-guards guards --write-baseline --guard=${GUARD_NAME}\` once.`,
+        resolveLine: (file) => firstLine[file] ?? 1,
+      }),
+    };
+  },
+  writeBaseline: (files, roots = resolveRepoRoots()) => {
+    weakReasonBaseline.write(weakIgnoreReasonCounts(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-test-timeouts.ts

@@ -43,6 +43,12 @@ import {
   type ScanSpec,
 } from "./_lib/guard-kit";
 import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
+import {
+  canonicalCalleeText,
+  declarationBaseCallee,
+  TEST_DECLARATION_CALLEE,
+  testFrameworkAliases,
+} from "./_lib/test-callee";
 
 // Playwright dirs sit outside every manifest's sourceRoots/testGlobs, and
 // scenario helpers next to the specs (not just *.spec.ts) carry the timeouts too.
@@ -75,9 +81,6 @@ const TIMEOUT_RAISING_CALLEES: ReadonlySet<string> = new Set(["test.setTimeout",
 const SET_TIMEOUT_CALLEE = /(^|\.)setTimeout$/;
 const SET_DEFAULT_TIMEOUT_CALLEE = /(^|\.)setDefaultTimeout$/;
 const DESCRIBE_CONFIGURE_CALLEE = /(^|\.)describe\.configure$/;
-const TEST_FRAMEWORK_MODULES: ReadonlySet<string> = new Set(["bun:test", "@playwright/test"]);
-const TEST_DECLARATION_CALLEE =
-  /^(test|it|describe)(\.(skip|only|todo|if|each|failing|concurrent|serial|skipIf|runIf|todoIf))*$/;
 
 const HOOK_DECLARATION_CALLEE = /^(beforeAll|beforeEach|afterAll|afterEach)$/;
 
@@ -153,34 +156,6 @@ function hasTimeoutProperty(node: Node | undefined): boolean {
   );
 }
 
-// Maps local names imported from the test framework to their exported name;
-// "" marks a namespace import (`import * as bt`), whose member access is stripped.
-function testFrameworkAliases(sf: SourceFile): ReadonlyMap<string, string> {
-  const aliases = new Map<string, string>();
-  for (const decl of sf.getImportDeclarations()) {
-    if (!TEST_FRAMEWORK_MODULES.has(decl.getModuleSpecifierValue())) continue;
-    const namespaceImport = decl.getNamespaceImport();
-    if (namespaceImport !== undefined) aliases.set(namespaceImport.getText(), "");
-    for (const named of decl.getNamedImports()) {
-      const alias = named.getAliasNode();
-      if (alias !== undefined) aliases.set(alias.getText(), named.getName());
-    }
-  }
-  return aliases;
-}
-
-function canonicalCalleeText(text: string, aliases: ReadonlyMap<string, string>): string {
-  const [head = "", ...rest] = text.split(".");
-  const imported = aliases.get(head);
-  if (imported === undefined) return text;
-  return (imported === "" ? rest : [imported, ...rest]).join(".");
-}
-
-// `test.each(rows)(…)` and `test.if(cond)(…)` call the result of a call.
-function declarationBaseCallee(callee: Node): Node {
-  return Node.isCallExpression(callee) ? declarationBaseCallee(callee.getExpression()) : callee;
-}
-
 // An identifier can be the Playwright test body (`test(title, details, body)`) or an options
 // variable like `{ retry: 2 }`, so only its type decides. Every other non-function expression
 // (conditional, member access, call) is treated as a timeout so a union or untyped value cannot hide one.

package/src/guard-test-title.ts

@@ -0,0 +1,159 @@
+#!/usr/bin/env bun
+/**
+ * Test-title guard: the title of a `test`/`it`/`describe` (including `.each`, `.skip`, `.only`,
+ * `.todo` and `.if` chains) is English and carries no issue or PR reference. A German title or one
+ * ending in `(#1234)` ages into noise: the number belongs in the commit message, the title has to
+ * state the behaviour. Existing hits are frozen per file in `.kumiko-test-title-baseline.json` and
+ * may not grow; without a baseline file (consumer repos) the guard only warns.
+ */
+
+import path from "node:path";
+import { type CallExpression, Node, type SourceFile, SyntaxKind } from "ts-morph";
+import { isGermanTestTitle } from "./_lib/german-test-title";
+import {
+  ALL_REPO_KINDS,
+  type AstGuard,
+  baselineRatchet,
+  buildSharedProject,
+  filesForGuard,
+  isLocalFinding,
+  relFromRepoRoot,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
+import { hasIgnoreTag } from "./_lib/ignore-tag";
+import { resolveRepoRoots } from "./_lib/roots";
+import {
+  canonicalCalleeText,
+  declarationBaseCallee,
+  TEST_DECLARATION_CALLEE,
+  testFrameworkAliases,
+} from "./_lib/test-callee";
+import { REFERENCE_RE } from "./guard-comment-issue-ref-only";
+
+const ROOT = process.cwd();
+const GUARD_NAME = "test-title";
+const IGNORE_TAG = `kumiko-lint-ignore ${GUARD_NAME}`;
+
+// Playwright specs sit outside every manifest's testGlobs; so do bin and sample-app tests.
+const SCAN: ScanSpec = {
+  scope: "tests",
+  kinds: ALL_REPO_KINDS,
+  extensions: ["ts", "tsx"],
+  extraGlobs: [
+    "packages/*/src/**/__tests__/**/*.{ts,tsx}",
+    "packages/*/bin/**/__tests__/**/*.{ts,tsx}",
+    "samples/apps/**/*.{test,spec}.{ts,tsx}",
+    "samples/apps/**/__tests__/**/*.{ts,tsx}",
+    "e2e/**/*.{ts,tsx}",
+    "packages/*/e2e/**/*.{ts,tsx}",
+    "packages/*/src/e2e/**/*.{ts,tsx}",
+    "samples/e2e/**/*.{ts,tsx}",
+    "samples/recipes/*/e2e/**/*.{ts,tsx}",
+    "samples/apps/*/e2e/**/*.{ts,tsx}",
+  ],
+};
+
+const EXCLUDE = /(\.d\.(ts|tsx)$|\/dist\/)/;
+const PLAYWRIGHT_DESCRIBE_CALLEE = /^test\.(describe|fixme|fail)(\.\w+)*$/;
+
+type TitleFinding = { readonly line: number; readonly title: string; readonly reason: string };
+
+export function hasIssueReference(title: string): boolean {
+  return (title.match(REFERENCE_RE)?.length ?? 0) > 0;
+}
+
+function titleReason(title: string): string | undefined {
+  if (isGermanTestTitle(title)) return "German";
+  if (hasIssueReference(title)) return "issue reference";
+  return undefined;
+}
+
+function isTitleLiteral(arg: Node): boolean {
+  return (
+    Node.isStringLiteral(arg) ||
+    Node.isNoSubstitutionTemplateLiteral(arg) ||
+    Node.isTemplateExpression(arg)
+  );
+}
+
+function titleLiteralText(arg: Node | undefined): string | undefined {
+  if (arg === undefined || !isTitleLiteral(arg)) return undefined;
+  return arg.getText().slice(1, -1);
+}
+
+function isTestDeclaration(call: CallExpression, aliases: ReadonlyMap<string, string>): boolean {
+  const base = canonicalCalleeText(declarationBaseCallee(call.getExpression()).getText(), aliases);
+  return TEST_DECLARATION_CALLEE.test(base) || PLAYWRIGHT_DESCRIBE_CALLEE.test(base);
+}
+
+export function findBadTestTitles(sf: SourceFile): TitleFinding[] {
+  const aliases = testFrameworkAliases(sf);
+  const findings: TitleFinding[] = [];
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    if (!isTestDeclaration(call, aliases)) continue;
+    const arg = call.getArguments()[0];
+    const title = titleLiteralText(arg);
+    if (arg === undefined || title === undefined) continue;
+    const reason = titleReason(title);
+    if (reason === undefined) continue;
+    if (hasIgnoreTag(arg, IGNORE_TAG) || hasIgnoreTag(call, IGNORE_TAG)) continue;
+    findings.push({ line: arg.getStartLineNumber(), title, reason });
+  }
+  return findings.sort((a, b) => a.line - b.line);
+}
+
+export function testTitleCounts(
+  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 findings = findBadTestTitles(sf);
+    const first = findings[0];
+    if (first === undefined) continue;
+    const file = relFromRepoRoot(sf.getFilePath(), roots);
+    if (!isLocalFinding({ file })) continue;
+    counts[file] = findings.length;
+    firstLine[file] = first.line;
+  }
+  return { counts, firstLine };
+}
+
+const testTitleBaseline = baselineRatchet({
+  file: path.join(ROOT, ".kumiko-test-title-baseline.json"),
+  formatVersion: 1,
+  unit: "German or issue-referencing test title(s)",
+});
+
+const REMEDIATION =
+  "Write the title in English and state the behaviour instead of the issue number; the number belongs in the commit message.";
+
+export const guard: AstGuard = {
+  name: GUARD_NAME,
+  scan: SCAN,
+  hint: `after fixing hits: \`kumiko-guards guards --write-baseline --guard=${GUARD_NAME}\`; deliberate exception (e.g. a German fixture string): // ${IGNORE_TAG} <reason>`,
+  run: (files, roots = resolveRepoRoots()) => {
+    const { counts, firstLine } = testTitleCounts(files, roots);
+    return {
+      violations: testTitleBaseline.check(counts, REMEDIATION, {
+        formatDriftRemediation: `Run \`kumiko-guards guards --write-baseline --guard=${GUARD_NAME}\` once.`,
+        resolveLine: (file) => firstLine[file] ?? 1,
+      }),
+    };
+  },
+  writeBaseline: (files, roots = resolveRepoRoots()) => {
+    testTitleBaseline.write(testTitleCounts(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/run-guards.ts

@@ -37,6 +37,7 @@ import { guard as htmlEscape } from "./guard-html-escape";
 import { guard as i18nKeys } from "./guard-i18n-keys";
 import { guard as i18nLocaleMount } from "./guard-i18n-locale-mount";
 import { guard as i18nLocaleTerminology } from "./guard-i18n-locale-terminology";
+import { guard as ignoreTagReason } from "./guard-ignore-tag-reason";
 import { guard as importExtensions } from "./guard-import-extensions";
 import { guard as internalSubpathImports } from "./guard-internal-subpath-imports";
 import { guard as libTestCoverage } from "./guard-lib-test-coverage";
@@ -53,6 +54,7 @@ import { guard as testEsFixtures } from "./guard-test-es-fixtures";
 import { guard as testEsRowWrites } from "./guard-test-es-row-writes";
 import { guard as testTemplateDrift } from "./guard-test-template-drift";
 import { guard as testTimeouts } from "./guard-test-timeouts";
+import { guard as testTitle } from "./guard-test-title";
 import { guard as unsafeJsonParse } from "./guard-unsafe-json-parse";
 import { guard as writeHandlerQns } from "./guard-write-handler-qns";
 
@@ -92,6 +94,8 @@ export const GUARDS = [
   testTemplateDrift,
   fileSize,
   commentIssueRefOnly,
+  testTitle,
+  ignoreTagReason,
 ];
 
 export const GUARD_FLAGS = [

package/src/run-repo-checks.ts

@@ -9,6 +9,8 @@ import { check as secretLiterals } from "./check-secret-literals";
 import { check as singleRuntimeInstance } from "./check-single-runtime-instance";
 import { check as subpathExports } from "./check-subpath-exports";
 import { check as agentDocsDrift } from "./guard-agent-docs-drift";
+import { check as appDockerfile } from "./guard-app-dockerfile";
+import { check as docStatus } from "./guard-doc-status";
 import { check as featureIntegrationTests } from "./guard-feature-integration-tests";
 import { check as guardsDocDrift } from "./guard-guards-doc-drift";
 import { check as noDirectProcessEnv } from "./guard-no-direct-process-env";
@@ -39,6 +41,8 @@ export const REPO_CHECKS = [
   guardsDocDrift,
   unsafeArrayParam,
   schemaCliFeatures,
+  appDockerfile,
+  docStatus,
 ];
 
 export const REPO_CHECK_FLAGS: readonly string[] = ["--write-baseline"];