Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/AGENTS.md
T
raffaelandClaude Opus 5.5 d09f79b673 chore(infra): Gitea-Host auf git.hg-int.dev umstellen
Gitea läuft seit 2026-11-11 auf hivegrid-control (git.hg-int.dev);
git.tool-ctrl.de wird abgeschaltet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 18:53:32 +01:00

558 lines
46 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# HiveGrid 2.0 — Agent-Regeln
Zentrale Regel-Datei für AI-Agents (Coding-Agents, HiveGrid-Worker), die an HiveGrid arbeiten.
**Letzte Aktualisierung:** 2026-08-02
**Architektur-Vertrag:** Diese Datei enthält die operativen Regeln; `.planning/ENTITY-MODEL.md`
besitzt das Datenmodell. `docs/ARCHITECTURE-DECISIONS.md` ist das kompakte Entscheidungsregister
mit IDs, Gründen und Status, aber kein zweites Regelwerk.
## Arbeitsmodus & Wo-finde-ich-was (Stand 16.06.)
**Team — 2 Devs bauen PARALLEL** (+ David = Screens/Subframe, Dejan = Website, Haris = Vertrieb):
- **Raffael** — kritische Kern-Kette, SEQUENZIELL: P1 → P2 → P5 → P6 → P7 → P8 → P9 → P11 → P12. **P13 entfällt nach AD-26** (kein v1-KI-Layer); v2-Neuschnitt ist `VR-MCP`/`VD-MCP`.
- **Akeshan** — unabhängige Trabanten parallel dazu: Infra, P3, P4, P17, P19, dann (nach P5) P14, P15, P16, P20, P21.
- **Sync-Punkt:** P14/P15/P16 brauchen Raffaels P5 (Apps-Engine). **Parallel-Regel (AD-21):** jedes Modul bekommt eine eigene `prisma/schema/<modul>.prisma`; auf dem Feature-Branch `prisma db push`, **Migration erst beim Merge** — sonst Konflikte im Schema/in der Migrations-Historie. `core.prisma`/`accounts.prisma` nur für Relationen zu Tenant/User anfassen. Siehe §„Prisma-Schema & Migrationen".
**Arbeitsmodus:** Wir arbeiten ausschließlich **ticket-getrieben** über Plane und die zugehörigen Ticket-Docs.
**Ein Ticket bauen:** Du bekommst eine Ticket-ID → lies `.planning/ticket-docs/<ID>.md` (self-contained Bau-Spec: Was/Screens/DoD/Technische-Bausteine/Quellen/Abhängigkeiten) **und** diese AGENTS.md. Voller Einstiegs-Prompt + Designer-first-Regel (UI wartet auf „Davids Delta" im Screen-Ticket): **`.planning/ticket-docs/README.md`**. **Interim-UI-Regel (AD-28):** UI-lastige Tickets bleiben nicht bis zu Davids Delta auf „On Hold" — der Dev baut eine **Interim-UI (Vorschau-Screen) aus `~/ui`** (VM als Prop, kein handgeschriebenes Tailwind) und stellt das Ticket damit fertig; die finale Subframe-Optik wird ein **getrackter Nachzug** (Label `design-nachzug`), nicht Done-blockierend. Details: **`.planning/INTERIM-UI-PLAYBOOK.md`**. Vor dem Bauen die `blocked-by` aus der Doc prüfen. **Strikt im Ticket-/Ticket-Doc-Scope bleiben, Verbesserungen nur explizit ausgewiesen vorschlagen, Fortschritt als % der DoD melden** → siehe §„Ticket-Treue, Verbesserungs-Vorschläge & Fortschritt". **Die Arbeit während der Umsetzung an atomaren Checkpoints committen** → siehe §„Atomare Commit-Checkpoints". Vor jedem Commit die passenden fokussierten Checks, vor jedem Push die vollständige operative Checkliste [`docs/AGENT-CHECKLIST.md`](docs/AGENT-CHECKLIST.md) abarbeiten (lokal typecheck+lint+test grün, passende `verify:*`, Footguns).
**Wo finde ich was:**
| Was | Wo |
|---|---|
| **Bau-Spec je Ticket (EINSTIEG)** | `.planning/ticket-docs/<ID>.md` (157 Tickets, je 1 verlinkte Datei) |
| Ticket ohne Codeänderung planen | `.agents/skills/plan-ticket/SKILL.md` |
| Subframe-Seiten/-Deltas integrieren | `.agents/skills/subframe-einbinden/SKILL.md` |
| Datenmodell — LOCKED, **Vorrang bei P6–P9** | `.planning/ENTITY-MODEL.md` (+ `entity-model.dbml`) |
| Phasen v1/v2 + Ziele/SC | `.planning/ROADMAP.md` · `.planning/ROADMAP-V2.md` |
| Reihenfolge (Ticket an Start-Tag) | `.planning/SPRINT-DAYPLAN.md` |
| Requirements je Modul | `.planning/REQUIREMENTS.md` |
| Screen-Briefs (Designer) | `.planning/designer-briefs/PXX.md` |
| **Architektur-Vertrag (operativ)** | diese `AGENTS.md` + `.planning/ENTITY-MODEL.md` |
| Entscheidungsregister / Warum | `docs/ARCHITECTURE-DECISIONS.md` |
| **Pre-Push/Pre-Merge-Checkliste** | `docs/AGENT-CHECKLIST.md` (lokal grün: typecheck+lint+test · `verify:*` · Footguns) |
| Live-Tickets/Status/Cycles | Plane: `project.tool-ctrl.de`, Projekt HiveGrid |
**Agent-Skills:** Der kanonische Workflow liegt unter `.agents/skills/`.
Claude Code entdeckt Projekt-Skills ausschließlich unter `.claude/skills/`;
dort liegen deshalb nur kleine, getrackte Discovery-Shims, die auf den
kanonischen Workflow verweisen. Workflow-Inhalte nie doppelt pflegen.
**Datenmodell-Vertrag:** `.planning/ENTITY-MODEL.md` ist alleinige Quelle für das Projekt-zentrische
Modell (AD-20: ein `Projekt`-Kern, Pipelines=Views, „Deal"/„Auftrag"=Typen, Lead→Projekt,
kein Won-Handoff).
## Plane-Tracking (Ticket-System — gleicher Standard für beide Devs)
**Wo:** self-hosted Plane `https://project.tool-ctrl.de`, Workspace `toolctrl`, **Projekt HiveGrid** = `35d0d968-8ab3-40cc-97b8-b81d917dc5df` (NICHT PowerLinked!). REST: `{BASE}/api/v1/workspaces/{WORKSPACE}/projects/{PROJECT}/…`, Auth-Header `X-API-Key`.
**Zugang — kanonisch über Environment-Variablen (identische Namen bei Raffael + Akeshan):**
`PLANE_API_KEY` (persönlich je Dev — **nie ins Repo/Git**) · `PLANE_BASE_URL=https://project.tool-ctrl.de` · `PLANE_WORKSPACE=toolctrl` · `PLANE_PROJECT=35d0d968-…`.
Fallback, wenn Env leer: dieselben 4 Keys aus `~/.cli-tokens/plane` (Zeilen `KEY=VALUE`).
**Wer wird imitiert? (vor jeder Schreibaktion prüfen):** Der `PLANE_API_KEY` ist persönlich → Kommentare/Assignee erscheinen unter *diesem* User. Identität verlässlich über `GET {BASE}/api/v1/users/me/` (liefert den User des Keys). **Nicht** an der git-Mail festmachen (Maschine kann `node1@…` sein, Plane-User aber `raffael@…`). Ergebnis muss zum Dev der Maschine passen → bei Mismatch STOP + melden.
**Member-IDs:** raffael `8e34a88c…` · akeshan `8bf43e86…` · david `6c1fc63f…` · dejan `a5883f5e…` · haris `48367c1f…`.
**Skripte:** `.planning/plane-sync/` — `dump_snapshot.py` (read-only Snapshot), Pflege idempotent via `scrub_plane.py`. Module=Tracks, Cycles=Wochen, blocked-by=JIT.
**Ticket abschließen (verbindliche Reihenfolge):** 1) `.planning/ticket-docs/<ID>.md`: Umsetzungs-Notiz mit **Datum + kurzem Proof** (Commits/Tests/Deploy-Run) + DoD abhaken + **%-Done-Stand** (siehe §„Ticket-Treue, Verbesserungs-Vorschläge & Fortschritt"). 2) Plane-Kommentar — **schlicht, 1. Person (= imitierter User), kein AI-Sprech, keine Em-Dashes (—)**. 3) Ticket auf **Done** — nur bei **100 % DoD**.
**Übersichten:** Done-Tickets ausblenden, nur offene Arbeit zeigen.
## Ticket-Änderungen dependency-aware (verbindlich)
Vor jeder maßgeblichen Ticket-Änderung (Start-/Zieldatum, Scope, Assignee/Owner) **oder** Code, der `blocks`-Tickets betrifft (Contracts aus `R-P1a`, `core.prisma`, Querschnitt-Services M001–M017):
1. **Beide Richtungen lesen:** `blocked-by` UND `blocks` — in Plane *und* in den `.planning/ticket-docs/`-Docs der Abhängigen.
2. **Abhängige nicht brechen:** Änderung so wählen, dass blockierte/folgende Tickets konsistent bleiben (z.B. Start-Datum nie hinter Ziel-/Vorgänger-Datum schieben; keine Contract-/Schema-Änderung ohne Nachzug der Konsumenten).
3. **Auswirkung dokumentieren** — in der eigenen Ticket-Doc *und* im betroffenen abhängigen Ticket (Muster: AD-23 → Eintrag in `AK-P4a`).
4. **„Fertig" heißt:** Abhängige bleiben grün (Tests/Typecheck) — proaktiv prüfen, nicht erst bei Bruch reagieren.
## Lokale Dev-Secrets (SOPS + age)
Geteilte Dev-`.env`-Werte liegen **verschlüsselt** in `secrets/dev.sops.env` (SOPS+age, beide Devs als Recipients). `pnpm env:pull` entschlüsselt nach `./.env`, `pnpm env:edit` ändert sie. Onboarding/Regeln: `secrets/README.md`. Der age-Private-Key bleibt lokal (`~/.config/sops/age/keys.txt`), **nie ins Repo**. Nur geteilte API-Keys liegen im Blob; lokale DB/Redis = Defaults aus `.env.example`.
## Session-Isolation mit Worktree und Branch (verbindlich)
**Jede neue mutierende Dev-/Agent-Session arbeitet in einem neuen Worktree auf einem neuen Branch.**
Ein bestehender Worktree oder Branch wird nicht für ein anderes Ticket, einen neuen Auftrag oder einen
Folge-Fix wiederverwendet. Rein lesende Diagnose darf in einem vorhandenen Worktree laufen; vor der ersten
Dateiänderung muss die Session isoliert werden.
Start aus einem vorhandenen Clone:
```bash
pnpm session:start -- <type>/<kurzer-slug>
```
Der Helfer fetcht den aktuellen `origin/main`, verweigert bereits vorhandene lokale oder Remote-Branches,
legt einen neuen Geschwister-Worktree mit neuem Branch an, entschlüsselt die `.env` atomar und installiert
mit `pnpm install --frozen-lockfile`. Danach arbeitet die Session ausschließlich im ausgegebenen
Worktree. Ein optionaler Zielpfad ist mit `--path <absoluter-pfad>` möglich.
Die `.env`-Hydrierung setzt auf macOS/Linux automatisch den kanonischen Age-Key
`~/.config/sops/age/keys.txt` als `SOPS_AGE_KEY_FILE`, schreibt erst nach erfolgreicher Entschlüsselung
und ersetzt `.env` atomar mit Modus `0600`. Ein SOPS-/Key-Fehler darf weder eine leere `.env` noch einen
halb eingerichteten Session-Worktree hinterlassen.
Ein Session-Worktree wird erst nach dem PR-Abschluss aufgeräumt:
```bash
pnpm session:finish -- <type>/<kurzer-slug>
```
Der Cleanup ist fail-closed und darf nur fortfahren, wenn der Worktree sauber ist, der lokale und
gegebenenfalls Remote-Head identisch sind, der Feature-Head Vorfahr des aktuellen `origin/main` ist und
ein **normaler Merge-Commit** den Feature-Head als Nicht-First-Parent aufgenommen hat. Squash-, Rebase-only-
und Fast-Forward-Merges zählen nicht. Vor einer Remote-Löschung müssen persönliche Gitea-Identität,
`active=true` und ein geschlossener PR bestätigt sein. Danach werden Remote-Branch, Worktree und lokaler
Branch verifiziert entfernt. Kein manueller `rm -rf`, kein `git branch -D` und kein Löschen eines dirty,
ungemergten oder weitergelaufenen Branches.
## Atomare Commit-Checkpoints (verbindlich)
**Agents committen während der Umsetzung, nicht erst auf Nachfrage oder gesammelt am Ende.** Lokale Commits
im aktiven Session-Branch gehören zum normalen Arbeitsablauf; ein Push braucht weiterhin einen eigenen,
vollständig grünen Abschluss-Checkpoint.
Ein Commit enthält genau **eine fachlich benennbare, separat revertierbare Änderung** einschließlich ihrer
direkt gekoppelten Tests, Typen, Übersetzungen und generierten Artefakte. Bevor ein zweites unabhängiges
Thema begonnen wird, muss das erste Thema fokussiert geprüft und committed sein. Unfertige Zwischenzustände,
die allein nicht bauen oder den Contract brechen, werden nicht künstlich getrennt.
**Verbindliche Commit-Grenzen:**
1. Ein eigenständig beschreibbarer Bug oder ein sichtbares Verhalten ist fertig und fokussiert getestet.
2. Eine Route bzw. eine zusammengehörige Routenfamilie ist verschoben, inklusive Navigation, Redirects und
Routentests.
3. Ein Feature, Modell oder Alt-Modul ist vollständig entfernt, inklusive direkt abhängiger Artefakte.
4. Eine Schema-/Migrationsänderung samt zwingend gekoppeltem Client-/RLS-Nachzug ist konsistent.
5. Während der Arbeit taucht ein unabhängiger Refactor, Tooling-Fix, Test-Fix oder Doku-Nachzug auf. Dieser
wird nicht in den laufenden Fach-Commit gemischt, sondern erhält einen eigenen Commit.
6. Vor einem Kontextwechsel, einer längeren Diagnose oder dem Beginn des nächsten Plan-/DoD-Punkts.
**Größenbremse vor jedem Commit:**
- `git diff --cached --name-only` und `git diff --cached --stat` prüfen; nie blind `git add -A`, wenn mehr
als ein Checkpoint offen ist.
- Ab **25 Dateien oder 800 geänderten Zeilen** ohne reine Generierung, Migration oder Massendeletion muss
der Agent stoppen und den Staging-Inhalt in kleinere fachliche Einheiten zerlegen. Eine Überschreitung
ist nur zulässig, wenn alle Dateien nachweislich zu derselben untrennbaren Änderung gehören; der Grund
wird in der Abschlussmeldung genannt.
- Ein Sammelcommit mit mehreren unabhängigen Themen wird nicht erstellt, auch nicht mit dem Vorsatz, ihn
später noch zu splitten. Falls das versehentlich passiert, wird die lokale Historie vor Übergabe
korrigiert.
Pro Checkpoint laufen mindestens `git diff --cached --check`, die fokussierten Tests und der Typecheck der
betroffenen Pakete. Die vollständigen `pnpm typecheck && pnpm lint && pnpm test` sowie passende
`verify:*`-Gates laufen spätestens vor Push/PR; Details stehen in `docs/AGENT-CHECKLIST.md`.
## Staging-Credentials: keine Rotation ohne Auftrag (verbindlich)
Für **Staging** werden Credentials, Secrets, API-Keys und OAuth-Client-Secrets grundsätzlich **nicht**
automatisch rotiert, ersetzt oder widerrufen. Agents dürfen eine Rotation nur nach ausdrücklicher Anweisung
des Users in der aktuellen Aufgabe ausführen oder als Voraussetzung für einen Staging-Test bzw. -Deploy
behandeln. Ein möglicher Leak wird gemeldet und dokumentiert, löst aber keine eigenmächtige Rotation oder
pauschale Staging-Sperre aus. Produktion bleibt davon unberührt. Die providerseitige, protokollbedingte
Refresh-Token-Rotation eines OAuth-Flows ist keine manuelle Credential-Rotation und bleibt technisch aktiv.
## Kanonische lokale Login-Daten (verbindlich)
Für ausschließlich lokale, wegwerfbare Dev-Datenbanken gilt: Der Plattform-Admin für
`http://admin.localhost:3000` ist **immer** `admin@email.com`; sein Passwort ist **immer**
`password`. Abweichende lokale `AdminUser`-Identitäten werden demotet; nur der kanonische Admin
erhält die globale `SuperAdmin`-Rolle. Alle lokalen Plattform- und Portal-Benutzer mit
Passwort-Login erhalten ebenfalls `password`; absichtlich passwortlose Magic-Link-Identitäten
bleiben passwortlos.
Der kanonische Startbefehl ist `pnpm dev:local`. Er lädt `.env`/`.env.local`, aktiviert den nur für
`admin@email.com` erlaubten lokalen Admin-Fallback und stellt die Login-Daten vor jedem Start
idempotent wieder her. Ein rohes `pnpm dev` startet nur den Web-Prozess und erfüllt diesen lokalen
Credential-Vertrag nicht.
Diese Vereinfachung gilt **niemals** für CI, Staging oder Produktion. Die Normalisierung muss bei
`NODE_ENV !== "development"`, `RLS_RUNTIME_MODE=required`, gesetztem `SENTRY_ENVIRONMENT`, einem
nicht über Loopback erreichbaren PostgreSQL-Ziel, Connection-String-Queryparametern oder einer DB
ohne den Datenbank-Marker `app.local_dev_credentials=enabled` fail-closed abbrechen. Frische
lokale Compose-Datenbanken erhalten den Marker beim Init; bestehende lokale Compose-Volumes werden
einmalig und ausschließlich über `pnpm dev:services:mark-local` markiert. Der allgemeine Seed-Pfad
darf diese Guards nicht umgehen. Die Production-/Staging-Gates bleiben unverändert scharf.
## Bespoke-HiveGrid auf ehemaligem Boilerplate-Fundament — kritisch
**HiveGrid wird bespoke gebaut.** Das `HiveGrid-Cloud/`-Repo stammt historisch aus der EU-sterilisierten Boilerplate und nutzt weiterhin sinnvolle Fundament-Pakete, aber wir planen **keine laufende Upstream-Produktmerge-Strategie mehr**. Boilerplate-Reste sind Arbeitsmaterial, kein Produktziel. Du editierst, erweiterst und löschst sie, wenn HiveGrid dadurch kohärenter wird.
Konkret:
- `apps/web/`, `apps/api/`, `apps/worker/`, `packages/db/`, `packages/mail/`, `packages/queue/`, `packages/ui*`, alles weitere → das ist deine Arbeitsbasis
- `package.json` mit pnpm-Workspace, Prisma, BullMQ, Mailjet, shadcn/Radix → bestehender Stack, den du nutzt
- Du erweiterst, was fehlt (z. B. neue `packages/view-models/`, `packages/ui-app/`, neue Routes)
- Du löschst, was nicht zu HiveGrid gehört (Affiliate-Reste, Scaffolder, Demo-/Marketing-Boilerplate, Storybook-/Docs-Ballast, falls nicht mehr gebraucht)
- Du baust neue Module **in** dieser Codebase, nicht **neben** ihr
**Pre-Flight-Check beim Start (jedes Mal):**
1. Für die mutierende Session wurde mit `pnpm session:start -- <branch>` ein neuer Worktree/Branch vom
aktuellen `origin/main` erstellt und als Arbeitsverzeichnis gewählt → wenn nein: STOP
2. `package.json` im Repo-Root existiert mit pnpm-Workspace-Konfig → wenn nein: STOP, melde „Workspace-Inhalt fehlt"
3. `apps/`, `packages/`, `prisma/` existieren → wenn nein: STOP
4. **Kein redundanter Baseline-Typecheck/-Test auf frischem `main`:** Wenn der Worktree sauber ist und
nach einem frischen Fetch exakt auf `origin/main` basiert (direkt durch `pnpm session:start` oder
konfliktfrei per `--ff-only` synchronisiert), werden beim Start **weder `pnpm typecheck` noch
`pnpm test`** ausgeführt. Die grünen Merge-Gates von `main` sind für diesen unveränderten Stand
maßgeblich; den Entwickler-Rechner nur zur Wiederholung derselben Baseline zu belasten ist verboten.
Erst nach eigenen Codeänderungen laufen fokussierte Checks an den atomaren Checkpoints und die
vollständigen Gates gemäß `docs/AGENT-CHECKLIST.md` vor Push/PR. Baseline-Checks sind nur zulässig,
wenn der Worktree von `origin/main` abweicht oder eine konkrete Diagnose sie erfordert.
5. Keine US-Provider-Imports mehr (`grep -rE "@ai-sdk/openai[^-]|@ai-sdk/anthropic|remix-auth-google" --include="*.ts"` leer) → wenn nein: STOP, EU-Sterilisation nicht abgeschlossen. (`@ai-sdk/openai-compatible` ist zwar provider-neutral, führt nach AD-26 aber nicht zu neuem v1/v2-LLM-Scope.)
Erst danach beginnst du mit dem Ticket.
## Naming-Konvention (Stand 2026-07-01, Bespoke-Re-Cut)
**Wichtige Korrektur:** Dieses Repo hat einen Boilerplate-Ursprung, aber HiveGrid wird bespoke weitergeführt. Stabilität im laufenden Code zählt mehr als künstliche Upstream-Mergebarkeit.
- **Alle Workspace-Pakete nutzen den `@hivegrid/*`-Scope** (z.B. `@hivegrid/foundation`,
`@hivegrid/view-models`, `@hivegrid/db`, `@hivegrid/search`, `@hivegrid/cli`). Es gibt keine
Alt-Scope-Aliase und keine parallel gepflegten Alt-Namen.
- **UI-Pakete heißen real `packages/ui-app`, `packages/ui-subframe`, `packages/ui-mock`** —
NICHT `packages/ui-hivegrid`. Alte `ui-hivegrid`-Erwähnungen sind Doku-Drift und zu korrigieren.
- Pfad-Korrekturen ggü. älteren Docs: Sidebar liegt in `apps/web/app/application/sidebar/`
(nicht `sidebar.config.ts`); Such-Index/`indexedEntities` gehört nach `packages/search/`
(nicht `packages/db/src/search/indexed-entities.ts`).
Die DoD-, Anti-Pattern- und Workflow-Pfade unten nennen ab hier bereits die realen Pfade (`packages/ui-app`, `apps/web/app/application/sidebar/`, `packages/search/`).
## Quellenverantwortung und Status
Es gibt keine globale Rangliste für unterschiedliche Dokumenttypen; jede Quelle besitzt einen klaren
Verantwortungsbereich:
1. **Ticket-Doc** `.planning/ticket-docs/<ID>.md` — ausführbarer Scope, Abhängigkeiten und DoD.
2. **Diese `AGENTS.md`** — repo-weite Architektur-, Sicherheits- und Arbeitsregeln. Eine Ticket-Doc darf
diese Grenzen nicht still lockern.
3. **Entity Model** `.planning/ENTITY-MODEL.md` — alleinige Quelle für Datenmodell und Projekt-Pivot.
4. **Requirements/Roadmaps** `.planning/REQUIREMENTS.md`, `ROADMAP.md`, `ROADMAP-V2.md` — Modulabdeckung
und Reihenfolge.
5. **Entscheidungsregister** `docs/ARCHITECTURE-DECISIONS.md` — IDs, Gründe und Status; keine zweite
operative Regelsammlung.
6. Ersetzte Produktplanungen sind ausschließlich über die Git-Historie verfügbar und keine Bauquelle.
Ein genehmigter Change-Request aktualisiert immer die zuständige operative Quelle und die betroffenen
Ticket-Docs. Ein Eintrag nur im Entscheidungsregister genügt nicht.
Operativer Status, Owner, Cycles und Abhängigkeiten liegen ausschließlich in Plane. Umsetzung und Proof werden in der Ticket-Doc dokumentiert; es gibt keinen parallelen Milestone-Tracker.
## Architektur-Baseline (operativ)
Diese Kurzfassung ist beim Bauen bindend. Die AD-Nummern dienen nur der Rückverfolgbarkeit ins
Entscheidungsregister.
| Bereich | Verbindlicher Vertrag |
|---|---|
| **Tenant-Sicherheit (AD-1)** | Postgres erzwingt RLS; App-/Worker-Rollen haben kein `BYPASSRLS`. Jeder DB-Pfad bindet User-/Tenant-Kontext, jede neue Tabelle erhält Policy und Contract-Gate. |
| **Fachmodelle (AD-2/20)** | Neue Fachentitäten sind typisierte Prisma-Modelle. Kein neuer Entity-Builder-Konsument. CRM bleibt projekt-zentrisch: ein `Projekt`-Kern, Pipelines als Views, Lead → Projekt. |
| **Admin und Sessions (AD-3/4)** | Plattform-Admins sind von Tenant-Identitäten getrennt und nutzen produktiv nur Authentik-OIDC. Sessions liegen in Postgres; Redis ist Cache, Cookies enthalten nur die Referenz. |
| **Secrets und Medien (AD-8/22/23)** | Tenant-Credentials nutzen DEK-Envelope-Encryption; GeoIP bleibt lokal und minimal; Uploads bleiben privat und werden nur über geprüfte App-/Signaturpfade ausgeliefert. |
| **Suche, Mail, Captcha (AD-5/6/7)** | Meilisearch ist keyword-only und SQL wird revalidiert; Mail läuft über Mailjet; Captcha ist self-hosted (`mCaptcha` oder `Cap`), nicht Google/Cloudflare/hCaptcha. |
| **Realtime, Naming, Mobile (AD-9/10/17)** | Chat nutzt WebSocket, Read-Updates SSE; Produktcode heißt ausschließlich `@hivegrid/*`; Mobile bleibt in v1/v2 PWA-only. |
| **Prisma (AD-21)** | Ein Modul = eine Schema-Datei; Shared-Core nur minimal ändern; Branch = `db push`, lineare Forward-only-Migration beim Merge. |
| **Signatur (AD-25)** | Self-hosted gehärtete SES ist Default, PandaDoc nur Tenant-BYOK; QES bleibt späteres Add-on. Vor Produktivfreigabe juristisch bestätigen. |
| **KI/MCP (AD-26)** | Kein eigenes LLM/RAG/Whisper in v1/v2. Externe KI-Clients nutzen den getrennten, tenant- und permission-gescopten MCP-Service. |
| **Billing (AD-27)** | HiveGrid hält Entitlements, Lago Billing/Invoices, Mollie Zahlungen. Kein v1-Usage-Billing und keine Fachdaten beim Provider. |
| **Interim-UI (AD-28)** | UI-lastige Tickets werden mit getesteter `~/ui`-Interim-UI fertig; finale Subframe-Optik bleibt als `design-nachzug` getrackt. |
| **Workspace-Rollen (AD-29)** | Neue Workspaces erhalten fünf versionierte SHK-Rollen; Owner bleibt ausschließlich globaler `Admin`; bestehende Tenants werden nicht automatisch verändert. |
| **Customer-Portal (AD-30)** | Eigenständiger Host und `hivegrid-portal`-Runtime mit eigenen Sessions, minimalem DB-Login, Entitlement-Gates und verifizierter Host→Tenant-Auflösung. |
| **Plattform-Leads (AD-31)** | HiveGrids eigene Leads liegen tenantlos in der Admin-Domäne. `lead-inbox` wird erst nach Backfill, Cutover und Drain stillgelegt. |
| **KWP (AD-32)** | Initial fachlich read-only. Nur feste Read-Allowlist; Mutationen vor HTTP gesperrt. Writeback erst nach `VEXT-6` plus erneuter ausdrücklicher Freigabe. |
## Definition of Done — verbindlicher Qualitätsrahmen für Tickets
Ein Ticket gilt nur dann als erledigt, wenn seine eigene DoD vollständig erfüllt ist. Soweit der Ticket-Scope die folgenden Flächen berührt, gelten zusätzlich diese repo-weiten Qualitätsanforderungen:
### A. Code-Layer-Trennung (PR-Block bei Verstoß)
1. Loader/Action in `app/routes/**` baut View-Model. KEIN Direkt-Import von `~/db` oder `@prisma/client` in `packages/ui-app/**`.
2. Domain-Logik in `app/domain/**` importiert NIE React oder UI.
3. View-Models in `packages/view-models/**` sind pure Funktionen ohne React/Prisma-Imports.
4. Subframe-Output in `packages/ui-subframe/**` wird NIE direkt von `app/routes/**` importiert — nur via Adapter in `packages/ui-app/src/adapters/`.
5. UI-Components rufen NIE `useLoaderData` / `useFetcher` auf — Routes injizieren VM und Action-Callbacks.
### B. Erreichbarkeit (Reachability — siehe `docs/INTEGRATION-CONTRACTS.md`)
6. **Sidebar-Eintrag** in `apps/web/app/application/sidebar/` (AppSidebar/AdminSidebar + SidebarItem) — oder Inline-Verlinkung aus bestehendem Modul, wenn das semantisch korrekt ist.
7. **Permission-Gate** auf dem Sidebar-Eintrag — Eintrag NUR sichtbar bei berechtigter Rolle.
8. **Route registriert** unter dem korrekten URL-Pattern (siehe INTEGRATION-CONTRACTS.md §3).
9. **Breadcrumbs** für Detail-Routes (siehe §4).
10. **i18n-Keys** für ALLE UI-Texte (Pflicht via M003-Build-Lint).
11. **Mobile-Tab-Bar-Eintrag**, falls das Modul mobile-relevant ist (§13).
12. **Customer-Portal-Konfiguration**, falls Endkunden das sehen sollen (§14, Default unsichtbar).
### C. Querschnitt-Wiring (Pflicht-Service-Aufrufe)
13. **Schreib-Aktion** ist auditiert (auto via M001-Prisma-Middleware oder manuell via `auditEvent`).
14. **Activity-Stream-Eintrag** auf relevanter Entität (Kontakt/Firma/Lead/Projekt) bei jeder relevanten Aktion via `logActivity`.
15. **Notifications** via M011-Service (`notify({...})`), niemals direkt Email/Push.
16. **Search-Index** registriert in `packages/search/` (indexed-entities-Registry — M00-Neubau), falls suchbar.
17. **Permission-Filter** via `withTenantScope()` + `withPermission()` (M004) — kein manueller Query-Filter im Modul-Code.
### D. Tests (PR-Block ohne)
18. **Unit-Tests** für View-Model-Builder (pure-function-test mit Fixture).
19. **Smoke-Test** in `e2e/smoke/<modul>.spec.ts` — Login → Route öffnen → Hauptaktion klicken → erwartetes Ergebnis sichtbar.
20. **Hot-Swap-Drill** (M017): Smoke-Tests müssen mit `packages/ui-mock` als Drop-in-Replacement laufen.
21. **Visual-Regression-Snapshot** (M016) für die Hauptansicht — bei Interim-UI (AD-28) gegen die **Interim-Baseline**, mit Re-Baseline-Pflicht beim David-Nachzug.
> **Interim-UI & Done (AD-28, `.planning/INTERIM-UI-PLAYBOOK.md`):** Für UI-lastige Tickets zählt als Done: **Dev-DoD 100 % + Interim-Screen aus `~/ui` (VM als Prop, kein handgeschriebenes Tailwind) + Tests grün** (B 6–10, D 18–21 gegen Interim-Baseline). Die **finale Subframe-Optik** ist dann **kein Done-Blocker**, sondern ein **getrackter Nachzug**. `/planning` bleibt Single Source of Truth: der `🎨 design-nachzug: offen`-Tag unter der Header-Tabelle der Ticket-Doc + Interim-UI-Vermerk in der „Dev-Nachzug"-Sektion sind führend; das gleichnamige Plane-Label spiegelt nur. Die Layer-Trennung (Block A) und die drei Anti-Patterns bleiben unangetastet.
### E. Klartext-Hinweise (User-facing)
22. ALLE Fehler-Texte aus M002-Catalog (kein nackter HTTP-Code, keine kryptische Stack-Trace im UI).
23. **Empty-State** mit Klartext + nächster Aktion.
24. **Loading-State** mit Klartext (kein leerer Spinner).
25. **Permission-Denied** zeigt 404, nicht 403 (siehe Bauprinzip A.5.3).
### F. Dokumentation
26. Ticket-Doc mit Umsetzungs-Notiz, Datum, Proof und %-Stand aktualisiert.
27. **Rollback-Pfad dokumentiert** in der Ticket-Doc (siehe `docs/MID-STREAM-CHANGES.md`).
28. **Forward-Only-DB-Migration** mit Inverse-SQL als Kommentar im Migration-File.
---
## Drei Anti-Patterns — sofortiger PR-Block
1. `@prisma/client` oder `~/db` in `packages/ui-app/**`
2. Direktimport aus `packages/ui-subframe` in `app/routes/**`
3. `useLoaderData<typeof loader>()` innerhalb von `packages/ui-app/**`
## Entity-Builder: KEIN neuer Konsument + Ablöse-Pflicht (AD-2, verbindlich seit 2026-06-29)
Der generische Entity-Builder (`Entity`/`Row`/`RowValue`, `modules/rows`, `utils/db/entities`, `EntitiesSingleton`, die `*Api.server`-Entity-Layer, `modules/crm`-`CrmService`-Legacy) ist **Alt-Last** und wird abgelöst — bisher nur für den CRM-Pfad raus (R-P6/R-P6B-α/R-P6C), generisch läuft er noch.
- **PR-Block:** Ein **neues** Fachmodul/Feature, das den Entity-Builder als Datenmodell nutzt (statt typisierter Prisma-Tabellen wie CRM), wird abgelehnt — wie ein Anti-Listen-Verstoß. Neue Entitäten = typisiert.
- **Pflicht (kein „optional"):** Der generische Builder MUSS vollständig abgelöst werden. Die bereits **gebauten** Konsumenten — EmailMarketing (AK-P14, dringend), WorkflowEngine, formulas, codeGenerator, onboarding, `CrmService`-Legacy — werden **typisiert abgelöst, sobald sie ohnehin angefasst werden** („Migration durch Neubau", billiger als späterer Refactor). Noch nicht gebaute Module (AK-P14b/P15/P16c/d/DEMO1) sowieso direkt typisiert.
- Konsumenten-Matrix, Reihenfolge und Ownership: `.planning/ticket-docs/R-P6B.md`
§Migrationskette & Ownership / §Rückwirkungs-Audit.
## Daten-Fluss (verbindlich)
**Synchron im Loader.** Server bereitet das View-Model einmal auf, UI rendert. KEIN client-seitiges Re-Compute.
```ts
// app/routes/kontakte.$id.tsx
export async function loader({ params, context }: LoaderArgs) {
const entity = await context.db.kontakt.findUniqueOrThrow({ where: { id: params.id! } });
return json<KontaktDetailVM>(toKontaktDetailVM(entity, context.user));
}
export default function KontaktRoute() {
const vm = useLoaderData<typeof loader>();
return <KontaktDetailPage vm={vm} actions={{ onEdit, onArchive }} />;
}
```
## Prisma-Schema & Migrationen (verbindlich — AD-21)
Das Schema ist ein **Ordner** (`prisma/schema/`, Prisma 7), nicht eine Datei. Bei parallelen Branches gilt:
- **Ein Modul = eine eigene `prisma/schema/<modul>.prisma`** (viele existieren: `appsEngine`, `email`, `workflows`, `notifications`, `permissions`, `marketingLeads` …). Neue Modelle **NIE** in `core.prisma`/`accounts.prisma` — das ist der geteilte Kern (Tenant/User/Audit/File/ApiKey/Credential). Den nur für Relationen zu `Tenant`/`User` berühren, Rück-Relationsfelder minimal halten.
- **Feature-Branch: `prisma db push`** (kein Migrations-File). Die **eine** Migration pro Phase wird beim Merge auf `main` erzeugt — Forward-only + Inverse-SQL als Kommentar (DoD 28). Verhindert divergierende Timestamp-Historie bei parallelen Branches.
- Vor Merge: `prisma validate` + `prisma migrate status` grün. URLs liegen in `prisma.config.ts` (`DIRECT_URL` Migrate, `DATABASE_URL`/PgBouncer Runtime).
- **Migration muss aus dem Nichts reproduzierbar sein** (`infra/LESSONS.md §9`): CI testet `prisma migrate deploy` gegen eine **leere** DB — nur inkrementell auf Prod angewandte Migrations können bei Staging/DR/neuem Dev-Setup in falscher Reihenfolge brechen (gleicher Datums-Prefix sortiert lexikografisch, nicht nach Dependency → P3018). Order-abhängige DDL/DML in `DO $$ … IF [NOT] EXISTS … $$`-Blöcke guarden. Eine bereits auf Prod angewandte Migration **nie** umbenennen, ohne `_prisma_migrations.migration_name` nachzuziehen.
## Row-Level-Security (RLS) — verbindlich, seit Staging-Cutover 14.07.2026 scharf
Seit `20260713190000_appwide_rls_cutover` erzwingt **Postgres selbst** die Mandanten-Trennung (264 Tabellen, `FORCE ROW LEVEL SECURITY`). Die App verbindet als `hivegrid_app` bzw. `hivegrid_worker` — **ohne** Superuser, **ohne** `BYPASSRLS`. Details: `docs/security/RLS-HARDENING-2026-07-13.md`.
**Die Falle, die dich sonst garantiert erwischt:** Lokal läuft `RLS_RUNTIME_MODE=off`. Dein Code kann also lokal einwandfrei laufen und auf Staging/Prod **null Zeilen** liefern — kein Fehler, kein Log, nur leere Ergebnisse (bereits einmal passiert: eine neue Route lieferte in Prod jedes Profilbild als 404). Verlass dich für RLS-Korrektheit **nie** auf einen grünen lokalen Lauf.
- **Ohne gebundenen Kontext liefert eine RLS-Tabelle KEINE Zeile.** Der Kontext (`app.user_id` / `app.tenant_id`) wird transaktionslokal gesetzt — siehe `packages/db/src/rls-context.server.ts`.
- **Gehe über die db-Layer-Helfer** (`app/utils/db/**`): die binden den Kontext selbst (z.B. `updateUserProfile` via `withUserRlsContext`). Rufst du in einer Route/Service **direkt** `db.<model>` auf, musst du ihn selbst binden: `runWithRlsContext({ userId, tenantId }, …)` bzw. `withTenantRLS(tenantId, …)`.
- **Cross-Tenant-Lesen gibt es nicht „mal eben".** Eine Route ohne Tenant-Bezug (host-weit) muss die Mitgliedschaft Tenant für Tenant nachweisen, statt eine GUC in einer offenen Transaktion umzuschalten. Vorbild: `apps/web/app/routes/avatars.$userId.tsx`.
- **Pre-Auth-Pfade** (Login, Registrierung, Magic-Link) laufen über SECURITY-DEFINER-Funktionen und binden den Kontext danach — nicht selbst nachbauen.
- **Neue Tabelle = neue Policy.** `pnpm run verify:tenant-policy-contract` schlägt sonst an. Der Vertrag wird generiert, nicht handgeschrieben.
- **Tests, die den DB-Client mocken, beweisen nichts über RLS.** Ein Mock, der auf jede Query antwortet, versteckt genau diesen Bruch. Bilde in solchen Tests die Policy nach (Sichtbarkeit abhängig vom gebundenen Kontext).
**Runtime-Env: verbotene Schlüssel.** Auf Runtime-Ressourcen (web/api/mcp/hocuspocus/worker) dürfen `DIRECT_URL`, `MIGRATE_ON_BOOT`, `SEED_ON_BOOT`, `SEED_*` und `MIGRATOR_*` **nicht** gesetzt sein — `assert-runtime-db-env` bricht den Deploy sonst ab. Migrationen laufen ausschließlich im Einmal-Container des Deploys. **Konsequenz für Feature-Flags:** Ein Laufzeit-Schalter darf **niemals** ein `SEED_`-Präfix tragen, auch wenn er thematisch nach Seed klingt — genau daran sind die Staging-Demo-Logins gestorben (siehe `docs/deployment.md`, `STAGING_DEMO_LOGIN_ENABLED`).
**Seeding** ist auf Runtime-Ressourcen abgeschaltet und unter erzwungenem RLS **nicht freigegeben**. Ein tenant-bewusster Operator-Seed-Workflow ist offener Nachzug.
## EU-Stack (nicht verhandelbar — Bauprinzip A.12)
- **KEIN** `@ai-sdk/anthropic`, `@ai-sdk/openai`, `openai`
- **KEIN** `remix-auth-google`
- **KEIN** Apple-/Google-/Microsoft-Login (Phase 1)
- **KEIN eigenes LLM/RAG/Whisper in v1/v2** (AD-26). HiveGrid wird stattdessen Remote-MCP-Server (`VR-MCP`/`VD-MCP`); externe KI-Clients bringen die Inferenz mit.
- **JA** Email+Passwort + Magic-Link + TOTP (M020, M021, M022)
- Hosting: Hetzner + Coolify (EU); Datenbank: in EU; Storage: Hetzner Object Storage / S3 (EU).
## Querschnitt-Hülle nutzen, nicht nachbauen
| Concern | Querschnitt-Vertrag | Service-Import |
|---|---|---|
| Audit-Log default | M001 | auto via Prisma-Middleware; manuell `auditEvent` |
| Klartext-Diagnostik | M002 | `errorCatalog`, `ErrorBoundary` |
| i18n | M003 | `t('<modul>.<bereich>.<key>')` |
| Tenant-Scope | M004 | `withTenantScope()`, `withPermission()` |
| Feature-Flag | M006 | `featureFlag('<key>', tenant)` |
| Idempotenz (BullMQ) | M007 | `withIdempotency()` |
| Apps-Engine-Adapter | M008-M010 | `defineAdapter()` |
| Notifications | M011 | `notify({...})` |
| View-Model-Layer | M013 | Type + Zod-Schema in `packages/view-models/src/<domain>/*.vm.ts` |
| Action-Callback-Contract | M014 | Standard-Shape `{ onX: (input) => Promise<...> | void }` |
| Subframe-Adapter | M015 | Adapter in `packages/ui-app/src/adapters/` |
| Visual-Regression | M016 | Playwright Component-Test mit Fixture-VM |
| Hot-Swap-Drill | M017 | `pnpm test:hot-swap` |
Wenn ein Modul Cross-Cutting-Concern selbst nachbaut → PR abgelehnt.
## Estate-Infrastruktur — verbindliche Regeln (Quelle: `infra/`)
HiveGrid ist **ein** Workload im ToolCtrl-Estate (neben mITapp + Marketing-Sites). **Quelle der Wahrheit ist
das Schwester-Repo `../infra/`:** `../infra/README.md` (Bestand), `../infra/STANDARDS.md` (Estate-Default),
`../infra/decisions/` (Ausnahmen/ADRs), `../infra/LESSONS.md` (Footguns). Eine akzeptierte Infra-ADR darf
einen allgemeinen Standard ausdrücklich brechen. Übersichts-Diagramm + Steckbriefe:
`local/infra-diagrams/06-estate-infrastructure.{mmd,md}`.
**Estate-Default:** geteilte Services nutzen, nie ungeplant pro Produkt nachbauen. HiveGrid bekommt den
Slug **`hivegrid`**. Die Tabelle gilt für Staging und alle nicht ausdrücklich ausgenommenen Runtimes.
**Produktions-Ausnahme (AD-24 / Infra-ADR 016):** HiveGrid-Prod läuft im eigenen Hetzner-Account mit
eigenem Coolify. Meilisearch, ClamAV und Captcha laufen dort innerhalb des Prod-Accounts; Prod darf dafür
nicht auf die Staging-/Estate-Mesh-Adressen `10.42.0.4:*` zeigen. Gitea Registry, Sentry und Cloudflare
bleiben bewusst geteilte Dienste über authentifiziertes öffentliches TLS.
| Concern | Zentral (mesh-only, wenn nicht anders genannt) | App-Env / Vertrag |
|---|---|---|
| Errors (STANDARDS §1) | Sentry `sentry.saas-ctrl.com` — 1 Team `hivegrid`, 1 Projekt je Codebase (`web`/`api`/`worker`) | `SENTRY_DSN_<APP>` · `SENTRY_ENVIRONMENT=staging\|production` · `SENTRY_RELEASE=$GIT_SHA`. Staging↔Prod = **Tag**, nicht eigenes Projekt. Browser-DSN als `VITE_SENTRY_*` **Build-Arg** (Coolify-Env ist nur Runtime). |
| FTS (STANDARDS §4, AD-5) | Staging: Meilisearch `10.42.0.4:7700`; Prod: dedizierte AD-24-Instanz | `MEILI_API_KEY=<hivegrid-scoped>`. Indizes **`hivegrid-*`**-prefixed, **nie** geteilt, **nie** Master-Key in der App. |
| Upload-AV (STANDARDS §13) | Staging: ClamAV `10.42.0.4:3310`; Prod: dedizierte AD-24-Instanz; immer **INSTREAM** | Failure-Policy: **fail-closed** für untrusted Uploads. Kein Path-Scan/shared FS; >100 MB vorab ablehnen. |
| NSFW-Bilder (STANDARDS §14) | nsfw-api `10.42.0.4:3000`, `POST /classify` raw bytes | `NSFW_URL=http://10.42.0.4:3000`. Failure-Policy: **fail-open** (Gegenteil von AV). |
| Logs (STANDARDS §2) | Loki `10.42.0.4:3100` via Promtail (per Host) | App loggt **strukturiertes JSON nach stdout/stderr**, keine Secrets (Loki-Labels sind global queryable). |
| Metrics (STANDARDS §2/§3) | Prometheus+Grafana auf `control` (`grafana.saas-ctrl.com`) | App-`/metrics` optional, aber **bearer-token-geschützt**. Pflicht-Labels `project/environment/server/service`. |
| Admin-SSO (STANDARDS §5, AD-3) | Authentik `auth.tool-ctrl.de` (OIDC) | Nur **Operator/Admin**-Logins über Authentik. SaaS-Endkunden bleiben in der eigenen User-Tabelle. |
> Mesh-only-Services (`10.42.0.4`) haben **keine** Auth — Sicherheit = WireGuard-Mesh-Bind + UFW. Erreichbar nur als Mesh-Peer; **nie** einen Public-Port dafür fordern.
**Deploy & Repo (STANDARDS §6–§9, ADR-002/005/010):**
- **Interaktive Gitea-Identität = persönlicher Dev-Account (verbindlich):** Jeder Clone deklariert
seinen erwarteten Gitea-Login lokal mit `git config --local hivegrid.giteaUser <login>`
(`raffael` auf Raffaels Maschine, `akeshan` auf Akeshans Maschine). Vor jedem Git-Push und vor jeder
schreibenden Gitea-API-Aktion (PR anlegen/schließen/mergen, Kommentar, Branch/Tag löschen, Release)
muss die effektiv verwendete Credential über `GET /api/v1/user` exakt diesen Login und
`active=true` liefern. Fehlende Deklaration, Lookup-Fehler oder Abweichung = **STOP**; keine
Admin-Impersonation als Ersatz. Der kanonische lokale API-PAT liegt in
`~/.cli-tokens/gitea-<login>` (Mode 600); `~/.cli-tokens/gitea` darf nur als Symlink auf den zum
deklarierten Login passenden Token existieren. HTTPS-Credentials bleiben pfadspezifisch
(`credential.useHttpPath=true`) und dürfen nie in Remote-URLs stehen. `gitea-admin` ist für normale
Entwickler-/Agent-Arbeit verboten und nur als ausdrücklich autorisierter, separat auditierter
Break-Glass-Zugang zulässig. **Ausnahme:** CI-/Deploy-/Registry-Automation nutzt weiterhin dedizierte
Servicekonten/Bot-PATs; persönliche Entwickler-Credentials gehören nie in Gitea-Secrets oder Runner.
- **Merge-Strategie = normaler Merge-Commit, niemals Squash (verbindlich):** PRs werden nach vollständig
grüner CI mit der normalen Merge-Strategie übernommen. Die einzelnen Branch-Commits müssen mit ihren
ursprünglichen SHAs Vorfahren von `main` bleiben; Gitea-API-Merges verwenden `Do=merge`, nie
`Do=squash`. Vor dem Merge wird die erwartete Head-SHA geprüft, danach mit
`git merge-base --is-ancestor <feature-head> origin/main` verifiziert, dass die Branch-Historie erhalten
ist. Ein versehentlicher Squash wird nicht durch Umschreiben oder Force-Pushen des geteilten `main`
repariert, sondern append-only durch einen bytegleichen History-Repair-PR, der den ursprünglichen
Feature-Head per normalem Merge-Commit anbindet.
- **Coolify** ist das Deploy-Target (kein K8s/Terraform). Hierarchie: **Projekt = Produkt** (`HiveGrid`, TitleCase) · **Environment = Phase** (`production`/`staging`, lowercase) · **Resource = Service** (`hivegrid-web`/`-api`/`-worker`, kebab-case). Staging läuft über das zentrale Estate-Coolify; HiveGrid-Prod über das eigene AD-24-Coolify.
- **Build-once / deploy-via-pull:** CI (Gitea-Runner `toolctrl-ci`) baut **ein** Image, pusht in die **Gitea Package Registry** (`git.hg-int.dev/toolctrl-labs/<image>:<sha>` immutable + Alias-Tags); Coolify **pullt** nur — **kein** Build in Coolify. Rollback = altes `:<sha>` neu deployen.
- **CI triggert Coolify mit `POST /api/v1/deploy?uuid=…&force=true`** — NICHT `/restart` (das reuset das gecachte Image und shipped still alten Code, `infra/LESSONS.md §10`).
- Repo unter `toolctrl-labs/<name>` in **Gitea**, **private by default**, mit `Dockerfile` + `.gitea/workflows/`. Clone von Cloud-Hosts via **HTTPS+PAT** (Gitea-SSH:2222 ist von Hetzner unerreichbar, ADR-003).
- **DNS in Cloudflare** (SSL-Mode strict): A-Record `proxied=false` bis das LE-Cert steht, danach `true`. Mail: **OUT = Mailjet**, **IN = mailbox.org**.
**Secrets & Backups (STANDARDS §9/§10):**
- Secrets **nie** ins Repo / in Chat / in CI-Logs. Per-User-Tokens in `~/.cli-tokens/` (chmod 600); geteilte Dev-`.env` verschlüsselt via SOPS+age (`secrets/dev.sops.env`, `pnpm env:pull`).
- Ein **stateful** Service (Postgres/Redis-Persistenz/Index) darf **nicht** Prod-Traffic bekommen, bevor das Backup in `infra/runbooks/` dokumentiert ist (wohin, wie oft, Restore, letztes Restore-Drill-Datum).
Konkret tun (Host hinzufügen, Recovery, Secret-Rotation, neue Marketing-Site) → `infra/runbooks/*.md`.
## Subframe-Workflow
1. Designer baut Screen in Subframe
2. User pulled Subframe-Code → landet in `packages/ui-subframe/src/**`
3. AI-Coding-Agent integriert via Adapter-Layer in `packages/ui-app/src/adapters/**`
4. Routes importieren nur `packages/ui-app`, nie `ui-subframe` direkt
5. Visual-Regression-CI (M016) prüft auf unbeabsichtigte Diffs
6. Hot-Swap-Drill (M017) bestätigt: Tausch gegen `ui-mock` bricht nichts
## Produktgrenzen / Anti-Liste — Bauprinzip A.9
Was nicht in der aktuellen Ticket-Doc beauftragt ist, wird nicht gebaut. Zusätzlich bleiben folgende
repo-weite Grenzen ohne genehmigten Change-Request ausdrücklich außerhalb des Produkts:
- keine Marketing-Webseiten-, CMS-, Blog- oder MySite-Engine in HiveGrid,
- kein vollständiges Buchhaltungs-/ERP-Ersatzprodukt; der einfache Projekt-Rechnungsdatensatz und
ausdrücklich beauftragte Adapter sind die Grenze,
- kein Apple-/Google-/Microsoft-Login; Provider-OAuth für freigegebene Fachintegrationen ist davon getrennt,
- keine native App, kein Expo/Capacitor und keine App-Store-Distribution in v1/v2,
- kein eigenes LLM, RAG, Whisper, HiveMind oder autonom handelnder KI-Agent in v1/v2,
- keine frei ausführbaren Custom-JS-Ausdrücke in Automationen,
- keine GraphQL-Surface und keine zusätzlichen ERP-, Social-, Marketplace- oder Provider-Integrationen
ohne eigenes Ticket und Produktfreigabe,
- kein KWP-Writeback vor `VEXT-6` und erneuter ausdrücklicher Freigabe (AD-32).
Eine Erweiterung läuft über `docs/CHANGE-REQUESTS.md`. Die dort genehmigte Änderung muss anschließend
in `AGENTS.md`, Requirements und den betroffenen Ticket-Docs nachgezogen werden.
## Ticket-Treue, Verbesserungs-Vorschläge & Fortschritt (verbindlich)
**1. Strikt am Ticket bauen — nichts erfinden.** Gebaut wird **ausschließlich**, was in der Ticket-Doc
`.planning/ticket-docs/<ID>.md` (Was / Screens / **DoD** / Technische-Bausteine) steht und mit den
repo-weiten Verträgen aus `AGENTS.md`, Entity Model und Requirements vereinbar ist. Verboten sind:
erfundene Tasks, „während ich hier bin"-Scope, ungefragte Refactors und **vorgezogene
Arbeit aus Folge-Tickets/-Phasen** (z.B. flächiger Roll-out, wo das Ticket nur den Nachweis verlangt). Ist die
Ticket-Doc lückenhaft, mehrdeutig oder widersprüchlich → **Stop + Rückfrage** (siehe §„Bei Unklarheit"), kein
Auto-Ausbau. Alles, was über das Ticket hinausginge, läuft über den Change-Request-Workflow
(`docs/CHANGE-REQUESTS.md`, M176). Maßstab ist die **DoD der Ticket-Doc** — nicht das, was technisch „auch noch
ginge".
**2. Verbesserungen sind willkommen — aber IMMER explizit ausgewiesen, nie still gebaut.** Du **darfst** (am
Ende und gerne auch mittendrin) vorschlagen, was man besser/sicherer/sauberer machen könnte. Solche Hinweise
**müssen klar als Vorschlag außerhalb des Ticket-Scopes markiert** sein — Format: eine Zeile/Block mit Präfix
**„💡 Vorschlag (außerhalb Ticket-Scope): …"** + kurzer Begründung (Nutzen/Aufwand/Risiko). Erst nach
**explizitem OK** des Users wird daraus Arbeit (i.d.R. neues Ticket / CR). **Niemals** einen Vorschlag direkt in
Code/Commit ziehen, nur weil er sinnvoll wirkt — das ist ein PR-Block wie ein Anti-Listen-Verstoß.
**3. Fortschritt in % ausweisen — bis das Ticket auf 100 % steht.** Bei **jeder** Status- oder Abschluss-Meldung
zu einem Ticket den Stand als **% done** angeben, abgeleitet aus den DoD-Punkten der Ticket-Doc:
`% = abgehakte DoD-Punkte / DoD-Punkte gesamt`. Format z.B.: **„R-P2a: 6/7 DoD = ~86 % done — offen: <Punkt>"**.
DoD-Punkte, die **extern blockiert** sind (David-Screens, Partner-Input, Folge-Phase), als **`blockiert`**
kennzeichnen und vom **selbst machbaren** Rest trennen (z.B. „86 % done · 1 Punkt offen, davon 1 blockiert →
0 selbst machbar"). Den %-Stand zusätzlich in die **Umsetzungs-Notiz der Ticket-Doc** schreiben. Erst bei
**100 % (alle DoD grün, nichts mehr selbst machbar offen)** ist das Ticket abschlussreif → §„Ticket abschließen".
## Klartext-Diagnostik — Bauprinzip A.1
- Kein `throw new Error("401 Unauthorized")` — stattdessen Catalog-Fehler aus M002
- Kein hartkodierter UI-Text — stattdessen i18n-Key aus M003
- Jede Fehler-Meldung beschreibt: was passiert ist, was zu tun ist, welcher Knopf hilft
## Kommentar-Sprache (Code = Englisch, Dokus = Deutsch)
**Code-Kommentare werden auf Englisch geschrieben** — passe dich der umgebenden Datei an, und
der Code-Bestand ist praktisch durchgaengig englisch kommentiert (Messung 2026-06-19: nur ~1% der
Quelldateien mit Kommentaren enthalten Deutsch, meist Alt-Bestand). Das gilt fuer `*.ts`/`*.tsx`,
`*.prisma` sowie SQL/Migrations in `prisma/**`. Grund: der ausführbare Code bleibt
tool- und teamübergreifend konsistent; Projektkontext und Umsetzungsnotizen bleiben deutsch.
**Deutsch bleibt nur in den Projekt-Dokus:** `.planning/**` (inkl. `ticket-docs/`),
`docs/**`, `local/**`-Planungsartefakte sowie die Umsetzungs-Notizen und
Plane-Kommentare. Diese sind bewusst deutsch und bleiben deutsch.
Faustregel: liegt die Datei im ausfuehrbaren Code (`apps/**`, `packages/**`, `prisma/**`) →
Kommentare Englisch. Liegt sie in einem Doku-/Planungs-Ordner → Sprache der Doku (meist Deutsch).
## RR7-Spezifika
- **`.server.ts`-Re-Export ist verboten** (User-Memory). Nutze stattdessen Component-Extraktion.
- Loader/Action sind die einzigen Pfade in `app/domain/**`. Keine Direkt-DB-Calls aus Components.
## Mid-Stream-Korrektur
Bei falschem Code: siehe `docs/MID-STREAM-CHANGES.md` für Eskalations-Stufen und Rollback-Pfad.
## Bei Unklarheit
Stop, Frage an User, kein Auto-Refactor. Dokumentiere offene Frage in der PR-Beschreibung.