Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -1,101 +1,42 @@
# Mid-Stream-Änderungen — Rollback-Playbook
**Zweck:** Wenn ein AI-Coding-Agent ein Milestone falsch baut und du es mittendrin korrigieren musst, ohne dass 5 andere Module brechen.
**Zweck:** Ein laufendes Ticket sicher korrigieren, ohne abhängige Tickets oder bereits ausgelieferte Daten zu beschädigen.
## Grundsatz: atomare Commits pro Slice
## Grundsatz
Der HiveGrid committet pro Slice atomar. Eine Slice rückgängig zu machen heißt: einen Commit-Range zu reverten — nicht einen einzelnen File.
- Plane hält Status und Dependencies; die Ticket-Doc hält Scope, DoD, Rollback und Proof.
- Änderungen werden an atomaren Checkpoints committed. Ein Rollback erfolgt mit `git revert`, nicht durch Umschreiben veröffentlichter Historie.
- Vor Contract-, Schema- oder Scope-Änderungen werden `blocked-by` und `blocks` in beide Richtungen geprüft.
## Eskalations-Stufen
## Eingriffsstufen
### Stufe 1: Kosmetik / UI falsch
### 1. UI/Wording
**Anzeichen:** Funktion läuft technisch, aber Layout/Wording/Reihenfolge falsch.
Interim-UI beziehungsweise Subframe-Adapter korrigieren, Visual-Baseline nachziehen und die stabile VM-/Action-Grenze beibehalten. Keine fachliche Logik in Routes oder UI verschieben.
**Vorgehen:**
1. NIEMALS direkt im `app/routes/**` korrigieren — Designer baut neu in Subframe
2. Subframe-Update → AI-Agent integriert in `packages/ui-hivegrid/src/adapters/`
3. Visual-Regression-Gate (M016) zeigt Diff
4. Merge
### 2. View-Model oder Domain-Logik
**Risiko:** sehr niedrig. Layer-Trennung schützt.
Pure VM-Builder, Zod-Schema und fokussierte Tests gemeinsam ändern. Bei Schreiblogik zusätzlich Audit, Activity, Notifications, Permission- und RLS-Kontext prüfen.
### Stufe 2: View-Model falsch (Daten-Form)
### 3. Datenmodell oder öffentlicher Contract
**Anzeichen:** Funktion zeigt falsche Daten / fehlende Felder / falsche Aggregation.
- Neue Forward-only-Migration; angewandte Migrationen nicht umbenennen oder editieren.
- Inverse-SQL als Kommentar dokumentieren.
- Alle abhängigen Ticket-Docs und Konsumenten im selben Änderungsschnitt nachziehen.
- Prisma-Validierung, Migrations-Parität, RLS-Verträge und fokussierte Consumer-Tests ausführen.
**Vorgehen:**
1. View-Model in `packages/view-models/src/<domain>/*.vm.ts` korrigieren
2. Zod-Schema mit-aktualisieren
3. Loader-Funktion im `app/routes/**` korrigieren
4. UI-Component in `packages/ui-hivegrid/**` muss NICHT geändert werden (sonst war die Trennung schlecht)
### 4. Ticket-Ansatz verwerfen
**Risiko:** mittel. Wenn die UI-Component die VM-Form falsch annimmt: neuer Vertrag.
Noch nicht gemergte Checkpoints gezielt reverten oder den Branch verwerfen. Bereits gemergte Änderungen ausschließlich über neue Revert-/Fix-Commits korrigieren. Ticket-Doc mit Ursache, Auswirkungen, neuem Plan und aktuellem DoD-Prozentsatz aktualisieren.
### Stufe 3: Domain-Logik falsch
## Notbremse
**Anzeichen:** Daten werden falsch geschrieben, Permissions stimmen nicht, falsche Side-Effects.
Wenn ein ausgeliefertes Modul einen vorhandenen Feature- oder Ingress-Schalter besitzt, ihn kontrolliert deaktivieren und die operative Auswirkung dokumentieren. Kein neuer Schalter außerhalb des Ticket-Scopes und kein Deploy-Bypass.
**Vorgehen:**
1. `app/domain/**` korrigieren (NICHT UI, NICHT VM)
2. Bei DB-Schema-Änderung: neue Prisma-Migration als FORWARD-MIGRATION (kein Backward-Edit der alten)
3. Bei Permission-Bug: Permission-Wrapper-Test in M004 erweitern
4. Cross-Tenant-Probe-Test (M005) muss grün bleiben
## Pflichtnachweise vor Push
**Risiko:** hoch. Daten könnten bereits in der DB falsch sein.
### Stufe 4: Komplettes Milestone neu
**Anzeichen:** Architektur-Fehler, falscher Layer-Schnitt, Anti-Pattern in der Foundation.
**Vorgehen:**
1. Branch identifizieren — TC arbeitet pro Milestone in einem Branch
2. Branch nicht mergen → revert ist trivial
3. Wenn schon gemergt: `git revert <merge-commit>` als neuer Commit
4. PLAN.md des Milestones aktualisieren (Lessons Learned als Hinweis für Slice-Planung)
5. TC neu starten auf das Milestone
**Risiko:** sehr hoch wenn andere Milestones bereits darauf bauen. Deshalb: vor jedem Milestone PLAN.md prüfen, ob die Abhängigkeiten klar sind.
## Reversibilitäts-Pflichten pro Milestone
Bevor TC ein Milestone als fertig markiert, müssen folgende Rollback-Pfade existieren:
| Artefakt | Rollback-Pfad |
|---|---|
| **Code-Änderungen** | `git revert <slice-commit>` — atomic per Slice |
| **DB-Migration** | Forward-Only-Migration mit dokumentiertem Inverse-SQL als Kommentar im Migration-File |
| **Sidebar-Eintrag** | Eintrag in `sidebar.config.ts` löschen → Sidebar baut sich neu |
| **Routes** | Route-Datei löschen → RR7 verweigert die URL |
| **Permissions** | Permission-Key in `permissions.ts` als deprecated markieren |
| **Feature-Flag** | Flag aus auf `false` → Modul unsichtbar ohne Code-Deploy |
## Notbremse: Feature-Flag
Jedes Modul, das in Produktion landet, kann via Feature-Flag aus M006 ausgeschaltet werden — ohne Deploy. Wenn etwas live brennt:
1. Plattform-Admin → Feature-Flags
2. Flag des betroffenen Moduls auf `false` für betroffenen Mandanten
3. Modul verschwindet aus der Sidebar (siehe sidebar.config.ts `feature_flag` Feld)
4. Bug in Ruhe fixen
5. Flag wieder auf `true`
## Was du als Mensch nicht selbst korrigieren solltest
- **NICHT direkt in `packages/ui-subframe/**`** — das ist Subframe-Output, wird beim nächsten Designer-Update überschrieben
- **NICHT direkt in `packages/ui-hivegrid/src/adapters/**`** — der AI-Agent generiert das aus dem Subframe-Output
- **NICHT in TC-State (`.tc/`)** ohne Backup
## Was du selbst korrigieren KANNST
- `docs/milestones/M*/PLAN.md` — Pflichtenheft-Bezug, Hinweise, Erfolgskriterien anpassen
- `AGENTS.md` und `docs/INTEGRATION-CONTRACTS.md` — Agent-Regeln verschärfen
- `docs/CHANGE-REQUESTS.md` — Change-Request festhalten
## Eskalationspfad
1. Feature-Flag aus (Notbremse)
2. PLAN.md aktualisieren mit klarer Korrektur-Anweisung
3. TC auf das Milestone neu starten oder gezielt eine Slice via `/tc steer` umsteuern
4. Verify-Gates laufen lassen, bis grün
5. Flag wieder an
1. Betroffene Ticket-DoD und Dependencies konsistent.
2. Passende fokussierte Tests und `verify:*`-Gates grün.
3. `pnpm typecheck`, `pnpm lint` und `pnpm test` gemäß `docs/AGENT-CHECKLIST.md` grün.
4. Rollback-Pfad und Forward-only-DB-Vertrag in der Ticket-Doc dokumentiert.
5. Plane-Kommentar und Status erst nach dem lokalen Proof aktualisieren.