Ein TYPO3-Upgrade ist keine gerade Linie. In realen Projekten kann ein Composer-Konflikt die
Zielversion blockieren, ein Consent-Dialog die Screenshot-Messung verfälschen, ein Solr-Update die
Reihenfolge von Suchergebnissen verändern oder ein Datenimport plötzlich mit dem falschen
fileadmin arbeiten.
Genau deshalb haben wir unseren typo3-upgrade-run Skill umgebaut: aus einer großen Schleife wurde
ein evidenzbasierter Zustandsgraph.
Mit „Graph“ meinen wir ein Netz aus Zuständen und gerichteten Übergängen. Ein „Grid“ wäre ein visuelles Raster. Für die Upgrade-Logik ist der Graph der richtige Begriff.
Was war am Loop gut – und wo wurde er zu teuer?
Das bisherige Modell war leicht zu verstehen:
planen → ausführen → prüfen → Fehler beheben → wieder prüfen
Für kleine, lineare Änderungen funktioniert das gut. Der Loop erzwingt Disziplin und verhindert, dass nach einem fehlgeschlagenen Test einfach weitergearbeitet wird. Bei großen TYPO3-Upgrades hat er jedoch zu viele unterschiedliche Aufgaben in denselben Kreislauf gezogen.
Wir haben sechs begonnene oder abgeschlossene Projekt-Upgrades ausgewertet. Wiederkehrende Muster waren unter anderem:
- Ein beschädigter Sitemap-Pfad führte zu erneuter Baseline-Arbeit, obwohl das Problem zur URL-Erkennung gehörte.
- Zufällige Logos, animierte GIFs und Slider-Timing erzeugten falsche Pixel-Funde. Mehr Screenshots lösten nicht die Ursache – die Messung musste stabilisiert werden.
- Ein lokaler Sync enthielt ein Credential-Problem; ein späterer Import leerte das frisch
synchronisierte
fileadmin. Das war kein Frontend-Fehler, sondern ein Identitäts-, Backup- und Recovery-Problem. - Solr lieferte dieselben Treffer in anderer Reihenfolge. Status 200 und ein grüner Screenshot reichten nicht; die Suchreihenfolge brauchte einen eigenen Verhaltens-Test.
- Ein Upgrade war in Git dokumentiert, hatte aber keine vollständige Run-Evidenz. „TYPO3 14 ist installiert“ und „Contract A ist bewiesen“ sind zwei verschiedene Aussagen.
- Vollständige Screenshot-Läufe mit hunderten URLs wurden mehrfach wiederholt, obwohl die Ursache bereits auf eine einzelne CSS-, Asset- oder Harness-Klasse eingegrenzt war.
Der Loop wusste nur: grün oder nicht grün. Er wusste zu wenig darüber, warum etwas rot war und welcher nächste Schritt daraus folgt.
Der Nachfolger: ein Zustandsgraph
Im neuen Modell besitzt jeder Knoten eine kleine, überprüfbare Aufgabe. Eine Kante verbindet nicht einfach „Fehler“ mit „noch einmal“, sondern ein konkretes Ergebnis mit dem passenden nächsten Knoten.
Vereinfachter TYPO3-Upgrade-Graph: Ursachen verzweigen in eigene Recovery-Pfade
Ein Knoten ist eine kleine Vereinbarung
Jeder Knoten definiert:
- genau ein Ziel und einen zuständigen Skill,
- Voraussetzungen und erlaubte Ergebnisse,
- ob Code oder Daten verändert werden,
- den passenden Git-Anker oder DDEV-Snapshot,
- benötigte Ressourcen,
- einen überprüfbaren Evidence-Verweis.
Ein Knoten darf nicht mit „wurde geprüft“ abgeschlossen werden. Er braucht ein Artefakt: einen Report, Hash, Exit-Code, Screenshot-Vergleich, Manifest oder eine dokumentierte Entscheidung.
Kanten erhalten die Ursache
Ein visueller Unterschied ist nicht automatisch eine CSS-Aufgabe. Der Graph unterscheidet:
| Feature | Beobachtung | Nächster Pfad |
|---|---|---|
| Composer löst TYPO3 14.3 nicht auf | Dependency Resolution statt Screenshot-Retry | |
| Unveränderte Doppelaufnahme unterscheidet sich | Determinism/Harness Recovery statt Site-Fix | |
| HTTP und DOM unterscheiden sich | Routing/Markup/Content Recovery | |
| Nur Pixel unterscheiden sich | CSS, Assets, Fonts, Bilder, Session oder Harness klassifizieren | |
| Consent oder Slider ist kaputt | Interaction Recovery mit repräsentativer User Journey | |
| Projekt, Daten oder Backup sind unklar | Stoppen – keine Mutation |
Damit bleibt die Ursache erhalten. Ein kaputtes Messwerkzeug kann nicht mehr durch CSS-Änderungen „repariert“ werden, und ein Credential-Problem verschwindet nicht in einer allgemeinen Fehlermeldung.
Fünf kleine Skills statt eines Monolithen
Der Orchestrator wurde bewusst verkleinert. Er hält Verträge, Graph, Freigaben, Security-Grenzen und den finalen Status. Die Arbeit übernehmen kleinere Skills:
Upgrade Intake
Prüft Repository, DDEV, Core, Datenbank, fileadmin, Sites, Sitemaps, Extensions, Credentials und Backup-Bereitschaft – ohne Mutation.
Upgrade Baseline
Baut die deterministische Vorher-Evidenz: URLs, HTTP, DOM, Pixel sowie Consent-, Slider-, Such- und Formular-Journeys.
Upgrade Migration
Führt genau einen autorisierten Dependency-, Code-, Schema- oder Daten-Schritt mit Rollback und Fixed-Point-Beweis aus.
Upgrade Closure
Vergleicht Quelle und Ziel, prüft Backend, Redirects/Rechte, Runtime, Lighthouse und axe und erstellt das Abschlusszertifikat.
Upgrade Retrospective
Analysiert vergangene Runs und Tasks und übersetzt echte Probleme in neue Graph-Kanten, Guards, Tests und Evals.
Spezialisierte TYPO3-Skills
Vite, Solr, Content Blocks, Backend-Rechte, Visual Editor, Rector, Fractor und Security behalten ihre klare Fachzuständigkeit.
Die Trennung macht die Aufgaben kleiner, die Trigger präziser und die Ergebnisse leichter prüfbar. Sie verhindert außerdem, dass ein Detail-Skill den gesamten Upgrade-Prozess oder seine eigenen Wiederholungsschleifen erfindet.
Sicher parallel – mit Ressourcen-Locks
Ein Graph kann mehrere Knoten gleichzeitig bereitstellen. Das bedeutet nicht, dass alles parallel laufen darf.
Read-only Inventuren ohne gemeinsame Ressourcen können gleichzeitig arbeiten. Dagegen werden folgende Ressourcen exklusiv gesperrt:
- Composer: nur ein Prozess verändert Abhängigkeiten und Lockfile.
- DDEV stateful: nur ein Knoten verändert Datenbank, Schema oder
fileadmin. - Browser proof: die autoritative Render-Umgebung bleibt reproduzierbar.
- Solr core: kein paralleles Clear, Configset-Update oder Reindex.
- Backend session: Rechte- und Schreibtests bleiben einem definierten Benutzerkontext zugeordnet.
So entsteht reale Beschleunigung ohne konkurrierende Datenänderungen oder Beweise, deren Inputs sich während der Messung bewegen.
Was ändert sich beim visuellen Regressionstest?
„Mehr Screenshots“ ist nicht automatisch „mehr Sicherheit“. Der neue Ansatz arbeitet in drei Ebenen:
- HTTP und normalisiertes DOM vollständig: jede entdeckte Route wird geprüft.
- Pixel tiered: Golden Paths, Sprachen, Sonderseiten, Template-Repräsentanten und auffällige URLs zuerst; der Rest wird deterministisch gesampelt.
- Komponenten als Journeys: Consent, Slider, Suche, Formulare, Navigation, Modals und Medien werden auf repräsentativen Seiten wirklich bedient.
Für normale Seitenvergleiche wird ein akzeptierter Consent-Zustand gesetzt. Separat öffnet ein frischer Browser-Kontext den ersten Besuch, die Einstellungen, Ablehnen und Akzeptieren; Tracker werden lokal abgefangen. Ein Slider wird nicht nur auf Slide 1 eingefroren: Bilder und Fonts werden abgewartet, danach werden Weiter, Zurück und Tastaturbedienung geprüft.
Während der Fehlerbehebung werden nur betroffene URLs plus deterministische Sentinels neu erfasst. Der vollständige Beweis läuft an den wenigen festgelegten Grenzen. Das spart Zeit, ohne die Abdeckung kleinzureden.
Security ist ein Pfad, kein Absatz im Abschlussbericht
Die wichtigste Konsequenz aus den realen Runs: Security- und Identitätsprobleme müssen den Prozess mechanisch stoppen.
Vor jeder Mutation werden Projekt, DDEV, Datenbank, Branch, HEAD, Backup und exakter Scope erneut geprüft. Ein Backup braucht Artefakt, Datum, Prüfsumme, Ziel und Restore-Kommando. Eine Freigabe für vier Datei-UIDs gilt nicht plötzlich für sechs – und eine lokale Freigabe gilt niemals für live.
Auch das TYPO3 Redirects-Modul ist jetzt Teil des Graphen. Fehlt typo3/cms-redirects, wird es über
die Dependency Resolution passend zum gesperrten TYPO3-14.3-Core installiert. Danach prüft ein
eigener Rechte-Knoten mit einem Nicht-Admin-Testuser: Modul sichtbar, erlaubtes Erstellen/Bearbeiten
möglich, fremde Sites und Aktionen verboten, Frontend-Redirect korrekt.
Was ist besser?
- Gezieltere Recovery: Ein Fehler springt zum passenden Reparaturpfad.
- Weniger Wiederholung: Nur der betroffene Beweis wird nach einer Korrektur wiederholt.
- Sichere Parallelität: unabhängige Analysen können gleichzeitig laufen.
- Bessere Wiederaufnahme: State, Graph-Hash, Node-History und Locks liegen auf Disk.
- Mehr Security: Identität, Backup, Credential-Ursprung und destructive scope sind Gates.
- Ehrlichere Ergebnisse: Git-Commit, installierte Version und bewiesene Invarianz bleiben getrennte Aussagen.
- Professionellere Skills: kleine Aufgaben, klare Owner, präzise Trigger und eigene Evals.
Was ist schlechter oder aufwendiger?
Ein Graph ist kein kostenloses Upgrade.
- Mehr Zustandsmodell: Nodes, Edges, Outcomes, Locks und Hashes müssen konsistent bleiben.
- Graph-Pflege: neue Projektformen brauchen neue Bedingungen oder Recovery-Pfade.
- Branch-Explosion: zu feine Ursachen können den Graph unnötig groß machen.
- Lock-Konflikte: falsche Ressourcen-Zuordnung serialisiert zu viel; zu lockere Zuordnung ist gefährlich.
- Debugging wird zweistufig: Neben dem TYPO3-Projekt kann auch der Graph/Harness fehlerhaft sein.
- Overhead bei kleinen Sites: Für einen simplen Patch wäre der vollständige Upgrade-Graph zu schwer. Deshalb triggern die Leaf-Skills und der Orchestrator nur für den passenden Umfang.
Diese Nachteile sind real. Wir akzeptieren sie dort, wo ein stundenlanger, datenverändernder TYPO3-LTS-Sprung eine nachweisbare Prozesssicherheit braucht. Für kleine Einzelaufgaben bleiben kleinere Fach-Skills die bessere Wahl.
Wann ist der Upgrade-Skill fertig?
Nicht nach composer update. Nicht nach einer grünen Homepage. Und nicht nach einem Commit mit dem
Text „Upgrade complete“.
Der lokale Run ist abgeschlossen, wenn Projekt und Daten identifiziert sind, die immutable Baseline verifiziert ist, alle anwendbaren Migrations- und Spezialknoten Evidence besitzen, der Ziel- Datenzustand nachvollziehbar ist, HTTP/DOM/Pixel und Komponenten grün oder ausdrücklich akzeptiert sind, Backend/Redirects/Rechte/Runtime funktionieren und Graph sowie Run-Verzeichnis valide sind.
Erst dann entsteht das lokale Handover. Deployment auf Staging oder live bleibt bewusst ein eigener Prozess mit eigener Zielprüfung und Freigabe.
Nicht die maximale Zahl autonomer Wiederholungen macht ein Upgrade professionell. Entscheidend ist, dass jeder Fehler seine Ursache behält, jeder riskante Schritt eine Grenze hat und jede Aussage auf prüfbarer Evidenz beruht.
Der typo3-upgrade-run Skill ist Teil unserer offenen
TYPO3 Agent Skills auf GitHub. Die kleineren Upgrade-Skills veröffentlichen wir dort Schritt für Schritt.