Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/docs/AGENT-CHECKLIST.md
T
2026-07-08 16:15:37 +02:00

59 lines
6.2 KiB
Markdown

# 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 <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.