ROAD-2026-001 – Koordiniertes Integrationsprogramm für ARCH-2026-001 bis ARCH-2026-006¶

Status: Entwurf
Proposal-Status: accepted
Kategorie: roadmap
Erstellt: 2026-07-07
Stand: 2026-07-07
Geprüfter Repository-Stand: f84c881aace65ff9aa857b43fc2de4b0a7998397

Entscheidung¶

Am 2026-07-07 wurde Variante B bestätigt:

ARCH-2026-001 bis ARCH-2026-006 werden als ein gemeinsames
Architektur-Integrationsprogramm geplant.

Die technische Umsetzung erfolgt nicht in einem Mega-Branch oder
Mega-Pull-Request, sondern in sequenziellen, einzeln prüfbaren und
rückrollbaren Integrationswellen.

Jede technische Welle basiert auf dem danach aktuellen main-Stand
und besitzt eigenen Scope, Tests, Abschlussgate, Review und Rollback.

Diese Entscheidung legt Reihenfolge und Integrationsstrategie fest. Sie setzt keines der sechs Architektur-Proposals automatisch auf accepted oder integrated.

Anlass und Ausgangsproblem¶

Die sechs Architektur-Proposals sind voneinander abhängig:

ARCH-2026-001
  Frontend-State, Render-Orchestrierung und View-Eigentümerschaft

ARCH-2026-002
  Snapshot-basierte Reportdatenpipeline und reporttypspezifische ViewModels

ARCH-2026-003
  schlanke Architekturentscheidungsnachweise und Ablösung

ARCH-2026-004
  reproduzierbare Prüf-, Release- und Container-Baseline

ARCH-2026-005
  Post-Merge-Verifikation des integrierten Repository-Standes

ARCH-2026-006
  Deployment- und Produktionsnachweis mit Drift-Erkennung

Eine gemeinsame Umsetzung in einem einzelnen technischen Änderungsblock würde Governance, CI, Deployment, Frontend und Reporting vermischen.

Risiken eines Mega-Pull-Requests:

sehr großer Diff
unklare Fehlerursachen
Rollback nur als Gesamtpaket
lange Branch-Lebensdauer und Drift zu main
schwierige Reviews
unklare Integrationscommits je Proposal

Geltungsbereich¶

ROAD-2026-001 steuert:

Reihenfolge und Abhängigkeiten
Aufteilung in Integrationswellen
Branch- und Pull-Request-Strategie
Abschlussgates
semantische Dateieigentümerschaft
Gesamtabschluss des Architekturprogramms

Nicht Teil dieses Proposals:

Detailentscheidung eines ARCH-Proposals
konkrete Implementierung
Änderung von Formeln, KPIs oder fachlichen Verträgen
automatisches Mergen
automatisches Setzen von Proposal-Statuswerten

Integrationsprinzipien¶

1. Kein Mega-Pull-Request für alle sechs Proposals.
2. Welle 0 bleibt ausschließlich docs-only.
3. Technische Umsetzung beginnt erst bei Proposal-Status accepted.
4. Jede technische Welle startet vom dann aktuellen main.
5. Jede Welle besitzt eigenen Testnachweis und Rollback.
6. Nachfolgende Wellen verwenden bereits integrierte Schutzmechanismen.
7. Jedes Proposal erhält einen eigenen Integrationsnachweis.
8. Kein automatischer Merge nach main.

Abhängigkeitsmodell¶

Welle 0
Proposal-Konsolidierung und Entscheidungsfreeze
        |
        v
Welle 1
ARCH-2026-003
Governance und Decision Records
        |
        v
Welle 2
ARCH-2026-004 Teil A
Runtime-Baseline und kanonischer Contract Check
        |
        v
Welle 3
ARCH-2026-005
Post-Merge-Verifikation
        |
        v
Welle 4
ARCH-2026-004 Teil B
Release-Artefakte, Aktivierung und Rollback
        |
        v
Welle 5
ARCH-2026-006
DeploymentRecord, EnvironmentState und Drift
        |
        v
Welle 6
ARCH-2026-001
AnalysisState und Render-Orchestrierung
        |
        v
Welle 7
ARCH-2026-002
ReportSource, ViewModels und Reportrenderer
        |
        v
Welle 8
Gesamtintegration und Baseline-Fixierung

Begründung der Reihenfolge¶

ARCH-2026-003 zuerst:
  Governance, ADR-Rolle und Integrationsreferenzen werden geklärt.

ARCH-2026-004 Teil A danach:
  ein kanonischer Check und eine fixierte Runtime-Baseline schützen
  alle folgenden Änderungen.

ARCH-2026-005 danach:
  der tatsächlich gemergte main-Commit wird erneut geprüft.

ARCH-2026-004 Teil B danach:
  unveränderbare Artefakte, Release-ID, Aktivierung und Rollback entstehen.

ARCH-2026-006 danach:
  der tatsächlich laufende Release wird nachgewiesen und Drift erkannt.

ARCH-2026-001 danach:
  Frontend-State und View-Eigentümerschaft werden unter der neuen
  Prüf- und Releasekette refaktoriert.

ARCH-2026-002 danach:
  Reporting baut auf dem stabilisierten AnalysisState auf.

Welle 0 – Proposal-Konsolidierung¶

Umfang:

ARCH-2026-001 bis ARCH-2026-006 konsolidieren
Architecture-Proposal-Index zentral neu aufbauen
Roadmap-Proposal-Index aktualisieren
MkDocs-Navigation synchronisieren
Begriffe und Querverweise angleichen
keine führende Spezifikation ändern
keinen Code, kein Schema, keine Konfiguration und keinen Test ändern

Branch:

docs/architecture-proposal-consolidation

Draft-Pull-Request:

#35 – docs: consolidate architecture proposals and integration roadmap

Abschlussgate:

alle sechs Proposal-Dateien vorhanden
Index und MkDocs vollständig
Diff ausschließlich docs-only
Contract Check erfolgreich
MkDocs strict build erfolgreich
Review abgeschlossen
bewusster Merge nach main

Aktueller Stand:

Proposal-Konsolidierung: abgeschlossen
Architecture- und Roadmap-Index: abgeschlossen
MkDocs-Navigation: abgeschlossen
Diffprüfung: abgeschlossen
Contract Check für Commit 5011de131b1908d3451aa62ce2e2140f328d19d2: erfolgreich
Draft-PR #35: offen
Review und Merge nach main: offen

Ergebnis nach Merge:

ROAD-2026-001 bleibt accepted.
ARCH-2026-001 bis ARCH-2026-006 bleiben under_review,
solange ihre umsetzungsrelevanten Detailentscheidungen offen sind.
Kein Architektur-Proposal wird durch Welle 0 integrated.

Welle 1 – ARCH-2026-003¶

Umfang:

Governancepräzisierung
ADR-Metadaten und eindeutige IDs
Entscheidungsindex
current-, partial- und historical-Einordnung
check-decision-records
AGENTS.md-Klarstellung

Gate:

ARCH-2026-003 accepted
Dokumentationsbuild erfolgreich
Decision-Record-Konsistenztest erfolgreich
keine führende Spezifikation durch ADR dupliziert
Integrationscommit dokumentiert

Welle 2 – ARCH-2026-004 Teil A¶

Umfang:

maschinenlesbare Runtime-Baseline
Image-, Tool- und Action-Pinning
kanonischer Contract-Check-Einstieg
lokale und CI-Prüfparität
gekapselte Headless-Browserprüfung

Gate:

ARCH-2026-004 accepted
kanonischer Check lokal und in CI erfolgreich
keine parallelen Prüfkataloge
Runtime-Baseline eindeutig
bestehendes Deployment rückfallfähig

Welle 3 – ARCH-2026-005¶

Umfang:

push-main-Verifikation
workflow_dispatch für expliziten Commit
IntegrationVerificationRecord
Integrations-Metaprüfungen
Evidence-Retention

Gate:

ARCH-2026-005 accepted
erster erfolgreicher Record für einen integrierten main-Commit
bewusster Wiederholungslauf erfolgreich
negativer Referenzfall korrekt als failed erkannt

Welle 4 – ARCH-2026-004 Teil B¶

Umfang:

unveränderbares Web-Artefakt
statisches Docs-Artefakt
Release-ID und Release-Manifest
Build außerhalb des aktiven Produktionspfads
explizite Aktivierung
Rollback auf vorherigen Release

Gate:

Release parallel gebaut und geprüft
Aktivierung erst nach Freigabe
Rollback technisch getestet
App- und Docs-Routing unverändert

ARCH-2026-004 wird erst nach Teil A und Teil B vollständig integrated.

Welle 5 – ARCH-2026-006¶

Umfang:

DeploymentRecord
EnvironmentState
Web- und Docs-Release-Manifeste
Post-Deployment-Soll-Ist-Vergleich
Drift-Findings
BrowserAcceptanceRecord-Verknüpfung
Rollback als neues Deploymentereignis

Gate:

ARCH-2026-006 accepted
App und Doku weisen dieselbe Release-ID nach
beobachtete Artefakte entsprechen dem erwarteten Release
Drift-Referenzfälle werden erkannt
produktiver DeploymentRecord vorhanden
Rollbackrecord getestet

Welle 6 – ARCH-2026-001¶

Umfang:

vollständiger AnalysisState
explizite Render-Orchestrierung
eindeutige View-Eigentümerschaft
keine fachliche DOM-Rücklesequelle
keine zeitversetzten Korrekturketten
stabile Lifecycle-Zustände

Gate:

ARCH-2026-001 accepted
Berechnungsbaseline unverändert
kein DOM-Ziel besitzt mehrere schreibende Owner
Browserregressionen erfolgreich
Speichern, Öffnen und Neuberechnung korrekt
Release und Deployment nachgewiesen

Welle 7 – ARCH-2026-002¶

Umfang:

ReportSource-Vertrag
ReportDataBuilder
reporttypspezifische ViewModels
reine Reportrenderer
keine DOM- oder Formularwerte als Reportquelle

Gate:

ARCH-2026-002 accepted
Reports verwenden nur AnalysisResult oder PropertyRecord
unberechnete Formularänderungen verändern keinen Report
Reporttypen bleiben getrennt
Print- und Browserabnahme erfolgreich

Welle 8 – Gesamtintegration¶

Umfang:

Querverweise konsolidieren
führende Architektur- und Validierungsdokumente synchronisieren
Roadmap und current-status aktualisieren
Changelog aktualisieren
notwendige ADR-Nachweise ergänzen
alle Proposal-Status und Integrationscommits prüfen
vollständigen Contract Check ausführen
Post-Merge-Verifikation ausführen
Release bauen und deployen
Deployment- und Browserabnahme abschließen

Branch- und Pull-Request-Strategie¶

Welle 0:
  ein docs-only Konsolidierungsbranch

Wellen 1 bis 7:
  je Welle ein kleiner Branch vom aktuellen main

ARCH-2026-004:
  zwei technische Pull Requests unter demselben accepted Proposal

Welle 8:
  kleiner Abschluss- und Dokumentationsbranch

Nicht zulässig:

langfristiger Gesamtimplementierungsbranch
automatischer Merge nach main
pauschales integrated für mehrere Proposals

Semantische Dateieigentümerschaft¶

Proposal-Index und MkDocs-Navigation:
  Welle 0

Governance, AGENTS.md und Decision Records:
  ARCH-2026-003

Runtime-Baseline, Contract Check und Prüfimages:
  ARCH-2026-004 Teil A

Post-Merge-Workflow und IntegrationVerificationRecord:
  ARCH-2026-005

Release-Build, Aktivierung und Rollback:
  ARCH-2026-004 Teil B

DeploymentRecord, EnvironmentState und Produktionsdrift:
  ARCH-2026-006

Frontend-Controller und Ergebnisrenderer:
  ARCH-2026-001

ReportSource, ReportData, ViewModels und Reportrenderer:
  ARCH-2026-002

Eine Datei darf in mehreren Wellen verändert werden. Die semantische Eigentümerschaft der jeweiligen Änderung muss eindeutig bleiben.

Statusregeln¶

under_review:
  Detailentscheidungen sind offen.

accepted:
  Ziel und umsetzungsrelevante Detailentscheidungen sind beschlossen.

integrated:
  Proposalumfang ist vollständig umgesetzt, geprüft und mit
  Integrationscommit dokumentiert.

Besondere Regeln:

ARCH-2026-004 bleibt nach Teil A accepted.
ARCH-2026-006 wird erst nach realem Deploymentnachweis integrated.
ARCH-2026-001 und ARCH-2026-002 benötigen eigene Browser- beziehungsweise Reportabnahmen.

Voraussetzungen vor Welle 1¶

Vor dem ersten technischen Implementierungsbranch müssen mindestens entschieden sein:

ARCH-2026-003:
  ADR-Metadaten und Klassifikationsregeln

ARCH-2026-004 Teil A:
  Runtime-Baseline-Datei
  Pinning-Tiefe
  Contract-Check-Umfang
  Browser-Testumgebung

ARCH-2026-005:
  Trigger und Mindestfelder des IntegrationVerificationRecord

Gemeinsame Definition of Done¶

alle sechs ARCH-Proposals einzeln integrated
alle Integrationscommits dokumentiert
keine offene Entscheidung als verbindliche Regel verwendet
führende Dokumente und maschinenlesbare Verträge synchron
kanonischer Contract Check erfolgreich
finaler main-Commit post-merge verified
unveränderbarer Release erzeugt
App und Doku weisen denselben Release nach
DeploymentRecord technical_verified oder accepted
Browserabnahmen abgeschlossen
Rollbackpfad nachgewiesen
Roadmap, current-status und Changelog synchron

Auswirkungen¶

Architektur:
  keine unmittelbare Produktarchitekturänderung

Roadmap:
  priorisierter Architektur-Stabilisierungsblock vor Expert Mode,
  Reportingausbau und Batch

Formeln, KPIs und fachliche Datenverträge:
  keine unmittelbare Änderung

UI, Reporting und Speicherung:
  keine unmittelbare Änderung durch ROAD-2026-001

Risiken und Gegenmaßnahmen¶

Risiko Mega-Pull-Request: sehr hoch
Risiko Wellenmodell: mittel

Hauptrisiken:

zu lange Übergangszustände
unnötig große Einzelwellen
unklare Dateieigentümerschaft
zu frühes integrated
zusätzlicher Dokumentationsaufwand

Gegenmaßnahmen:

kleine Pull Requests
feste Gates
frühe Post-Merge-Verifikation
individueller Proposal-Status
aktueller main als Basis jeder technischen Welle
kein automatischer Merge

Sicherungs- und Rückfallstrategie¶

Vor jeder technischen Welle:

sauberen main-Stand prüfen
aktuelle Regressionen ausführen
betroffene Baseline sichern
Rollback festlegen

Vor Deploymentwellen zusätzlich:

aktive Image- und Artefaktidentitäten sichern
Compose-Konfiguration sichern
lokale und öffentliche Smoke-Tests dokumentieren
vorherigen Release verfügbar halten

Zieldokumente¶

ARCH-2026-001 bis ARCH-2026-006
docs/changes/proposals/architecture/README.md
docs/changes/proposals/roadmap/README.md
docs/changes/proposals/roadmap-additions.md
mkdocs.yml

Integrationscommit¶

offen