# Agent-Checkliste — vor Commit / Push / Merge > **Operative Ergänzung zu [`AGENTS.md`](../AGENTS.md).** AGENTS.md hat die Regeln/DoD/Scope — > **hier** steht das praktische „bevor du pushst, mach es lokal grün" + die Footguns aus echten Vorfällen. > Die DoD-/Scope-/Ticket-Regeln aus AGENTS.md gelten zusätzlich. ## 1. Vor JEDEM Push: lokal grün machen CI läuft auf node1 mit begrenzten Slots (~7 Min/Lauf). Fang Fehler **lokal** ab, nicht im CI. ```bash pnpm typecheck # tsc (@hivegrid/web). Andere Pakete: pnpm --filter typecheck pnpm lint # eslint --max-warnings=0 ← WARNINGS FAILEN CI, nicht ignorieren pnpm test # Core-Tests; bei breiteren Änderungen die betroffenen Pakete mit-testen ``` **Merksätze:** - **`esbuild`/`vitest` grün ≠ typecheck grün.** esbuild transpiliert ohne Typprüfung; `tsc` prüft Typen. Beide laufen lassen. - **Lint-Warnings = CI-rot.** `--max-warnings=0` ist hart. Kein `// eslint-disable` ohne Grund (wenn nötig: file-level + begründet). - **Coverage-Gate** (falls dein Modul ein Coverage-Target in `scripts/coverage-targets.json` hat): `pnpm run verify:test-coverage` — läuft vom **Repo-Root** (jsdom-Config!), siehe Footgun §3. ## 2. Passende `verify:*`-Checks vor Push Je nach Änderung die relevanten Validatoren laufen — CI bricht sonst: | Geändert | Check(s) | |---|---| | `.gitea/workflows/*.yml` | `pnpm run verify:gitea-ci-workflow` · `verify:deploy-workflow` | | **Neues `packages/`** | `pnpm run verify:docker-baseline` ← **Dockerfile deps-Target braucht `COPY packages//package.json`** (sonst Deploy rot, §3) | | **Neues Prisma-Modell mit `tenantId`** | `TENANT_SCOPED_MODELS` in `packages/cli/src/commands/tenant/models.ts` ergänzen (Eltern vor Cascade-Kindern) + RLS-Policy in `prisma/rls/-isolation.sql`. Test: `packages/cli/.../tenant/models.test.ts` (§3) | | **Neue Default-Permission** | In **alle vier** Registries: `packages/db/.../permissions-seed.server.ts` (Seed + Rollen-Grant) · `apps/web/app/application/dtos/shared/DefaultPermissions.ts` (Enum) · `apps/web/app/components/core/roles/roleDisplay.ts` (Scope- + Action-Map) · `translations.json` unter `models.permission.defaultPermissions.{scopes,actions}` (de **und** en). Tests: `rolesAndPermissionsService.role-matrix` + `roleDisplay` (§3) | | **`prisma/schema/**` geändert** | `pnpm run verify:migrations-parity` ← Schema ohne Merge-Migration = CI rot (AD-21-Gate; braucht Docker). Auf dem Branch mit `db push` arbeiten ist ok, aber **vor dem Merge** muss die Migration existieren | | Dockerfile / Runtime | `verify:docker-baseline` · `verify:docker-non-root` | | UI-Texte | `pnpm run verify:i18n` (keine hartkodierten Strings) | | Allgemein | `verify:ci-baseline` · `verify:source-health` | ## 3. Footguns aus echten Vorfällen - **Neues Workspace-Paket → Dockerfile-COPY-Zeile.** Jedes `packages/` braucht `COPY packages//package.json packages//package.json` im Dockerfile deps-Target (alphabetisch, vor `pnpm install`). `verify:docker-baseline` prüft das. Vergessen = **Deploy bricht erst NACH dem Merge** im Preflight (2026-06-28: `packages/integrations`, Hotfix PR #8). Der Docker-Build selbst + ci.yml tolerierten es früher — jetzt prüft ci.yml es mit. - **Neues `tenantId`-Modell lebt in mehreren Registries.** Modell + RLS-SQL reicht NICHT: `TENANT_SCOPED_MODELS` (Backup/Restore, `packages/cli/.../tenant/models.ts`) muss es kennen, sonst `tenant/models.test.ts` rot. Eltern **vor** Cascade-Kindern listen (Restore-Reihenfolge). (AK-P17b, CI-Fund 2026-06-28) - **Default-Permission lebt in 4 Registries.** Nur in den Seed schreiben reicht NICHT (siehe §2): `role-matrix`-Test verlangt den Eintrag im `DefaultPermissions`-Enum, `roleDisplay`-Test verlangt Scope- **und** Action-Mapping in `roleDisplay.ts` **plus** Übersetzungen unter `models.permission.defaultPermissions.{scopes,actions}` (de+en). Bei mehrstufigem Scope **flache** Keys (`hr.leave` → `hrLeave`), sonst Pfad-Kollision mit dem `hr`-String-Leaf. (AK-P17b) - **Kein `"…"` (doppelte Anführungszeichen) in Kommentaren im `defaultPermissionSeeds`-Array.** Der `roleDisplay`-Test **regex-extrahiert jedes doppelt-gequotete Literal im Array** als Permission-Namen — ein zitiertes Wort im Kommentar wird zur Phantom-Permission und bricht den Test (`… is not valid JSON`). Im Kommentar einfache Anführungszeichen / Backticks nutzen. (AK-P17b) - **Coverage-Gate läuft vom Repo-Root (jsdom).** Tests, die Node-Kontext brauchen (`fs`, `process`), mit `// @vitest-environment node` pinnen. **Kein `process.chdir`** in parallelen Tests (race). `vi.mock` **leakt** zwischen Files in shared Workers → Mocks pro File isolieren / `vi.restoreAllMocks`. - **`.server.ts`-Re-Export ist verboten** (RR7-Client-Build bricht). Stattdessen Component-Extraktion. - **pre-push-Hook blockt?** Erst die Checks **manuell** laufen + Ursache fixen — nicht blind `git push --no-verify`. `--no-verify` nur, wenn der Hook-Fehler nachweislich irrelevant ist (z.B. Hook-Timeout, kein echter Lint-/Typ-Fehler). ## 4. Branch / PR / Merge - **Nie direkt auf `main` pushen** → Branch + PR (Squash-Merge). - **Parallel-Schema (AD-21):** Modul = eigene `prisma/schema/.prisma`; am Branch `prisma db push`, **Migration erst beim Merge** (forward-only + Inverse-SQL als Kommentar, aus dem Nichts reproduzierbar — `DO $$ … IF [NOT] EXISTS … $$`-Guards). - **Deploy-Path-Filter:** test-/doc-/workflow-only-Merges (`**/*.test.*`, `docs/**`, `.planning/**`, `.gitea/workflows/**`, `*.md`) skippen den Staging-Deploy automatisch. Code-Änderungen triggern ihn. - **Abhängige nicht brechen:** bei Contract-/`core.prisma`-/Querschnitt-Änderungen `blocked-by` UND `blocks` lesen, Konsumenten nachziehen, Auswirkung dokumentieren. ## 5. Secrets & Ticket-Abschluss - **Secrets** nie ins Repo/Chat/CI-Log. Per-User-Token in `~/.cli-tokens/` (chmod 600); geteilte Dev-`.env` via `pnpm env:pull` (SOPS). - **Strikt im Ticket-Scope.** Verbesserungen nur als **„💡 Vorschlag (außerhalb Ticket-Scope)"** ausweisen, nie still einbauen. Fortschritt als **% der DoD** melden; Done erst bei 100 %. - **Abschluss-Reihenfolge:** Umsetzungs-Notiz (Datum + Proof) in der Ticket-Doc → Plane-Kommentar (1. Person, kein AI-Sprech, keine Em-Dashes) → Ticket auf Done.