@cosmicdrift/kumiko-guards 0.297.0 → 0.299.0

package/README.md

@@ -14,3 +14,22 @@ The baseline lives at `.kumiko-security-baseline.json` in the consumer
 repo's root. `--explain` prints the resolved repo and per-guard scan scope
 without running any guard; `--write-security-baseline` freezes current
 findings into the baseline file.
+
+## `kumiko-pre-push`
+
+A POSIX-sh pre-push hook, wired by copying the package's `hooks/pre-push`
+shim to `.husky/pre-push`. The shim execs the nearest executable
+`node_modules/.bin/kumiko-pre-push` from the repo root upwards (so worktrees
+without their own `node_modules` resolve via the parent install) and fails
+closed with a `bun install` / `PRE_PUSH_SKIP=1` hint when none exists. Inside
+the cosmicdriftgamestudio parent workspace it runs a scoped `bun check` for
+the pushing repo only; in a standalone clone it runs the repo's own
+`package.json` `test` script. Set `PRE_PUSH_SKIP=1` to bypass.
+
+Extension point: a tracked, executable `scripts/pre-push-extra.sh` runs
+before the main check in every branch (worktree, parent-scoped, and
+standalone), with `KUMIKO_PUSH_REPO_ROOT` and `KUMIKO_PUSH_PARENT_DIR`
+available inline (never exported, so nothing else inherits them). An
+untracked or non-executable `scripts/pre-push-extra.sh` is never run — this
+is fail-closed so a stray or unreviewed file can't hijack push. A non-zero
+exit from `pre-push-extra.sh` aborts the push before the main check runs.

package/hooks/pre-push

@@ -0,0 +1,36 @@
+#!/usr/bin/env sh
+# PRE_PUSH_SKIP is checked here too so the bypass works even without node_modules.
+if [ "${PRE_PUSH_SKIP:-0}" = "1" ]; then
+  echo "[pre-push] PRE_PUSH_SKIP=1 — hook skipped"
+  exit 0
+fi
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+if [ -z "$REPO_ROOT" ]; then
+  echo "[pre-push] FATAL: git rev-parse --show-toplevel failed — refusing push" >&2
+  exit 1
+fi
+
+# Walk up to / so a worktree without its own node_modules resolves via the
+# parent install; `[ -x ]` also skips a broken (uninstalled) symlink.
+BIN=""
+DIR="$REPO_ROOT"
+while true; do
+  CANDIDATE="$DIR/node_modules/.bin/kumiko-pre-push"
+  if [ -x "$CANDIDATE" ]; then
+    BIN="$CANDIDATE"
+    break
+  fi
+  if [ "$DIR" = "/" ]; then
+    break
+  fi
+  DIR="$(dirname "$DIR")"
+done
+
+if [ -z "$BIN" ]; then
+  echo "[pre-push] kumiko-pre-push not found in any node_modules/.bin above $REPO_ROOT." >&2
+  echo "Run \`bun install\`, or set PRE_PUSH_SKIP=1 to bypass this hook." >&2
+  exit 1
+fi
+
+cd "$REPO_ROOT" && exec "$BIN" "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.297.0",
+  "version": "0.299.0",
   "description": "AST-based security guards for Kumiko repos: direct-fs/fetch, tenant escalation, admin-API, escape hatches and related checks, run over a shared ts-morph project.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -24,10 +24,11 @@
     }
   },
   "bin": {
-    "kumiko-guards": "./src/cli.ts"
+    "kumiko-guards": "./src/cli.ts",
+    "kumiko-pre-push": "./src/pre-push.sh"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-repo-manifest": "0.297.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.299.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {
@@ -37,6 +38,7 @@
   "files": [
     "src",
     "!src/**/__tests__/**",
+    "hooks",
     "README.md",
     "LICENSE"
   ]

package/src/_lib/guard-kit.ts

@@ -52,7 +52,10 @@ export type AstGuard = {
   readonly hint?: string;
   /** Security guards fail on every finding not frozen in the per-repo security baseline — no skip flag. */
   readonly security?: boolean;
-  run(files: readonly SourceFile[]): GuardOutcome;
+  /** `roots` are the same roots `runGuards` scanned `files` with — a guard classifying paths against repo roots (`relFromRepoRoot`) must use these, not re-derive its own single-repo `resolveRepoRoots()`, or a multi-root caller's roots never reach it. */
+  run(files: readonly SourceFile[], roots?: readonly RepoRoot[]): GuardOutcome;
+  /** Ratchet guards only: freeze the current findings into that guard's own baseline file. */
+  writeBaseline?(files: readonly SourceFile[]): void;
 };
 
 export function isSecurityGuard(guard: Pick<AstGuard, "security">): boolean {
@@ -309,7 +312,7 @@ export function runGuards(
       const scans = scan(guard, roots);
       const paths = [...new Set(scans.flatMap((s) => s.files))].sort();
       const files = paths.map((p) => project.getSourceFile(p) ?? project.addSourceFileAtPath(p));
-      const outcome = guard.run(files);
+      const outcome = guard.run(files, roots);
       // Security guards get no skip flag: every finding must clear the baseline.
       const securityResult = isSecurityGuard(guard)
         ? applySecurityBaseline({

package/src/changes.json

@@ -1,4 +1,21 @@
 [
+  {
+    "version": "0.299.0",
+    "type": "improvement",
+    "title": "kumiko-guards ships a kumiko-pre-push bin carrying the shared pre-push hook mechanics",
+    "detail": "Consumer repos can replace their vendored .husky/pre-push with a thin shim; a tracked, executable scripts/pre-push-extra.sh is the per-repo extension point."
+  },
+  {
+    "version": "0.299.0",
+    "type": "improvement",
+    "title": "kumiko-guards ships the canonical `hooks/pre-push` shim that execs the nearest `node_modules/.bin/kumiko-pre-push` and fails closed with a `bun install` / `PRE_PUSH_SKIP=1` hint when it is missing; repos copy it to `.husky/pre-push`."
+  },
+  {
+    "version": "0.299.0",
+    "type": "fix",
+    "title": "AstGuard.run receives the caller's repo roots (guard-test-timeouts, guard-pii-annotations, guard-section-fields-raw, guard-text-field-stance, guard-i18n-locale-mount, guard-i18n-locale-terminology, check-complexity, guard-direct-fetch, guard-no-direct-fs, guard-write-handler-qns) so multi-repo aggregate runs stop throwing \"cannot classify path\" or dropping sibling-repo findings; --write-baseline now requires --guard=<name>",
+    "migration": "No action needed for AstGuard.run's new optional `roots` parameter. `kumiko-guards guards --write-baseline` no longer writes every ratchet guard's baseline in one call; pass `--guard=<name>` to freeze one guard deliberately, or run it once per guard."
+  },
   {
     "version": "0.292.0",
     "type": "improvement",

package/src/check-complexity.ts

@@ -41,10 +41,12 @@ import {
   type GuardOutcome,
   type GuardViolation,
   isLocalFinding,
+  relFromRepoRoot,
   runStandalone,
   type ScanSpec,
 } from "./_lib/guard-kit";
 import { hasIgnoreTag } from "./_lib/ignore-tag";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 
 const ROOT = process.cwd();
 
@@ -153,8 +155,11 @@ export function computeComplexity(fn: Node): number {
   return complexity;
 }
 
-export function collectHotspots(sf: SourceFile): Hotspot[] {
-  const file = path.relative(ROOT, sf.getFilePath());
+export function collectHotspots(
+  sf: SourceFile,
+  roots: readonly RepoRoot[] = resolveRepoRoots(),
+): Hotspot[] {
+  const file = relFromRepoRoot(sf.getFilePath(), roots);
   const hotspots: Hotspot[] = [];
   for (const kind of FUNCTION_KINDS) {
     for (const fn of sf.getDescendantsOfKind(kind)) {
@@ -192,7 +197,10 @@ export function countHotspotsByFile(hotspots: readonly Hotspot[]): Record<string
   return counts;
 }
 
-function scan(files: readonly SourceFile[]): {
+function scan(
+  files: readonly SourceFile[],
+  roots: readonly RepoRoot[] = resolveRepoRoots(),
+): {
   hotspots: Hotspot[];
   scanned: number;
 } {
@@ -201,7 +209,7 @@ function scan(files: readonly SourceFile[]): {
   for (const sf of files) {
     if (EXCLUDE.test(sf.getFilePath())) continue;
     scanned++;
-    hotspots.push(...collectHotspots(sf));
+    hotspots.push(...collectHotspots(sf, roots));
   }
   hotspots.sort((a, b) => b.complexity - a.complexity);
   return { hotspots, scanned };
@@ -245,14 +253,18 @@ function checkBaseline(scanned: readonly Hotspot[]): GuardViolation[] {
     countHotspotsByFile(hotspots),
     `Split the function, or allow it with "// ${BUDGET_TAG} <reason>".`,
     {
-      formatDriftRemediation: `Run \`bun guards/check-complexity.ts --write-baseline\` once.`,
+      formatDriftRemediation: `Run \`kumiko-guards guards --write-baseline --guard="Complexity Check"\` once.`,
       resolveLine: (file) => resolveHotspotLine(hotspots, file),
     },
   );
 }
 
-function analyse(files: readonly SourceFile[], compareBaseline: boolean): GuardOutcome {
-  const { hotspots, scanned } = scan(files);
+function analyse(
+  files: readonly SourceFile[],
+  roots: readonly RepoRoot[],
+  compareBaseline: boolean,
+): GuardOutcome {
+  const { hotspots, scanned } = scan(files, roots);
   report(hotspots, scanned);
   if (!compareBaseline) {
     console.log("  Baseline comparison skipped (--no-baseline).");
@@ -267,8 +279,13 @@ export const guard: AstGuard = {
   // Kein Remediation-Text hier: reportResults haengt hint an JEDEN Fail, auch
   // an Format-Drift, wo "Funktion aufteilen" in die Irre fuehrt. Der konkrete
   // Rat steht deshalb in der jeweiligen Violation-Message.
-  hint: "after a deliberate change: `bun guards/check-complexity.ts --write-baseline`",
-  run: (files) => analyse(files, true),
+  hint: 'after a deliberate change: `kumiko-guards guards --write-baseline --guard="Complexity Check"`',
+  run: (files, roots = resolveRepoRoots()) => analyse(files, roots, true),
+  writeBaseline: (files) => {
+    const { hotspots, scanned } = scan(files);
+    report(hotspots, scanned);
+    complexityBaseline.write(countHotspotsByFile(localHotspots(hotspots)));
+  },
 };
 
 // Flags werden NUR hier gelesen, nicht in run() — der Shared-Runner
@@ -285,7 +302,7 @@ if (import.meta.main) {
   }
   if (args.includes("--no-baseline")) {
     const project = buildSharedProject([guard]);
-    analyse(filesForGuard(project, guard), false);
+    analyse(filesForGuard(project, guard), resolveRepoRoots(), false);
     process.exit(0);
   }
   runStandalone(guard);

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

@@ -26,7 +26,7 @@ import {
   mentionsAsWord,
   nameForms,
 } from "./_lib/handler-name-forms";
-import { resolveRepoRoots } from "./_lib/roots";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 
 const ROOT = process.cwd();
 const SCAN: ScanSpec = {
@@ -118,16 +118,15 @@ export const guard: AstGuard = {
   scan: SCAN,
   security: true,
   hint: "Role-restricted write handlers need a test that references the handler and asserts a caller without the role is rejected (AccessDeniedError / access_denied / 403). Existing gaps are frozen in the security baseline; after closing one: `bun guards/run-guards.ts --write-security-baseline`.",
-  run(files) {
+  run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
     // consumer CI scans only its own repo, so a sibling repo's test must not count as coverage
-    const violations: GuardViolation[] = findHandlersWithoutAccessDeniedTest(
-      files,
-      resolveRepoRoots(),
-    ).map((h) => ({
-      file: path.relative(ROOT, h.file),
-      line: h.line,
-      message: `role-restricted write handler "${h.name}" has no access-denied test — add a test that references the handler and asserts a caller without the role is rejected (AccessDeniedError / access_denied / 403).`,
-    }));
+    const violations: GuardViolation[] = findHandlersWithoutAccessDeniedTest(files, roots).map(
+      (h) => ({
+        file: path.relative(ROOT, h.file),
+        line: h.line,
+        message: `role-restricted write handler "${h.name}" has no access-denied test — add a test that references the handler and asserts a caller without the role is rejected (AccessDeniedError / access_denied / 403).`,
+      }),
+    );
     return { violations };
   },
 };

package/src/guard-direct-fetch.ts

@@ -29,7 +29,7 @@ import {
   runStandalone,
   type ScanSpec,
 } from "./_lib/guard-kit";
-import { resolveRepoRoots } from "./_lib/roots";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 
 const SCAN: ScanSpec = {
   scope: "source",
@@ -123,9 +123,8 @@ export const guard: AstGuard = {
     'Same-origin path literal (`"/api/..."`) is allowed; otherwise put `// guard-allow: same-origin fetch` on the line above. ' +
     "Local bindings named fetch are flagged (false positive — unblock via that marker or ALLOWLIST in infra/guards/guard-direct-fetch.ts). " +
     'Known gap: bracket access (globalThis["fetch"](...)).',
-  run(files) {
+  run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
-    const roots = resolveRepoRoots();
 
     for (const sf of files) {
       const file = sf.getFilePath();

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

@@ -18,7 +18,7 @@
  *   bun guards/guard-i18n-locale-mount.ts
  */
 
-import { dirname, join, relative as pathRelative } from "node:path";
+import { dirname, join } from "node:path";
 import {
   type FileSystemHost,
   type Identifier,
@@ -30,11 +30,12 @@ import {
   type AstGuard,
   type GuardViolation,
   isLocalFinding,
+  relFromRepoRoot,
   runStandalone,
   type ScanSpec,
 } from "./_lib/guard-kit";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 
-const ROOT = process.cwd();
 const LOCALE_DE_DEP = "@cosmicdrift/kumiko-locale-de";
 
 const SCAN: ScanSpec = {
@@ -306,9 +307,9 @@ export const guard: AstGuard = {
   name: "i18n-Locale-Mount Guard",
   scan: SCAN,
   hint: "Mount point (createKumikoApp/createPublicSurface/LocaleProvider) without a German locale feature — add localeDeClient() to clientFeatures, or localeDe() to the server feature list.",
-  run(files) {
+  run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
     const violations = findViolations(files)
-      .map((v) => ({ ...v, file: pathRelative(ROOT, v.file) }))
+      .map((v) => ({ ...v, file: relFromRepoRoot(v.file, roots) }))
       .filter(isLocalFinding);
     return { violations };
   },

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

@@ -13,18 +13,17 @@
  * Ignore: // kumiko-lint-ignore i18n-locale-terminology
  */
 
-import { relative as pathRelative } from "node:path";
 import { type Node, type SourceFile, SyntaxKind } from "ts-morph";
 import {
   type AstGuard,
   type GuardViolation,
   isLocalFinding,
+  relFromRepoRoot,
   runStandalone,
   type ScanSpec,
 } from "./_lib/guard-kit";
 import { hasIgnoreTag } from "./_lib/ignore-tag";
-
-const ROOT = process.cwd();
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 
 const SCAN: ScanSpec = {
   scope: "source",
@@ -106,9 +105,9 @@ export const guard: AstGuard = {
   name: "i18n-Locale-Terminology Guard",
   scan: SCAN,
   hint: "DE: Mandant statt Tenant/Organisation; ES: Organización statt tenant-Loanword. Rollen wie TenantAdmin sind OK.",
-  run(files) {
+  run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
     const violations = findViolations(files)
-      .map((v) => ({ ...v, file: pathRelative(ROOT, v.file) }))
+      .map((v) => ({ ...v, file: relFromRepoRoot(v.file, roots) }))
       .filter(isLocalFinding);
     return { violations };
   },

package/src/guard-no-direct-fs.ts

@@ -34,7 +34,7 @@ import {
   runStandalone,
   type ScanSpec,
 } from "./_lib/guard-kit";
-import { resolveRepoRoots } from "./_lib/roots";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 
 const SCAN: ScanSpec = {
   scope: "source",
@@ -204,9 +204,8 @@ export const guard: AstGuard = {
   scan: SCAN,
   security: true,
   hint: "Direct node:fs import outside the allowlist — use FileStorageProvider (packages/framework/src/files/) instead of wiring fs yourself. The path-traversal guard (resolveContainedPath) only exists there. Legitimate new tooling caller? Extend the allowlist in guard-no-direct-fs.ts, with a reason + repo scope.",
-  run(files) {
+  run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
-    const roots = resolveRepoRoots();
 
     for (const sf of files) {
       const file = sf.getFilePath();

package/src/guard-pii-annotations.ts

@@ -37,9 +37,11 @@ import {
   type GuardOutcome,
   type GuardViolation,
   isLocalFinding,
+  relFromRepoRoot,
   runStandalone,
   type ScanSpec,
 } from "./_lib/guard-kit";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 
 const ROOT = process.cwd();
 
@@ -89,8 +91,8 @@ const PII_USER_OWNED_NAME_HINTS = new Set([
   "notes",
 ]);
 
-function relFile(sf: SourceFile): string {
-  return path.relative(ROOT, sf.getFilePath());
+function relFile(sf: SourceFile, roots: readonly RepoRoot[]): string {
+  return relFromRepoRoot(sf.getFilePath(), roots);
 }
 
 function fieldFactoryOptions(call: CallExpression): ObjectLiteralExpression | undefined {
@@ -149,7 +151,7 @@ export interface Finding {
   hint: string;
 }
 
-function scanFieldFactories(sf: SourceFile): Finding[] {
+function scanFieldFactories(sf: SourceFile, roots: readonly RepoRoot[]): Finding[] {
   const findings: Finding[] = [];
   for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     const callee = call.getExpression().getText();
@@ -171,15 +173,19 @@ function scanFieldFactories(sf: SourceFile): Finding[] {
     if (!hint) continue;
 
     const line = call.getStartLineNumber();
-    findings.push({ file: relFile(sf), line, fieldName, hint });
+    const file = relFile(sf, roots);
+    findings.push({ file, line, fieldName, hint });
     console.warn(
-      `  [pii-annotations WARN] ${relFile(sf)}:${line}  field "${fieldName}" looks like PII — mark ${hint}`,
+      `  [pii-annotations WARN] ${file}:${line}  field "${fieldName}" looks like PII — mark ${hint}`,
     );
   }
   return findings;
 }
 
-function scan(files: readonly SourceFile[]): {
+function scan(
+  files: readonly SourceFile[],
+  roots: readonly RepoRoot[] = resolveRepoRoots(),
+): {
   findings: Finding[];
   scanned: number;
 } {
@@ -188,7 +194,7 @@ function scan(files: readonly SourceFile[]): {
   for (const sf of files) {
     if (EXCLUDE.test(sf.getFilePath())) continue;
     scanned++;
-    findings.push(...scanFieldFactories(sf));
+    findings.push(...scanFieldFactories(sf, roots));
   }
   return { findings, scanned };
 }
@@ -224,14 +230,18 @@ function checkBaseline(findings: readonly Finding[]): GuardViolation[] {
     baselineCounts(findings),
     `Annotate the field ({ personal: ... } / { pii: true } / { userOwned: ... } / { tenantOwned: true } / { allowPlaintext: "..." }).`,
     {
-      formatDriftRemediation: `Run \`bun guards/guard-pii-annotations.ts --write-baseline\` once.`,
+      formatDriftRemediation: `Run \`kumiko-guards guards --write-baseline --guard="PII-Annotations Guard"\` once.`,
       resolveLine,
     },
   );
 }
 
-function analyse(files: readonly SourceFile[], compareBaseline: boolean): GuardOutcome {
-  const { findings } = scan(files);
+function analyse(
+  files: readonly SourceFile[],
+  roots: readonly RepoRoot[],
+  compareBaseline: boolean,
+): GuardOutcome {
+  const { findings } = scan(files, roots);
   if (!compareBaseline) {
     console.log("  Baseline comparison skipped (--no-baseline).");
     return { violations: [] };
@@ -242,8 +252,9 @@ function analyse(files: readonly SourceFile[], compareBaseline: boolean): GuardO
 export const guard: AstGuard = {
   name: "PII-Annotations Guard",
   scan: SCAN,
-  hint: "after a deliberate annotation: `bun guards/guard-pii-annotations.ts --write-baseline`",
-  run: (files) => analyse(files, true),
+  hint: 'after a deliberate annotation: `kumiko-guards guards --write-baseline --guard="PII-Annotations Guard"`',
+  run: (files, roots = resolveRepoRoots()) => analyse(files, roots, true),
+  writeBaseline: (files) => piiBaseline.write(baselineCounts(scan(files).findings)),
 };
 
 // Flags werden NUR hier gelesen, nicht in run() — der Shared-Runner
@@ -260,7 +271,7 @@ if (import.meta.main) {
   }
   if (args.includes("--no-baseline")) {
     const project = buildSharedProject([guard]);
-    analyse(filesForGuard(project, guard), false);
+    analyse(filesForGuard(project, guard), resolveRepoRoots(), false);
     process.exit(0);
   }
   runStandalone(guard);

package/src/guard-restricted-symbols.ts

@@ -113,9 +113,8 @@ export const guard: AstGuard = {
   name: "Restricted-Symbols Guard",
   scan: SCAN,
   hint: 'getUnscopedAggregateStream{MaxVersion,Tenant} is an existence oracle for foreign tenants — only seed-/system-internal code may reference them. New caller needed? Extend the allowlist in guard-restricted-symbols.ts, with a reason. Known gap: `export * from "...event-store"` is not detected (named imports, re-exports, and namespace property access are covered).',
-  run(files) {
+  run(files, roots = resolveRepoRoots()) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
-    const roots = resolveRepoRoots();
 
     for (const sf of files) {
       const file = sf.getFilePath();

package/src/guard-section-fields-raw.ts

@@ -44,9 +44,11 @@ import {
   type GuardOutcome,
   type GuardViolation,
   isLocalFinding,
+  relFromRepoRoot,
   runStandalone,
   type ScanSpec,
 } from "./_lib/guard-kit";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 
 const ROOT = process.cwd();
 
@@ -100,8 +102,8 @@ const ARRAY_READS = new Set([
   "values",
 ]);
 
-function relFile(sf: SourceFile): string {
-  return path.relative(ROOT, sf.getFilePath());
+function relFile(sf: SourceFile, roots: readonly RepoRoot[]): string {
+  return relFromRepoRoot(sf.getFilePath(), roots);
 }
 
 function hasReasonedIgnoreTag(node: Node): boolean {
@@ -129,7 +131,10 @@ export interface Finding {
   snippet: string;
 }
 
-export function scanRawSectionFieldReads(sf: SourceFile): Finding[] {
+export function scanRawSectionFieldReads(
+  sf: SourceFile,
+  roots: readonly RepoRoot[] = resolveRepoRoots(),
+): Finding[] {
   const findings: Finding[] = [];
   for (const access of sf.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)) {
     if (access.getName() !== "fields") continue;
@@ -137,19 +142,23 @@ export function scanRawSectionFieldReads(sf: SourceFile): Finding[] {
     if (!isSequenceRead(access)) continue;
     if (hasReasonedIgnoreTag(access)) continue;
     const line = access.getStartLineNumber();
-    findings.push({ file: relFile(sf), line, snippet: access.getText().slice(0, 80) });
+    const file = relFile(sf, roots);
+    findings.push({ file, line, snippet: access.getText().slice(0, 80) });
     console.warn(
-      `  [section-fields-raw WARN] ${relFile(sf)}:${line}  raw read of ${access.getText().slice(0, 80)} — use sectionFieldSpecs(section)`,
+      `  [section-fields-raw WARN] ${file}:${line}  raw read of ${access.getText().slice(0, 80)} — use sectionFieldSpecs(section)`,
     );
   }
   return findings;
 }
 
-function scan(files: readonly SourceFile[]): Finding[] {
+function scan(
+  files: readonly SourceFile[],
+  roots: readonly RepoRoot[] = resolveRepoRoots(),
+): Finding[] {
   const findings: Finding[] = [];
   for (const sf of files) {
     if (EXCLUDE.test(sf.getFilePath())) continue;
-    findings.push(...scanRawSectionFieldReads(sf));
+    findings.push(...scanRawSectionFieldReads(sf, roots));
   }
   return findings;
 }
@@ -169,8 +178,12 @@ export function baselineCounts(findings: readonly Finding[]): Record<string, num
   return counts;
 }
 
-function analyse(files: readonly SourceFile[], compareBaseline: boolean): GuardOutcome {
-  const findings = scan(files);
+function analyse(
+  files: readonly SourceFile[],
+  roots: readonly RepoRoot[],
+  compareBaseline: boolean,
+): GuardOutcome {
+  const findings = scan(files, roots);
   if (!compareBaseline) {
     console.log("  Baseline comparison skipped (--no-baseline).");
     return { violations: [] };
@@ -180,7 +193,8 @@ function analyse(files: readonly SourceFile[], compareBaseline: boolean): GuardO
     baselineCounts(findings),
     REMEDIATION,
     {
-      formatDriftRemediation: "Run `bun guards/guard-section-fields-raw.ts --write-baseline` once.",
+      formatDriftRemediation:
+        'Run `kumiko-guards guards --write-baseline --guard="Raw section.fields Guard"` once.',
       resolveLine: (file) => local.find((f) => f.file === file)?.line ?? 1,
     },
   );
@@ -190,8 +204,9 @@ function analyse(files: readonly SourceFile[], compareBaseline: boolean): GuardO
 export const guard: AstGuard = {
   name: "Raw section.fields Guard",
   scan: SCAN,
-  hint: `${REMEDIATION} Known gap: \`section.fields.length\` is not flagged. After a deliberate change: \`bun guards/guard-section-fields-raw.ts --write-baseline\`.`,
-  run: (files) => analyse(files, true),
+  hint: `${REMEDIATION} Known gap: \`section.fields.length\` is not flagged. After a deliberate change: \`kumiko-guards guards --write-baseline --guard="Raw section.fields Guard"\`.`,
+  run: (files, roots = resolveRepoRoots()) => analyse(files, roots, true),
+  writeBaseline: (files) => sectionFieldsRawBaseline.write(baselineCounts(scan(files))),
 };
 
 // Flags are read only here, never in run() — the shared runner drives every
@@ -206,7 +221,7 @@ if (import.meta.main) {
   }
   if (args.includes("--no-baseline")) {
     const project = buildSharedProject([guard]);
-    analyse(filesForGuard(project, guard), false);
+    analyse(filesForGuard(project, guard), resolveRepoRoots(), false);
     process.exit(0);
   }
   runStandalone(guard);

package/src/guard-test-timeouts.ts

@@ -21,10 +21,12 @@
  * baseline fails, at or under passes. Without the file the guard is
  * warning-only (bootstrap: `--write-baseline` once).
  *
- * Usage:
+ * Usage (framework dev checkout):
  *   bun guards/guard-test-timeouts.ts                  # compare to baseline
  *   bun guards/guard-test-timeouts.ts --write-baseline # freeze current
  *   bun guards/guard-test-timeouts.ts --no-baseline    # skip comparison
+ * Consumer (via the published `kumiko-guards` CLI):
+ *   kumiko-guards guards --write-baseline --guard=test-timeouts
  */
 import * as path from "node:path";
 import { type CallExpression, Node, type SourceFile, SyntaxKind } from "ts-morph";
@@ -36,9 +38,11 @@ import {
   type GuardOutcome,
   type GuardViolation,
   isLocalFinding,
+  relFromRepoRoot,
   runStandalone,
   type ScanSpec,
 } from "./_lib/guard-kit";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 
 const ROOT = process.cwd();
 
@@ -78,8 +82,8 @@ export interface Finding {
   message: string;
 }
 
-function relFile(sf: SourceFile): string {
-  return path.relative(ROOT, sf.getFilePath());
+function relFile(sf: SourceFile, roots: readonly RepoRoot[]): string {
+  return relFromRepoRoot(sf.getFilePath(), roots);
 }
 
 function isLoop(node: Node): boolean {
@@ -151,9 +155,12 @@ function withExceptionNote(node: Node, message: string): string | undefined {
     : message;
 }
 
-export function scanTimeouts(sf: SourceFile): Finding[] {
+export function scanTimeouts(
+  sf: SourceFile,
+  roots: readonly RepoRoot[] = resolveRepoRoots(),
+): Finding[] {
   if (sf.getFilePath().includes(RECIPES_DIR)) return [];
-  const file = relFile(sf);
+  const file = relFile(sf, roots);
   const findings: Finding[] = [];
   const add = (node: Node, message: string): void => {
     const reported = withExceptionNote(node, message);
@@ -184,7 +191,7 @@ const timeoutsBaseline = baselineRatchet({
 const REMEDIATION = `Wait for a condition (\`waitFor\`, \`expect.poll\`) instead of raising timeouts or sleeping, or mark the line with \`// ${EXCEPTION_TAG}: #<issue> <technical reason>\`.`;
 
 const HINT =
-  "Diagnose in this order: (1) reproduce a single run (`--repeat-each`, single file), (2) check shared state and missing isolation (one tenant per flow), (3) wait for a condition, not for time (`waitFor`, `expect.poll`), (4) check the seed, (5) only then change the central template via an issue — never per app. See docs/guides/test-failures.md. After a deliberate change: `bun guards/guard-test-timeouts.ts --write-baseline`.";
+  "Diagnose in this order: (1) reproduce a single run (`--repeat-each`, single file), (2) check shared state and missing isolation (one tenant per flow), (3) wait for a condition, not for time (`waitFor`, `expect.poll`), (4) check the seed, (5) only then change the central template via an issue — never per app. See https://github.com/CosmicDriftGameStudio/kumiko-framework/blob/main/docs/guides/test-failures.md. After a deliberate change: `kumiko-guards guards --write-baseline --guard=test-timeouts`.";
 
 export function baselineCounts(findings: readonly Finding[]): Record<string, number> {
   const counts: Record<string, number> = {};
@@ -194,10 +201,13 @@ export function baselineCounts(findings: readonly Finding[]): Record<string, num
   return counts;
 }
 
-function scan(files: readonly SourceFile[]): Finding[] {
+function scan(
+  files: readonly SourceFile[],
+  roots: readonly RepoRoot[] = resolveRepoRoots(),
+): Finding[] {
   const findings: Finding[] = [];
   for (const sf of files) {
-    for (const finding of scanTimeouts(sf)) {
+    for (const finding of scanTimeouts(sf, roots)) {
       findings.push(finding);
       console.warn(`  [test-timeouts WARN] ${finding.file}:${finding.line}  ${finding.message}`);
     }
@@ -205,8 +215,12 @@ function scan(files: readonly SourceFile[]): Finding[] {
   return findings;
 }
 
-function analyse(files: readonly SourceFile[], compareBaseline: boolean): GuardOutcome {
-  const findings = scan(files);
+function analyse(
+  files: readonly SourceFile[],
+  roots: readonly RepoRoot[],
+  compareBaseline: boolean,
+): GuardOutcome {
+  const findings = scan(files, roots);
   if (!compareBaseline) {
     console.log("  Baseline comparison skipped (--no-baseline).");
     return { violations: [] };
@@ -216,7 +230,8 @@ function analyse(files: readonly SourceFile[], compareBaseline: boolean): GuardO
     baselineCounts(findings),
     REMEDIATION,
     {
-      formatDriftRemediation: "Run `bun guards/guard-test-timeouts.ts --write-baseline` once.",
+      formatDriftRemediation:
+        "Run `kumiko-guards guards --write-baseline --guard=test-timeouts` once.",
       resolveLine: (file) => local.find((f) => f.file === file)?.line ?? 1,
     },
   );
@@ -227,7 +242,8 @@ export const guard: AstGuard = {
   name: "test-timeouts",
   scan: SCAN,
   hint: HINT,
-  run: (files) => analyse(files, true),
+  run: (files, roots = resolveRepoRoots()) => analyse(files, roots, true),
+  writeBaseline: (files) => timeoutsBaseline.write(baselineCounts(scan(files))),
 };
 
 // Flags are read only here, never in run() — the shared runner drives every
@@ -237,12 +253,12 @@ if (import.meta.main) {
   const args = process.argv.slice(2);
   if (args.includes("--write-baseline")) {
     const project = buildSharedProject([guard]);
-    timeoutsBaseline.write(baselineCounts(scan(filesForGuard(project, guard))));
+    guard.writeBaseline?.(filesForGuard(project, guard));
     process.exit(0);
   }
   if (args.includes("--no-baseline")) {
     const project = buildSharedProject([guard]);
-    analyse(filesForGuard(project, guard), false);
+    analyse(filesForGuard(project, guard), resolveRepoRoots(), false);
     process.exit(0);
   }
   runStandalone(guard);

package/src/guard-text-field-stance.ts

@@ -39,9 +39,11 @@ import {
   type GuardOutcome,
   type GuardViolation,
   isLocalFinding,
+  relFromRepoRoot,
   runStandalone,
   type ScanSpec,
 } from "./_lib/guard-kit";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 
 const ROOT = process.cwd();
 
@@ -61,8 +63,8 @@ const FIELD_FACTORY_CALLEES = new Set(["createTextField", "createLongTextField"]
 const VALID_PERSONAL_HINT =
   '{ personal: "self" | "tenant" | "ref" | { of: "<ownerField>" } | false } ("false" additionally needs { reason: "..." })';
 
-function relFile(sf: SourceFile): string {
-  return path.relative(ROOT, sf.getFilePath());
+function relFile(sf: SourceFile, roots: readonly RepoRoot[]): string {
+  return relFromRepoRoot(sf.getFilePath(), roots);
 }
 
 function fieldFactoryOptions(call: CallExpression): ObjectLiteralExpression | undefined {
@@ -110,7 +112,7 @@ export interface Finding {
   callee: string;
 }
 
-function scanFieldFactories(sf: SourceFile): Finding[] {
+function scanFieldFactories(sf: SourceFile, roots: readonly RepoRoot[]): Finding[] {
   const findings: Finding[] = [];
   for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     const callee = call.getExpression().getText();
@@ -126,15 +128,19 @@ function scanFieldFactories(sf: SourceFile): Finding[] {
 
     const place = enclosingFieldName(call) ?? `${callee}(...)`;
     const line = call.getStartLineNumber();
-    findings.push({ file: relFile(sf), line, place, callee });
+    const file = relFile(sf, roots);
+    findings.push({ file, line, place, callee });
     console.warn(
-      `  [text-field-stance WARN] ${relFile(sf)}:${line}  ${callee}(...) at "${place}" has no personal stance — mark ${VALID_PERSONAL_HINT}`,
+      `  [text-field-stance WARN] ${file}:${line}  ${callee}(...) at "${place}" has no personal stance — mark ${VALID_PERSONAL_HINT}`,
     );
   }
   return findings;
 }
 
-function scan(files: readonly SourceFile[]): {
+function scan(
+  files: readonly SourceFile[],
+  roots: readonly RepoRoot[] = resolveRepoRoots(),
+): {
   findings: Finding[];
   scanned: number;
 } {
@@ -143,7 +149,7 @@ function scan(files: readonly SourceFile[]): {
   for (const sf of files) {
     if (EXCLUDE.test(sf.getFilePath())) continue;
     scanned++;
-    findings.push(...scanFieldFactories(sf));
+    findings.push(...scanFieldFactories(sf, roots));
   }
   return { findings, scanned };
 }
@@ -179,14 +185,18 @@ function checkBaseline(findings: readonly Finding[]): GuardViolation[] {
     baselineCounts(findings),
     `Annotate the call (${VALID_PERSONAL_HINT}).`,
     {
-      formatDriftRemediation: `Run \`bun guards/guard-text-field-stance.ts --write-baseline\` once.`,
+      formatDriftRemediation: `Run \`kumiko-guards guards --write-baseline --guard="Text-Field Personal-Stance Guard"\` once.`,
       resolveLine,
     },
   );
 }
 
-function analyse(files: readonly SourceFile[], compareBaseline: boolean): GuardOutcome {
-  const { findings } = scan(files);
+function analyse(
+  files: readonly SourceFile[],
+  roots: readonly RepoRoot[],
+  compareBaseline: boolean,
+): GuardOutcome {
+  const { findings } = scan(files, roots);
   if (!compareBaseline) {
     console.log("  Baseline comparison skipped (--no-baseline).");
     return { violations: [] };
@@ -197,8 +207,9 @@ function analyse(files: readonly SourceFile[], compareBaseline: boolean): GuardO
 export const guard: AstGuard = {
   name: "Text-Field Personal-Stance Guard",
   scan: SCAN,
-  hint: "after a deliberate annotation: `bun guards/guard-text-field-stance.ts --write-baseline`",
-  run: (files) => analyse(files, true),
+  hint: 'after a deliberate annotation: `kumiko-guards guards --write-baseline --guard="Text-Field Personal-Stance Guard"`',
+  run: (files, roots = resolveRepoRoots()) => analyse(files, roots, true),
+  writeBaseline: (files) => textFieldStanceBaseline.write(baselineCounts(scan(files).findings)),
 };
 
 // Flags werden NUR hier gelesen, nicht in run() — der Shared-Runner
@@ -215,7 +226,7 @@ if (import.meta.main) {
   }
   if (args.includes("--no-baseline")) {
     const project = buildSharedProject([guard]);
-    analyse(filesForGuard(project, guard), false);
+    analyse(filesForGuard(project, guard), resolveRepoRoots(), false);
     process.exit(0);
   }
   runStandalone(guard);

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

@@ -183,8 +183,7 @@ export const guard: AstGuard = {
   name: "Write-Handler-QN Guard",
   scan: SCAN,
   hint: "Typo in the write-handler QN? Check feature name + handler name.",
-  run(files) {
-    const roots = resolveRepoRoots();
+  run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
     const knownQnsByRepo = loadKnownQnsByRepo(roots);
 
     const violations: Array<{

package/src/pre-push.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env sh
+# Pre-push hook — runs scoped `bun check` before allowing push.
+#
+# Logic:
+#   1. If running inside the cosmicdriftgamestudio Parent-Workspace,
+#      delegate to its `bun check` with KUMIKO_CLI_SCOPE set to THIS
+#      sub-repo only — so a push from one sub-repo doesn't run
+#      Biome/TS/Tests for its siblings as well.
+#   2. Else (standalone clone outside the parent workspace): run the
+#      sub-repo's own package.json `test` script.
+#
+# Extension point: a tracked, executable scripts/pre-push-extra.sh runs
+# before the main check in every branch above, with KUMIKO_PUSH_REPO_ROOT
+# and KUMIKO_PUSH_PARENT_DIR available inline (never exported).
+#
+# Override: set PRE_PUSH_SKIP=1 to bypass (use sparingly).
+
+if [ "${PRE_PUSH_SKIP:-0}" = "1" ]; then
+  echo "[pre-push] PRE_PUSH_SKIP=1 — hook skipped"
+  exit 0
+fi
+
+# Git exports GIT_DIR & co. to hooks; nothing this hook starts may inherit them,
+# or a test's fixture git calls write into this repo.
+LOCAL_GIT_ENV="$(git rev-parse --local-env-vars)" || { echo "[pre-push] FATAL: git rev-parse --local-env-vars failed" >&2; exit 1; }
+# shellcheck disable=SC2086
+unset $LOCAL_GIT_ENV
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+if [ -z "$REPO_ROOT" ]; then
+  echo "[pre-push] FATAL: git rev-parse --show-toplevel failed — refusing push" >&2
+  exit 1
+fi
+# --git-common-dir resolves to the main checkout's .git dir even when
+# REPO_ROOT is a `.wt/<name>` worktree, so REPO_NAME stays the repo's
+# own name instead of the worktree directory name.
+# Empty result (old git without --path-format, or rev-parse failure) would
+# make basename/dirname yield ".", fail-open-scoping the push — refuse instead.
+GIT_COMMON_DIR="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null || true)"
+if [ -z "$GIT_COMMON_DIR" ]; then
+  echo "[pre-push] FATAL: git rev-parse --git-common-dir failed — refusing push (would scope as '.')" >&2
+  exit 1
+fi
+REPO_NAME="$(basename "$(dirname "$GIT_COMMON_DIR")")"
+if [ -z "$REPO_NAME" ] || [ "$REPO_NAME" = "." ] || [ "$REPO_NAME" = "/" ]; then
+  echo "[pre-push] FATAL: could not derive REPO_NAME from git-common-dir='$GIT_COMMON_DIR' — refusing push" >&2
+  exit 1
+fi
+
+# Walk up from REPO_ROOT looking for the parent workspace's package.json —
+# a `.wt/<name>` worktree sits one level deeper than a regular checkout.
+PARENT_DIR=""
+DIR="$(dirname "$REPO_ROOT")"
+while [ "$DIR" != "/" ]; do
+  if [ -f "$DIR/package.json" ] \
+     && grep -q '"name": *"cosmicdriftgamestudio"' "$DIR/package.json" 2>/dev/null; then
+    PARENT_DIR="$DIR"
+    break
+  fi
+  DIR="$(dirname "$DIR")"
+done
+
+if git -C "$REPO_ROOT" ls-files --error-unmatch scripts/pre-push-extra.sh >/dev/null 2>&1 \
+   && [ -x "$REPO_ROOT/scripts/pre-push-extra.sh" ]; then
+  echo "[pre-push] running scripts/pre-push-extra.sh…"
+  (cd "$REPO_ROOT" && KUMIKO_PUSH_REPO_ROOT="$REPO_ROOT" KUMIKO_PUSH_PARENT_DIR="$PARENT_DIR" "$REPO_ROOT/scripts/pre-push-extra.sh" "$@") || exit 1
+fi
+
+# infra#559/#569: from a worktree, `--git-common-dir` resolves to the main
+# checkout's .git, so the branch below would scope `bun check` to the
+# canonical sibling path instead of this worktree — checking the wrong
+# code. Run the worktree-local check only when scripts/check-wt.sh is
+# tracked and executable (untracked/symlink stubs must not hijack push).
+if [ "$(git rev-parse --git-dir)" != "$(git rev-parse --git-common-dir)" ] \
+   && git -C "$REPO_ROOT" ls-files --error-unmatch scripts/check-wt.sh >/dev/null 2>&1 \
+   && [ -x "$REPO_ROOT/scripts/check-wt.sh" ]; then
+  echo "[pre-push] worktree detected — worktree check (see scripts/check-wt.sh)…"
+  cd "$REPO_ROOT" && exec "$REPO_ROOT/scripts/check-wt.sh"
+fi
+
+if [ -n "$PARENT_DIR" ]; then
+  echo "[pre-push] bun check (scoped: $REPO_NAME)…"
+  # KUMIKO_PUSH_REPO_ROOT forwards this checkout to guards that need it
+  # (worktrees with scripts/check-wt.sh take the branch above and skip this path).
+  cd "$PARENT_DIR" && KUMIKO_CLI_SCOPE="$REPO_NAME" KUMIKO_PUSH_REPO_ROOT="$REPO_ROOT" bun kumiko-framework/bin/kumiko.ts check
+else
+  echo "[pre-push] bun run test (standalone)…"
+  # `bun test` globs everything the default bunfig doesn't exclude, including
+  # integration tests; the package.json `test` script carries the repo's own
+  # exclusions (e.g. integration suites needing infra this hook doesn't have).
+  cd "$REPO_ROOT" && bun run test
+fi

package/src/run-guards.ts

@@ -11,6 +11,7 @@ import {
   buildSharedProject,
   cliFlagsError,
   explainGuards,
+  filesForGuard,
   isSecurityGuard,
   printGuardKitBanner,
   reportResults,
@@ -95,31 +96,61 @@ export const GUARD_FLAGS = [
   "--explain",
   "--write-security-baseline",
   "--strict-security-baseline",
+  "--write-baseline",
 ] as const;
 
+const GUARD_NAME_PREFIX = "--guard=";
+
 // Shared by the direct `bun run-guards.ts` invocation below and by the
 // `guards` subcommand in cli.ts — one place for the flag behavior so the
 // two entry points can never drift.
 export function runGuardsCli(argv: readonly string[]): number {
-  const flagsError = cliFlagsError("guards", argv, GUARD_FLAGS);
+  const guardNameArg = argv.find((arg) => arg.startsWith(GUARD_NAME_PREFIX));
+  const flags = guardNameArg === undefined ? argv : argv.filter((arg) => arg !== guardNameArg);
+  const flagsError = cliFlagsError("guards", flags, GUARD_FLAGS);
   if (flagsError !== undefined) {
     console.error(flagsError);
     return 1;
   }
-  if (argv.includes("--explain")) {
+  if (flags.includes("--explain")) {
     for (const line of explainGuards(GUARDS, buildSharedProject(GUARDS))) {
       console.log(line);
     }
     return 0;
   }
-  if (argv.includes("--write-security-baseline")) {
+  if (flags.includes("--write-security-baseline")) {
     writeSecurityBaselines(
       GUARDS.filter(isSecurityGuard),
       buildSharedProject(GUARDS.filter(isSecurityGuard)),
     );
     return 0;
   }
-  const strictSecurityBaseline = argv.includes("--strict-security-baseline");
+  // --write-baseline always needs --guard=<name> — baselines get frozen
+  // deliberately, one at a time, never as a drive-by "refreeze everything".
+  if (flags.includes("--write-baseline")) {
+    if (guardNameArg === undefined) {
+      console.error(
+        "--write-baseline needs --guard=<name>. Freeze a baseline only deliberately, one guard at a time — fix the cause first (https://github.com/CosmicDriftGameStudio/kumiko-framework/blob/main/docs/guides/test-failures.md).",
+      );
+      return 1;
+    }
+    const guardName = guardNameArg.slice(GUARD_NAME_PREFIX.length);
+    const target = GUARDS.find((g) => g.name === guardName);
+    if (target === undefined) {
+      console.error(
+        `Unknown guard "${guardName}". Known guard names: ${GUARDS.map((g) => g.name).join(", ")}`,
+      );
+      return 1;
+    }
+    if (target.writeBaseline === undefined) {
+      console.error(`Guard "${guardName}" has no ratchet baseline to write.`);
+      return 1;
+    }
+    const project = buildSharedProject([target]);
+    target.writeBaseline(filesForGuard(project, target));
+    return 0;
+  }
+  const strictSecurityBaseline = flags.includes("--strict-security-baseline");
   const guards = strictSecurityBaseline ? GUARDS.filter(isSecurityGuard) : GUARDS;
   const project = buildSharedProject(guards);
   printGuardKitBanner(guards.length, project);