HiveGrid-Wireframes/hivegrid-cloud/docs/MID-STREAM-CHANGES.md

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.

Grundsatz: atomare Commits pro Slice

Der ToolController committet pro Slice atomar. Eine Slice rückgängig zu machen heißt: einen Commit-Range zu reverten — nicht einen einzelnen File.

Eskalations-Stufen

Stufe 1: Kosmetik / UI falsch

Anzeichen: Funktion läuft technisch, aber Layout/Wording/Reihenfolge falsch.

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

Risiko: sehr niedrig. Layer-Trennung schützt.

Stufe 2: View-Model falsch (Daten-Form)

Anzeichen: Funktion zeigt falsche Daten / fehlende Felder / falsche Aggregation.

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)

Risiko: mittel. Wenn die UI-Component die VM-Form falsch annimmt: neuer Vertrag.

Stufe 3: Domain-Logik falsch

Anzeichen: Daten werden falsch geschrieben, Permissions stimmen nicht, falsche Side-Effects.

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

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