Skip to main content

jhf-shuttle Gesamtprojektplan

Documentation Map​

jhf-shuttle Gesamtprojektplan

Zweck​

Dieses Dokument ist der Masterplan fuer die weitere Entwicklung von jhf-shuttle bis zu einem fertigen, belastbaren Produktzustand.

Es beschreibt:

  • das Zielbild
  • die bereits erreichten Phasen
  • den aktuellen Stand je Phase
  • die noch offenen Phasen und Restarbeiten
  • die geplanten Sprints
  • die Abnahmekriterien bis "fertig"

Zielbild​

jhf-shuttle soll drei Dinge gleichzeitig gut koennen:

  1. Core Skill Workflow-Suche, Workflow-Bau, Validierung, Debugging, Live-n8n-Operations

  2. Operator Layer OpenClaw-/On-Prem-Operations, Mailbox, Policy, Recovery, Evidence-first Work

  3. Upgrade And Compatibility Platform offizielles n8n-Upstream-Verstaendnis, Instanz-Lernen, Upgrade-Impact, Mission-Control-Signale

Das Endprodukt ist damit nicht nur ein Skill, sondern eine laufende Operator-Plattform fuer:

  • n8n-Kompatibilitaet
  • Upgrade-Sicherheit
  • Workflow-Risikoanalyse
  • Mission-Control-Integration
  • belastbare operatorische Entscheidungsunterstuetzung

Statusuebersicht​

Bereits umgesetzt​

  • Core Skill Mode und On-Prem Messaging Mode sind sauber getrennt dokumentiert
  • Mission-Control-Vertrag ist implementiert
  • optionaler API-Server ist implementiert
  • WorkflowContext, Event Bus, OpenAPI und Schema sind vorhanden
  • Upstream Sync, Version Gap, Catalog Freshness und Learning Overlay sind implementiert
  • Upgrade-Impact, Upgrade-Readiness, Upgrade-Backlog, Upgrade-Batches und Upgrade-Alerts sind implementiert
  • Live-Verifikation gegen n8n-production ist erfolgt
  • GitHub/Gitea/README/Dokumentation sind nachgezogen

Aktueller Gesamtstand​

  • Produktphase: spaete Härtungsphase / finaler Residual-Risk- und Signoff-Modus
  • Mission Control Contract: stabil, live verifiziert und mit dedizierten Upgrade-Read-Surfaces ausgebaut
  • Upgrade Intelligence: breit implementiert, live verifiziert und ueber Backlog/Batches/Alerts/Summaries operationalisiert
  • On-Prem Operator Stack: funktional; verbleibende Risiken sind derzeit vor allem umgebungs- und laufzeitabhaengig
  • Dokumentierte Queue: Sprint 07 bis Sprint 25, Stabilization 01 bis 04 und Post-RC-Hardening sind abgearbeitet; die kleine Sprint-26-Folge-Queue fuer Live-Audit-Must-Fixes ist ebenfalls abgeschlossen und in den Signoff-/Follow-up-Dokumenten verankert
  • Zuletzt abgeschlossene kleine Queue: Sprint 27 hat die explizit priorisierten Restschulden aus dem Post-Audit-Stand in einem bounded Folgezyklus reduziert: Baseline-Coverage, Flow-Control-Tuning, blocked-dispatch-Produktsemantik, optionale API-Runtime und vertiefte Upgrade-Regel-/Katalogpflege
  • Noch nicht fertig: verbleibende Restpunkte sind jetzt bewusst sichtbar und liegen vor allem in:
    • verbleibender Baseline-Katalog-Coverage-Schuld jenseits des kleinen committed Supplements
    • weiterem Flow-control-Threshold-Tuning ueber die jetzt sichtbare Advisory-Stufe hinaus
    • tieferer blocked-dispatch-/policy-Semantik ueber die ganze Produktflaeche
    • optionaler API-Runtime im jeweiligen Zielumfeld
    • langfristiger Regel-/Katalogpflege

Aktuelle kleine Folge-Queue​

Sprint 27 war die naechste und bewusst begrenzte Schicht als direkte Restschuld-Queue nach dem abgeschlossenen Sprint-26-Audit-Follow-up. Mit dem Closure-Sync ist diese Queue jetzt beendet; weitere Arbeit in diesem Themenfeld braucht wieder eine explizit freigegebene Folge-Queue.

Sprint 26 - Live Audit Contract And Runtime Fixes​

Ziel

  • die wichtigsten operatorischen Fehlwahrheiten, negativen Contracts und verifikationskritischen Drift-Punkte aus dem Live-Audit beheben

Issues

  • Mission Control status/version-gap truth alignment
  • verify-agent-dispatch runtime discovery
  • mailbox malformed-JSON contract hardening
  • explicit validation for upgrade/workflow-not-found paths
  • API smoke runtime guardrails
  • messaging acceptance-semantics review
  • runbook/session-path and probe ergonomics
  • baseline catalog coverage visibility
  • flow-control threshold visibility
  • mailbox adapter probe helper ergonomics
  • live-audit follow-up status refresh
  • blocked-dispatch contract clarity
  • project plan and README queue sync
  • live audit entry-point follow-up link
  • live audit README and signoff entry sync
  • sprint-26 follow-up doc sync
  • residual-risk visibility sync
  • project-plan residual-risk clarity
  • backlog summary wording sync
  • final sprint-26 summary list sync

Status

  • abgeschlossen

Abschlussartefakte

  • docs/LIVE_TEST_FINDINGS_2026-03-29.md
  • docs/LIVE_AUDIT_FOLLOWUP_STATUS_2026-03-29.md
  • docs/FINAL_RELEASE_HARDENING.md
  • docs/RELEASE_CANDIDATE_SIGNOFF.md

Grenze

  • nach dieser Queue keine neue grosse Sprint-/Phasenserie ohne ausdrueckliche Freigabe

Sprint 27 - Residual Risk Reduction​

Ziel

  • die jetzt klar sichtbaren Restschulden in kleinen, produktnahen Slices abbauen

Issues

  • baseline catalog canonicalization pass
  • flow-control threshold tuning pass
  • blocked-dispatch product semantics pass
  • optional API runtime hardening
  • upgrade rule and catalog coverage extension
  • baseline catalog supplemental coverage seeds
  • sprint 27 closure sync
  • catalog refresh example contract sync
  • sprint 27 final queue tail sync
  • catalog refresh contract doc sync

Status

  • abgeschlossen

Grenze

  • nur kleine, direkt anschlussfaehige Slices innerhalb dieser Restschuld-Queue; danach wieder Stop bis zur naechsten explizit freigegebenen Folge-Queue

Phasenmodell​

Phase 0 - Foundations​

Ziel

  • gemeinsame Architektur und Datenmodelle schaffen

Status

  • abgeschlossen

Erreicht

  • Architektur-Dokumente
  • Upgrade-Intelligence-Dokumente
  • Grundbegriffe und Schichtenmodell
  • Trennung Basiskatalog / Overlay / Upstream / Learning

Rest

  • keine harten Restpunkte

Phase 1 - Upstream Connector​

Ziel

  • offizielle n8n-Releases und Tags integrieren
  • Version-Gap wie 1 behind, 2 behind sauber berechnen

Status

  • weitgehend abgeschlossen

Erreicht

  • offizieller Release-/Tag-Sync
  • GitHub-API- und Git-Remote-Fallback
  • Version-Gap-Berechnung
  • Delta-Erkennung mit:
    • new_versions
    • previous_latest_version
  • Status-/CLI-Integration

Offen

  • bessere Auswertung offizieller Release Notes fuer Breaking-/Migration-Hinweise
  • sauberere Klassifikation von Security-/Migration-Releases
  • optional spaeter: signierte/offline gespiegelt nutzbare Upstream-Metadaten

Phase 2 - Node Catalog Freshness System​

Ziel

  • n8n_nodes.db darf nicht mehr still veralten

Status

  • weitgehend abgeschlossen

Erreicht

  • Catalog-Freshness-Metadaten
  • Overlay-Architektur
  • Resolver-Pfad statt blindem Live-Overwrite
  • Freshness-Sichtbarkeit in CLI/API/Reports
  • reproduzierbarer Baseline-Catalog-Refresh gegen offizielle n8n-Upstream-Tags
  • Coverage-/Diff-/Provenance-Reports fuer den Basiskatalog
  • Scheduled-Signale und Contract-/Example-Abdeckung fuer Catalog-Build-Artefakte

Noch offen

  • weitergehende automatische Rebuild-Pfade fuer die komplette kuratierte SQLite-Basis
  • noch feinere Coverage-Validierung ueber Release-Familien und Spezialfaelle hinweg

Phase 3 - Upgrade Intelligence​

Ziel

  • vor einem Update echte Risiken auf echten Workflows erkennen

Status

  • weitgehend abgeschlossen

Erreicht

  • workflow-aware Upgrade-Impact
  • relevante Releases im Upgrade-Fenster
  • kuratierte Upgrade-Regeln
  • Rollups
  • Priority Backlog
  • Change-Window-Gruppen
  • Alerts
  • dedizierte Upgrade-Read-Endpunkte
  • learning- und execution-aware Zusatzsignale
  • Fixture-Packs fuer mehrere Rule-Familien

Noch offen

  • tiefere versionsspezifische Regeln pro n8n-Release
  • Credential-/Auth-Migrationsregeln mit hoeherer Genauigkeit
  • noch breitere Schema-Change-/Parameter-Change-Erkennung ueber die vorhandenen generischen Regeln hinaus
  • langfristige Pflege und Verdichtung der Community-Package-Kompatibilitaetsschaetzung

Phase 4 - Workflow Reachability And Live Impact Scan​

Ziel

  • nicht nur statische Analyse, sondern echte Relevanz auf real erreichbaren Workflows

Status

  • weitgehend abgeschlossen

Erreicht

  • Live-Inventar aus n8n-production
  • aktive/inaktive Tiering-Heuristik
  • reale produktive Workflows im Upgrade-Report
  • Produktionskritikalitaet, Owner-, Team-, Domain- und SLA-Signale
  • priorisierte Backlogs und Change-Window-Batches

Noch offen

  • noch feinere Published-/Production-Erkennung je n8n-Version
  • weitere Verfeinerung von Workflow-Familien-/Owner-Zuordnung aus Live-Metadaten

Phase 5 - Learning 2.0​

Ziel

  • Instanz-Lernen in echte Kompatibilitaetsintelligenz ueberfuehren

Status

  • weit fortgeschritten

Erreicht

  • instance_learning.db als reale Beobachtungsquelle
  • Learning Overlay als Bruecke
  • Credential-Typen und reale Node-Nutzung im Upgrade-Inventar
  • Learning Scores, Parameter-Signale und Success-Pattern-Enrichment
  • additive Learning-Summaries in Upgrade-Reports und Status-Surfaces
  • Bruecke zur Execution-Analyse fuer ausfuehrungsnahe Risikohinweise

Noch offen

  • langfristige Verdichtung der Learning-Signale ueber mehr Live-Historie
  • weitere Feinkalibrierung von Success-/Failure-Signalen fuer konkrete Upgrade-Empfehlungen

Phase 6 - Mission Control Integration​

Ziel

  • alle Erkenntnisse als stabilen Vertrag bereitstellen

Status

  • weitgehend abgeschlossen

Erreicht

  • WorkflowContext
  • Events
  • API
  • OpenAPI
  • Schema
  • Beispiele
  • Checklisten
  • Versioning
  • dedizierte Upgrade-Read-Endpunkte
  • Scheduled- und Upstream-Signal-Surfaces
  • breitere Contract-/Fixture-Abdeckung fuer Mission Control

Noch offen

  • spaetere Erweiterungen:
    • Audit-/Deploy-/Mailbox-Endpunkte
  • besserer Mission-Control-Consumer-Walkthrough

Phase 7 - Automation And Scheduled Freshness​

Ziel

  • das System pflegt sich aktiv

Status

  • weitgehend abgeschlossen

Erreicht

  • lokale Runner
  • GitHub Actions fuer Mission Control und Upgrade Intelligence
  • schedulable Upgrade-/Freshness-Automation
  • Event-Emission und Skip-Sichtbarkeit fuer Scheduled-Laeufe
  • read-only Scheduled-Report-Surfaces

Noch offen

  • echte dauerhafte Scheduler-Anbindung im Zielbetrieb
  • wiederholbare Langlauf-Evidence fuer das konkrete Betriebsumfeld

Phase 8 - Governance And Contracts​

Ziel

  • langfristige Wartbarkeit, Testbarkeit und Release-Reife

Status

  • weitgehend abgeschlossen

Erreicht

  • Versioning-Dokumentation
  • Readiness-Checks
  • Beispielartefakte
  • CI fuer zentrale Kontrakte
  • Contract-Change-Policy und Release-Matrix
  • breitere Fixture-Packs fuer Upgrade-, Catalog- und Upstream-Kontrakte
  • finale Hardening- und Signoff-Bundles

Noch offen

  • weitere Pflege der Release-Matrix und Fixture-Sets mit neuen n8n-Releases
  • finale Signoff-Evidence direkt vor einem oeffentlichen Release-Fenster

Sprintplan​

Die bereits umgesetzten Sprints sind unten als erledigt markiert. Die offenen Sprints bauen darauf auf.

Sprint 1 - Foundations And Upstream Basis​

Status

  • erledigt

Umfang

  • Phase 0
  • erste Teile von Phase 1

Geliefert

  • Architektur
  • Upstream-Sync-Grundlage
  • Version-Gap-Grundlage

Sprint 2 - Catalog Freshness And Overlay​

Status

  • weitgehend erledigt

Geliefert

  • Freshness-Metadaten
  • Overlay-Struktur
  • Sichtbarkeit in Status/Reports

Offen

  • echter Basiskatalog-Refresh

Sprint 3 - Erste Upgrade Intelligence​

Status

  • erledigt

Geliefert

  • Upgrade-Impact
  • relevante Releases
  • Downgrade-Erkennung
  • erste kuratierte Regeln

Sprint 4 - Live Workflow Reachability And Learning Bridge​

Status

  • weitgehend erledigt

Geliefert

  • Live-Workflow-Inventar
  • Instanz-Learning-Bruecke
  • reale Credential-Typen

Offen

  • tiefere Priorisierung produktionskritischer Flows

Sprint 5 - Mission Control Contract​

Status

  • erledigt

Geliefert

  • WorkflowContext
  • Event Bus
  • API
  • Beispiele
  • Smoke-Checks

Sprint 25 - Catalog Rebuild Provenance And Operations​

Status

  • abgeschlossen

Ziel

  • die noch offene Phase-2-Luecke um reproduzierbare Basiskatalog-Builds weiter schliessen

Geplante Slices

  • 25.01 Provenance und Digests fuer Baseline-Refresh-Artefakte
  • 25.02 Scheduled Signals fuer Catalog-Freshness und Build-Drift
  • 25.03 Contract-/Example-Erweiterung fuer den Baseline-Build-Pfad

Erwarteter Nutzen

  • spaetere Release-Builds koennen Baseline-Refresh-Artefakte besser vergleichen
  • Build-Herkunft und Tarball-Identitaet bleiben sichtbar
  • Mission-Control- und Operator-Surfaces koennen Build-Drift besser kommunizieren

Sprint 6 - Upgrade Governance Surfaces​

Status

  • weitgehend erledigt

Geliefert

  • backlog
  • batches
  • alerts
  • rollups
  • compact status surfaces

Offen

  • dedizierte Upgrade-Endpoints

Sprint 7 - Basiskatalog-Refresh Pipeline​

Status

  • abgeschlossen

Ziel

  • reproduzierbarer Build fuer n8n_nodes.db

Lieferobjekte

  • Build-Skript fuer Basiskatalog
  • diff-basierter Refresh
  • Coverage-Report
  • Release-Artefakt fuer Katalogversion

Bereits geliefert

  • offizieller Baseline-Snapshot aus dem n8n-Upstream-Tag
  • diff-/coverage-basierter Report gegen n8n_nodes.db
  • CLI-Befehl catalog baseline-refresh
  • Skript scripts/build_baseline_catalog.py
  • inhaltsbasierte Freshness-Signale statt reiner Timestamp-Sicht

Abnahme

  • Basiskatalog kann aus offizieller Quelle reproduzierbar aktualisiert werden
  • Freshness ist nicht nur Metadaten-, sondern inhaltlich belastbar

Sprint 8 - Deep Upgrade Rules​

Status

  • abgeschlossen

Ziel

  • tiefere inhaltliche Upgrade-Regeln pro n8n-Version

Lieferobjekte

  • versionsspezifische Breaking-/Migration-Regeln
  • Credential-/Auth-Regeln
  • Parameter-/Schema-Change-Regeln
  • groesserer Fixture-Satz

Abnahme

  • Report kann konkrete Problemtypen deutlich genauer erklaeren

Geliefert

  • parameterbasierte Regelmatcher
  • praezisere Webhook-/Data-Table-/HTTP-Request-Regeln
  • bessere erklaerbare Findings statt nur generischer Node-Warnungen

Sprint 9 - Community Package Intelligence​

Status

  • abgeschlossen

Ziel

  • Community-Packages als echte Risikoquelle sauber behandeln

Lieferobjekte

  • Package-Risiko-Metadaten
  • Unknown-/Unverified-/Known-Risk-Klassen
  • Version-/Kompatibilitaetsheuristik

Abnahme

  • Community-Risiken tauchen sauber und begruendet im Report auf

Geliefert

  • known / unverified / unknown Package-Zustaende
  • Community-Package-Rollups im Upgrade-Report
  • Package-Risiken in Findings und Summary

Sprint 10 - Production Criticality And Owners​

Status

  • abgeschlossen

Ziel

  • besseres Priorisieren von echten Produktionsworkflows

Lieferobjekte

  • production_critical-Signal
  • Owner-/Team-/Domain-Metadaten
  • SLA-/Trigger-Gewichtung

Abnahme

  • Backlog und Batches entsprechen eher der echten Betriebsrelevanz

Geliefert

  • production_critical
  • Owner-/Team-/Domain-/SLA-Signale
  • offengelegte priority_factors

Sprint 11 - Scheduled Automation​

Status

  • abgeschlossen

Ziel

  • die Upgrade-/Freshness-Schicht laeuft aktiv und nicht nur on demand

Lieferobjekte

  • taeglicher Upstream-Sync
  • taeglicher Freshness-Check
  • periodischer Instance-Scan
  • automatische Report-Neuberechnung

Abnahme

  • das System erkennt neue Releases und Drift auch ohne manuellen CLI-Lauf

Geliefert

  • schedulabler Upgrade-/Freshness-Runner
  • persistierte Automationssummaries unter logs/upgrade-automation/
  • beobachtbare Fehlerzustands-Summaries statt stiller Fehlschlaege

Sprint 12 - Mission Control Upgrade API​

Status

  • abgeschlossen

Ziel

  • Upgrade-Intelligence als eigene API-Flaeche ausbauen

Lieferobjekte

  • POST /api/v1/upgrade/impact
  • spaeter optional:
    • GET /api/v1/upgrade/backlog
    • GET /api/v1/upgrade/alerts
    • GET /api/v1/upgrade/batches

Abnahme

  • Mission Control braucht nicht mehr nur status, sondern kann gezielt Upgrade-Intelligence abrufen

Geliefert

  • POST /api/v1/upgrade/impact
  • OpenAPI-Dokumentation und API-Tests fuer den Upgrade-Impact-Pfad

Sprint 13 - Governance And Release Matrix​

Status

  • abgeschlossen

Ziel

  • belastbare Vertrags- und Release-Fuehrung

Lieferobjekte

  • Contract-Change-Prozess
  • n8n-Versionsmatrix
  • groesserer Fixture-Korpus
  • haertere Regressionstests

Abnahme

  • Breaking Changes an Kontrakten fallen in CI/Testmatrix sofort auf

Geliefert

  • n8n_expert/release_matrix.py
  • scripts/run_release_matrix_checks.py
  • Governance-/Release-Matrix-Dokumentation
  • CI-Einbindung fuer den Release-Matrix-Check

Sprint 14 - Release Härtung And Finish​

Status

  • abgeschlossen

Ziel

  • finaler produktionsreifer Zielzustand

Lieferobjekte

  • End-to-End-Abnahme
  • finale Runbooks
  • finale Release-Checklisten
  • Performance-/Stabilitaets-/Langzeitpruefung
  • Dokumentation fuer Betrieb und Weiterentwicklung

Bereits geliefert

  • scripts/run_final_release_hardening.py
  • maschinenlesbare Hardening-Evidence unter logs/release-hardening/
  • finale Hardening-Dokumentation und Handoff-Reihenfolge

Abnahme

  • Projekt erreicht die Definition of Done

Noch offen

  • wiederholbare Live-Abnahme im finalen Zielumfeld direkt vor einem oeffentlichen Release-Fenster
  • explizite Performance-/Langlauf-Evidence fuer die konkrete Zielumgebung

Sprint 15 - Security And Async Hardening​

Status

  • abgeschlossen

Geliefert

  • shell-sichere Session-Probes
  • async-sichere API-Route-Handler
  • input-Haertung fuer Route-Parameter
  • Startup-Warnings und non-blocking Diagnosepfade

Sprint 16 - Builder Registry And Lazy Loading​

Status

  • abgeschlossen

Geliefert

  • Builder-Registry
  • reduzierter CLI-Import-Footprint
  • lazy ladbare Builder-Kommandos

Sprint 17 - Final Runtime Polish​

Status

  • abgeschlossen

Geliefert

  • Builder-Registry-Expansion und Introspection
  • optionale Runtime-Ergonomics
  • finaler Runtime-Regression-Sweep

Sprint 18 - Upgrade Contract Completion​

Status

  • abgeschlossen

Geliefert

  • dedizierte Upgrade-Read-Endpunkte
  • Release-Matrix und Contract-Change-Policy
  • erweiterte Upgrade-Fixture-Packs

Sprint 19 - Scheduled Upgrade Signals​

Status

  • abgeschlossen

Geliefert

  • Scheduled-Event-Emission
  • Automation-Skip-Sichtbarkeit
  • Scheduled-Report-Read-Surfaces

Sprint 20 - Learning Signal Deepening​

Status

  • abgeschlossen

Geliefert

  • Learning Scores
  • Parameter-Signal-Bruecke
  • learning-getriebene Upgrade-Risk-Summaries

Sprint 21 - Learning Signal Operationalization​

Status

  • abgeschlossen

Geliefert

  • Success-Pattern-Enrichment
  • Learning-Status- und API-Surfaces
  • breitere Learning-Contract-/Fixture-Abdeckung

Sprint 22 - Execution History Learning Bridge​

Status

  • abgeschlossen

Geliefert

  • Execution-Analysis-Signal-Bridge
  • Failure-Hotspot-Summaries
  • execution-aware Upgrade-Risk-Summaries

Sprint 23 - Catalog Coverage Operationalization​

Status

  • abgeschlossen

Geliefert

  • Catalog-Refresh-Summary-Surface
  • Coverage-Status- und API-Surfaces
  • Catalog-Contract-/Fixture-Abdeckung

Sprint 24 - Upstream Release Note Operationalization​

Status

  • abgeschlossen

Geliefert

  • Release-Note-Topic-Enrichment
  • Upstream-Release-Signal-Surfaces
  • Upstream-Contract-/Fixture-Abdeckung

Was noch konkret zu tun ist​

Technische Restarbeiten mit hoechster Prioritaet​

  1. finale Live-Abnahme direkt im Release-Zielumfeld
  2. weitere Pflege/Vertiefung versionsspezifischer Upgrade-Regeln fuer neue n8n-Releases
  3. langfristige Pflege von Catalog-Build, Provenance und Coverage bei neuen Upstream-Staenden
  4. weitere Verdichtung von Live-Learning-/Execution-Signalen bei wachsender Betriebsdatenlage

Mittlere Prioritaet​

  1. dauerhafte Scheduler-/Ops-Einbindung fuer die bestehenden Runner
  2. breitere Release-/Fixture-/Contract-Matrix fuer kuenftige n8n-Majors und Community-Pakete
  3. bessere Langzeit-Lernsignale aus Executions und Fehlern

Niedrigere Prioritaet, aber wertvoll​

  1. offline-/airgapped-freundliche Upstream-Spiegel
  2. feinere Team-/Change-Window-Paketierung
  3. groessere operatorische UX-Politur in CLI/API

Risiken bis Projektabschluss​

Produkt-/Technikrisiken​

  • n8n_nodes.db bleibt ohne echten Basiskatalog-Refresh die groesste Langzeitluecke
  • Community-Packages bleiben ohne eigene Intelligence ein Unsicherheitsfaktor
  • Upgrade-Regeln muessen mit n8n aktiv gepflegt werden
  • echte Produktionskritikalitaet ist heute noch nur teilweise modelliert

Betriebsrisiken​

  • Live-API-Zugriff auf Zielinstanzen kann je Umgebung anders sein
  • On-Prem-Stack bleibt betrieblich komplexer als der Core Skill Mode
  • Change-Window-Qualitaet haengt auch an sauberer Daten- und Owner-Zuordnung

Definition Of Done​

Das Projekt gilt als "fertig", wenn alle folgenden Punkte erfuellt sind:

  1. Core Skill

    • stabil
    • dokumentiert
    • release- und smoke-getestet

  2. Mission Control

    • Vertrag stabil
    • API dokumentiert
    • Beispiele, Schema und CI vorhanden

  3. Upgrade Intelligence

    • echte Upstream-Anbindung
    • Basiskatalog-Refresh vorhanden
    • Learning-Overlay aktiv
    • Upgrade-Impact fuer reale Workflows belastbar

  4. Automation

    • taegliche oder periodische Checks laufen reproduzierbar
    • Alerts und Reports entstehen auch ohne manuellen Aufruf

  5. Governance

    • Versioning und Contract-Management stehen
    • Testmatrix deckt relevante n8n-Versionen und Kernkontrakte ab

  6. Operatorische Reife

    • Runbooks vorhanden
    • Backlog/Batches/Alerts sind fuer echte Change Windows nutzbar
    • Langzeitbetrieb ist nachvollziehbar und wartbar

Empfohlene naechste Reihenfolge​

Wenn ab jetzt sequenziell bis Projektabschluss weiterentwickelt wird, ist die empfohlene Reihenfolge:

  1. Sprint 7 - Basiskatalog-Refresh Pipeline
  2. Sprint 8 - Deep Upgrade Rules
  3. Sprint 9 - Community Package Intelligence
  4. Sprint 10 - Production Criticality And Owners
  5. Sprint 11 - Scheduled Automation
  6. Sprint 12 - Mission Control Upgrade API
  7. Sprint 13 - Governance And Release Matrix
  8. Sprint 14 - Release Haertung And Finish
  9. Stabilization 01 - End-to-End Regression Pass
  10. Stabilization 02 - Real Integration And Runtime Hardening
  11. Stabilization 03 - Bug Bash And Edge-Case Sweep
  12. Stabilization 04 - Release Candidate Signoff
  13. Sprint 15 - Security And Async Hardening
  14. Sprint 16 - Builder Registry And Lazy Loading
  15. Sprint 17 - Final Runtime Polish

Kurzfazit​

jhf-shuttle ist heute bereits mehr als ein Skill:

  • Mission-Control-ready
  • Upstream-aware
  • instance-aware
  • workflow-aware
  • operatorisch nutzbar

Fertig ist das Projekt aber noch nicht.

Der wichtigste verbleibende Hebel fuer echte Zukunftssicherheit ist:

  • ein reproduzierbarer Basiskatalog-Refresh

Der wichtigste verbleibende Hebel fuer produktionsnahe Upgrade-Sicherheit ist:

  • tiefere versionsspezifische Upgrade-Regeln plus Community-Package-Intelligence

Und der wichtigste verbleibende Hebel fuer echten Dauerbetrieb ist:

  • Automatisierung und Governance-Finalisierung

Nach Sprint 14: Stabilization Phase​

Wenn Sprint 07 bis Sprint 14 implementiert sind, ist das Produkt nicht automatisch "release-fertig". Danach folgt eine explizite Stabilization-Phase, in der keine neuen grossen Produktfeatures priorisiert werden, sondern reale Nutzungsfluesse, Integrationsverhalten, Fehlerpfade und Release-Reife systematisch abgearbeitet werden.

Stabilization 01 - End-to-End Regression Pass​

Ziel

  • alle Hauptpfade einmal als reproduzierbare Produktfluesse laufen lassen

Scope

  • CLI-Flows fuer Upgrade-Impact, Basiskatalog-Refresh, Community-Package-Analyse und Release-Hardening
  • Datenbank-/Artefaktpfade
  • Automation-Runner und erzeugte Summaries
  • Mission-Control-API-Grundpfad fuer Upgrade-Impact

Abnahme

  • dokumentierte Regression-Evidence fuer die wichtigsten Produktfluesse
  • reproduzierbare Checkliste fuer kuenftige Regressionen

Stabilization 02 - Real Integration And Runtime Hardening​

Ziel

  • reale Integrations- und Runtime-Pfade haerten statt nur synthetische Tests gruen zu halten

Scope

  • Mission-Control-Integration gegen den echten Zielpfad
  • Logging, Failure-Summaries, Exit-Codes und fehlertolerante API-/Runtime-Pfade
  • Absicherung optionaler Schichten, wenn eine Umgebung nicht alle Subsysteme bereitstellt

Abnahme

  • reale Integrationsfehler wurden reproduziert, verstanden und wenn sinnvoll direkt behoben
  • verbleibende Runtime-Limits sind explizit dokumentiert

Stabilization 03 - Bug Bash And Edge-Case Sweep​

Ziel

  • bekannte Schwachstellen und Beobachtungen in kleine, saubere Fix-Slices ueberfuehren

Scope

  • CLI-UX, Path-Handling, leere Inputs, optionale Konfiguration, unerwartete API-Rueckgaben, Reporting-Luecken
  • inkonsistente Warn-/Error-Texte
  • edge cases aus vorangegangenen Regressionen

Abnahme

  • priorisierte Bug-Bash-Slices abgearbeitet
  • auffaellige Edge Cases sind entweder behoben oder bewusst als Limit dokumentiert

Stabilization 04 - Release Candidate Signoff​

Ziel

  • eine belastbare Release-Candidate-Evidence erzeugen

Scope

  • finaler Hardening-Bundle-Lauf
  • Review der wichtigsten Artefakte und Logs
  • letzte kleine Korrekturen aus der Stabilization-Phase
  • Abschlussdokumentation fuer Release-/Handoff-Entscheidung

Abnahme

  • klarer Release-Candidate-Status mit sauberer Evidence
  • offene Restpunkte sind klein, explizit und release-entscheidbar

Nach der Stabilization: Post-RC Hardening​

Die Stabilization-Phase hat einen belastbaren Release-Candidate erzeugt, aber nicht jede spuerbare Sicherheits- und Runtime-Rauheit beseitigt. Danach folgt eine kleine, gezielt technische Hardening-Schiene statt einer breiten Produktphase.

Sprint 15 - Security And Async Hardening​

Ziel

  • bekannte Security- und Event-Loop-Risiken gezielt beseitigen

Scope

  • shell-sichere Session-Probe-Ausfuehrung
  • async-sichere API-Route-Handler fuer blocking n8n-Calls
  • input-Haertung fuer Route-Parameter
  • startup warnings und blocking wait-Reste in API-/Diagnosepfaden

Abnahme

  • keine direkte Shell-Ausfuehrung untrusted Probe-Strings mehr
  • API-Handler blockieren den aiohttp Event Loop nicht mehr an den bekannten Hotspots
  • Route-Fehler fuer ungültige Eingaben werden sauber als 400 statt als ungefangene Exceptions behandelt

Sprint 16 - Builder Registry And Lazy Loading​

Ziel

  • CLI-Imports und Builder-Flaeche modularisieren

Scope

  • Builder-Registry fuer durchsuchbare, lazy ladbare Builder
  • Reduktion frueher, grosser Direkt-Imports im CLI-Einstieg
  • Dokumentation des Registry-Vertrags

Abnahme

  • Builder koennen ueber eine Registry aufgeloest werden
  • der CLI-Einstieg importiert nicht mehr blind grosse Teile des Builder-Surfaces

Sprint 17 - Final Runtime Polish​

Ziel

  • die verbleibenden kleinen Runtime-/Operator-Kanten fuer den dauerhaften Betrieb glätten

Scope

  • Rest-UX fuer Warnings/Errors
  • kleine API-/CLI-Politur
  • erneuter Hardening-/Regression-Durchlauf nach Sprint 15/16

Abnahme

  • keine bekannten kleinen Runtime-Kanten bleiben still offen
  • finale Evidence ist nach dem Post-RC-Hardening erneut gruen

Issue-Slices

  • ISSUE_SPRINT_17_01_BUILDER_REGISTRY_EXPANSION_AND_INTROSPECTION.md
  • ISSUE_SPRINT_17_02_OPTIONAL_RUNTIME_ERGONOMICS.md
  • ISSUE_SPRINT_17_03_FINAL_RUNTIME_REGRESSION_SWEEP.md

Sprint 18 - Upgrade Contract Completion​

Ziel

  • die noch offenen Upgrade-/Governance-Vertragsluecken aus Phase 6 und 8 schliessen

Scope

  • dedizierte Upgrade-Read-Endpunkte statt nur Status-Surface
  • Release-Matrix und Contract-Change-Policy dokumentieren
  • Fixture-Packs fuer Upgrade-/Compatibility-Regeln breiter machen

Abnahme

  • Upgrade-Backlog/Batches/Alerts sind ueber eigene API-Surfaces lesbar
  • Governance-Regeln fuer Vertragsaenderungen sind dokumentiert
  • die Upgrade-Regeln haben breitere, versionierte Fixture-Abdeckung

Issue-Slices

  • ISSUE_SPRINT_18_01_DEDICATED_UPGRADE_READ_ENDPOINTS.md
  • ISSUE_SPRINT_18_02_RELEASE_MATRIX_AND_CONTRACT_CHANGE_POLICY.md
  • ISSUE_SPRINT_18_03_UPGRADE_FIXTURE_PACK_EXPANSION.md

Sprint 19 - Scheduled Upgrade Signals​

Ziel

  • die bestehende Scheduled-Upgrade-Automation von einem lokalen Runner zu einer klar beobachtbaren Signalquelle ausbauen

Scope

  • Event-Emission fuer geplante Upgrade-Laeufe
  • explizite Sichtbarkeit von Skip-/Degrade-Pfaden
  • spaetere Read-Surfaces fuer die letzten Scheduled-Laeufe

Abnahme

  • die geplante Upgrade-Automation emittiert ihre wichtigsten Signale nach dem bestehenden Event-Vertrag
  • Skip-/Degrade-Pfade bleiben beobachtbar
  • Scheduled-Run-Ergebnisse koennen spaeter gezielt gelesen werden

Issue-Slices

  • ISSUE_SPRINT_19_01_SCHEDULED_UPGRADE_EVENT_EMISSION.md
  • ISSUE_SPRINT_19_02_AUTOMATION_SKIP_VISIBILITY.md
  • ISSUE_SPRINT_19_03_SCHEDULED_REPORT_READ_SURFACES.md

Sprint 20 - Learning Signal Deepening​

Ziel

  • den Learning-Overlay-Pfad von rohen Beobachtungen zu brauchbareren Upgrade-Signalen ausbauen

Scope

  • additive Learning-Scores
  • beobachtete Parameter-/Schema-Signale
  • spaeter verdichtete Learning-getriebene Upgrade-Zusammenfassungen

Abnahme

  • Upgrade-Signale enthalten mehr als rohe Usage-Zahlen
  • beobachtete Parameter koennen spaeter in Risiko-Summaries einfliessen
  • die neuen Felder bleiben additive und testbar

Issue-Slices

  • ISSUE_SPRINT_20_01_LEARNING_SCORE_ENRICHMENT.md
  • ISSUE_SPRINT_20_02_PARAMETER_SIGNAL_BRIDGE.md
  • ISSUE_SPRINT_20_03_LEARNING_DRIVEN_UPGRADE_RISK_SUMMARY.md

Sprint 21 - Learning Signal Operationalization​

Ziel

  • die vorhandenen Learning-Daten staerker in operatorisch nutzbare Verträge und Priorisierungssignale überfuehren

Scope

  • Success-Pattern-Signale aus build_history und node_success_patterns
  • kompakte Learning-Status-Surfaces fuer CLI/API/Mission Control
  • breitere Vertrags- und Fixture-Abdeckung fuer Learning-getriebene Reports

Abnahme

  • compute_upgrade_signals() nutzt nicht nur Usage und Parameter, sondern auch vorhandene Erfolgs-Historie
  • Learning-Signale sind ueber kompakte Read-Surfaces beobachtbar
  • Learning-getriebene Reportfelder sind ueber Fixtures und Readiness-Checks abgesichert

Issue-Slices

  • ISSUE_SPRINT_21_01_SUCCESS_PATTERN_ENRICHMENT.md
  • ISSUE_SPRINT_21_02_LEARNING_STATUS_AND_API_SURFACES.md
  • ISSUE_SPRINT_21_03_LEARNING_CONTRACT_AND_FIXTURE_EXPANSION.md

Sprint 22 - Execution History Learning Bridge​

Ziel

  • vorhandene Execution-Analyse und Pattern-Erkennung in additive, spaeter upgrade-relevante Lernsignale ueberfuehren

Scope

  • kompakte Bridge zwischen execution_analyzer und Learning-/Risk-Surfaces
  • read-only Failure-Hotspot-Summaries
  • spaeter additive execution-aware Risiko-Hinweise in Upgrade-Reports

Abnahme

  • bestehende Execution-Analyse kann in kompakten, erklaerbaren Signals zusammengefasst werden
  • Failure-Hotspots sind ueber kleine Read-Surfaces beobachtbar
  • execution-aware Signale bleiben additive und verdrängen keine expliziten Rule-Findings

Issue-Slices

  • ISSUE_SPRINT_22_01_EXECUTION_ANALYSIS_SIGNAL_BRIDGE.md
  • ISSUE_SPRINT_22_02_FAILURE_HOTSPOT_SUMMARY_SURFACES.md
  • ISSUE_SPRINT_22_03_EXECUTION_AWARE_UPGRADE_RISK_SUMMARY.md

Sprint 23 - Catalog Coverage Operationalization​

Ziel

  • den bestehenden Baseline-Catalog-Refresh fuer Operatoren und Mission Control kompakter und beobachtbarer machen

Scope

  • kompakte Summary des letzten Baseline-Refresh-Laufs
  • spaeter Status-/API-Surfaces fuer Catalog-Coverage
  • Fixture-/Contract-Abdeckung fuer Catalog-Refresh-Artefakte

Abnahme

  • der letzte Catalog-Refresh-Lauf ist ueber eine kleine Summary lesbar
  • Coverage- und Missing-Signale koennen spaeter in Status/API einfliessen
  • Contract-/Fixture-Abdeckung faengt spaetere Regressions besser ab

Issue-Slices

  • ISSUE_SPRINT_23_01_CATALOG_REFRESH_SUMMARY_SURFACE.md
  • ISSUE_SPRINT_23_02_CATALOG_COVERAGE_STATUS_AND_API_SURFACES.md
  • ISSUE_SPRINT_23_03_CATALOG_CONTRACT_AND_FIXTURE_EXPANSION.md

Sprint 24 - Upstream Release Note Operationalization​

Ziel

  • offizielle Release-Hinweise besser in erklaerbare Upgrade-Signale uebersetzen

Scope

  • kompakte Themen-/Hinweis-Extraktion aus offiziellen Release Notes
  • spaeter read-only Surfaces fuer diese Release-Signale
  • Fixture-/Contract-Abdeckung fuer neue Upstream-Felder

Abnahme

  • Upstream-Releases tragen mehr als nur notes_excerpt, breaking_hint und security_hint
  • neue Felder bleiben additive und explainable
  • Release-Signale koennen spaeter in Status/Reports genutzt werden

Issue-Slices

  • ISSUE_SPRINT_24_01_RELEASE_NOTE_TOPIC_ENRICHMENT.md
  • ISSUE_SPRINT_24_02_UPSTREAM_RELEASE_SIGNAL_SURFACES.md
  • ISSUE_SPRINT_24_03_UPSTREAM_CONTRACT_AND_FIXTURE_EXPANSION.md

AGPLv3. Learn more at helpifyr.com.