HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/docs/AGENT-CHECKLIST.md

Agent-Checkliste — vor Commit / Push / Merge

Operative Ergänzung zu 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.

pnpm typecheck   # tsc (@hivegrid/web). Andere Pakete: pnpm --filter <pkg> 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/<x>	pnpm run verify:docker-baseline ← Dockerfile deps-Target braucht COPY packages/<x>/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/<modul>-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/<x> braucht COPY packages/<x>/package.json packages/<x>/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/<modul>.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.