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

Status: Entwurf
Proposal-Status: under_review
Kategorie: architecture
Erstellt: 2026-07-05
Stand: 2026-07-07
Geprüfter Repository-Stand: f84c881aace65ff9aa857b43fc2de4b0a7998397

Anlass¶

Immohai prüft Pull Requests bereits umfangreich. Ein erfolgreicher Pull-Request-Check beweist jedoch nicht automatisch, dass der danach tatsächlich auf main vorliegende Gesamtstand mit derselben Tiefe geprüft wurde.

Merge-Reihenfolge, parallele Proposal-Branches, manuelle Konfliktauflösungen, nachgelagerte Dokumentationsänderungen und veraltete Statusangaben können dazu führen, dass der integrierte Repository-Stand von dem zuvor geprüften Änderungsstand abweicht.

Bestätigte Teilentscheidung 1 – Umfang¶

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

ARCH-2026-005 wird nicht auf einen optionalen manuellen Wiederholungslauf
bestehender Pull-Request-Checks begrenzt.

Das Proposal definiert eine formale Post-Merge-Verifikation des tatsächlich
integrierten Repository-Commits auf main.

Der integrierte Commit wird in einem sauberen Checkout mit derselben
kanonischen Prüf- und Runtime-Baseline verifiziert, die ARCH-2026-004
für lokale Prüfung, CI und Releasebereitstellung festlegt.

Das Ergebnis wird als nachvollziehbarer IntegrationVerificationRecord
festgehalten. Eine erfolgreiche Verifikation ist notwendige, aber nicht
allein hinreichende Voraussetzung für den Proposal-Status integrated.

Die konkrete Triggerstrategie, das Evidence-Format und mögliche Prüfprofile bleiben Gegenstand weiterer Einzelentscheidungen.

Ausgangsproblem¶

Der aktuelle Prozess ist vereinfacht:

Feature- oder Proposal-Branch
-> Pull-Request-Workflow
-> Merge nach main
-> kein gleichwertiger automatischer Post-Merge-Lauf
-> später Deploymentprüfung mit abweichendem Prüfumfang

Damit bleiben mehrere Fragen unbeantwortet:

Wurde exakt der integrierte main-Commit vollständig geprüft?
Wurden Mergekonflikte und parallele Änderungen mitgeprüft?
Sind Governance, Proposals, Spezifikationen, Verträge, Code und Tests synchron?
Ist der dokumentierte Arbeits- und Deploymentstand noch wahr?
Kann die Verifikation bewusst und reproduzierbar wiederholt werden?
Welche prüfbare Evidenz rechtfertigt den Status integrated?

Relevanter bestehender Stand¶

Betroffene Grundlagen mindestens:

AGENTS.md
docs/governance/documentation-system.md
docs/governance/change-control.md
docs/specification/data-quality-and-validation/validation.md
docs/operations/deployment.md
docs/operations/browser-acceptance.md
docs/roadmap/current-status.md
docs/changes/changelog.md
docs/changes/proposals/**
docs/changes/decisions/**
.github/workflows/contract-check.yml
scripts/check-specification-consistency.mjs
scripts/check-frontend-baseline.sh
scripts/deploy-and-verify.sh

Angrenzende Architektur-Proposals:

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-006
  nachweisbarer Deployment- und Produktionsstand sowie Drift-Erkennung

Nachgewiesene aktuelle Lücken¶

1. Der Contract-Check läuft nur für Pull Requests¶

Der aktuelle Workflow reagiert auf:

pull_request nach main

Nicht vorgesehen sind derzeit:

push nach main
workflow_dispatch für bewussten Wiederholungslauf
Verifikation eines ausgewählten integrierten Commits

Damit ist der tatsächliche Post-Merge-Stand nicht durch denselben Workflow abgesichert.

2. Pull-Request-Ergebnis und integrierter Commit sind nicht zwingend identisch¶

Ein Pull Request kann gegen einen temporären Merge-Commit oder einen zu diesem Zeitpunkt aktuellen Base-Stand geprüft werden.

Nach dem Merge können Unterschiede entstehen durch:

weitere inzwischen gemergte Pull Requests
manuelle Konfliktauflösung
Rebase oder Merge-Strategie
nachgelagerte Korrekturcommits
separate Proposal-Branches mit gemeinsamer Indexdatei

Gerade ARCH-2026-001 bis ARCH-2026-006 verändern teilweise dieselben Übersichts-, Governance- oder Architekturdokumente und müssen später kontrolliert zusammengeführt werden.

3. CI und Deploymentprüfung sind nicht gleichwertig¶

Der Pull-Request-Workflow enthält mehr Prüfungen als scripts/check-frontend-baseline.sh, das vom Deploymentpfad verwendet wird.

ARCH-2026-004 soll einen kanonischen Contract Check herstellen. ARCH-2026-005 muss diesen Prüfumfang anschließend auf den tatsächlich integrierten Commit anwenden und darf keine dritte Prüfdefinition einführen.

4. Konsistenz kann veraltete Aussagen reproduzierbar festschreiben¶

Der aktuelle Spezifikationskonsistenztest prüft unter anderem, dass bestimmte Dokumente denselben produktiven Baseline-Commit und denselben Hinweis auf Pull Request #12 enthalten.

Damit kann die Prüfung erfolgreich sein, obwohl eine mehrfach wiederholte Statusaussage inzwischen sachlich veraltet ist.

Es muss deshalb unterschieden werden zwischen:

interner Textkonsistenz
  mehrere Dateien enthalten dieselbe Aussage

und

integrierter Zustandswahrheit
  die Aussage entspricht dem tatsächlichen Repository-, Release-
  und Produktionsstand

5. Kein formaler Integrationsnachweis¶

Es gibt derzeit kein standardisiertes Artefakt, das mindestens dokumentiert:

welcher Commit geprüft wurde
welche Runtime-Baseline verwendet wurde
welcher Prüfumfang lief
welche Ergebnisse vorlagen
welche Artefakte erzeugt wurden
ob Wiederholung denselben Stand bestätigt

6. Proposal-Status integrated ist nicht technisch unterlegt¶

Der Governance-Prozess definiert integrated als vollständig in alle betroffenen verbindlichen Artefakte übernommen und geprüft.

Der aktuelle Prozess beschreibt jedoch nicht, welche konkrete Post-Merge-Evidenz diesen Status technisch unterstützt.

7. Browserabnahme und Repository-Verifikation sind vermischt, aber nicht verbunden¶

Die Browserabnahme verlangt einen Integrationscommit und einen dokumentierten Deploymentzeitpunkt. Der automatisierte Repository-Check ersetzt die interaktive Abnahme ausdrücklich nicht.

Gleichzeitig fehlt eine eindeutige Verbindung zwischen:

integriertem Commit
technischem Release
produktivem Deployment
Browserabnahmeprotokoll

Diese Verbindung wird zwischen ARCH-2026-005, ARCH-2026-004 und ARCH-2026-006 aufgeteilt.

Zielprinzip¶

Pull Request prüfen
-> Änderung mergen
-> tatsächlichen main-Commit erneut vollständig verifizieren
-> IntegrationVerificationRecord erzeugen
-> bei Erfolg Releasekandidat nach ARCH-2026-004 erzeugen
-> Deployment und Produktionsnachweis nach ARCH-2026-006

Die Post-Merge-Verifikation prüft den real vorliegenden integrierten Stand und nicht nur die beabsichtigte Änderung.

Geltungsbereich¶

ARCH-2026-005 umfasst:

automatische Post-Merge-Verifikation auf main
bewussten manuellen Wiederholungslauf
Verifikation eines eindeutig angegebenen integrierten Commits
sauberen Checkout ohne lokale Nebenwirkungen
Verwendung des kanonischen Contract Checks aus ARCH-2026-004
Prüfung von Governance- und Proposal-Konsistenz
Prüfung führender Dokumente und Querverweise
Prüfung maschinenlesbarer Verträge und Konfigurationen
Prüfung von Implementierung, Regressionen und Dokumentationsbuild
Erzeugung eines IntegrationVerificationRecord
Verknüpfung des Nachweises mit Proposal, Commit und Releasekandidat
klare Gate-Regel vor Status integrated und Releasebereitstellung

Nicht Teil dieses Proposals:

Definition der Fach- oder UI-Architektur aus ARCH-2026-001 und ARCH-2026-002
ADR-Metadaten und Ablösungslogik aus ARCH-2026-003
Pinning, Buildartefakte, Releaseaktivierung oder Rollback aus ARCH-2026-004
produktiver Deploymentnachweis und Drift-Erkennung aus ARCH-2026-006
automatische fachliche Entscheidung über ein Proposal
automatisches Setzen des Proposal-Status integrated
allgemeine GitHub-Actions- oder CI-Anleitungen für andere Projekte

Abgrenzung zu ARCH-2026-001¶

ARCH-2026-001 definiert die Zielarchitektur für Frontend-State, Render-Orchestrierung und View-Eigentümerschaft.

ARCH-2026-005 definiert keine Renderer- oder State-Regeln. Es prüft nach deren späterer Integration lediglich, ob der tatsächliche Gesamtstand alle zugehörigen Verträge, Tests und Dokumentationen erfüllt.

Abgrenzung zu ARCH-2026-002¶

ARCH-2026-002 definiert ReportSource, ReportData, reporttypspezifische ViewModels und Renderergrenzen.

ARCH-2026-005 prüft nur den vollständig integrierten Stand dieser Pipeline. Es erzeugt keine Reportdaten und führt keine Reportinglogik ein.

Abgrenzung zu ARCH-2026-003¶

ARCH-2026-003 definiert:

Rolle von ADRs
historische Entscheidungsnachweise
Proposal- und ADR-Abgrenzung
Bedeutung von current, partial und historical

ARCH-2026-005 definiert die technische Evidenz für einen integrierten Repository-Stand.

Wesentliche Grenze:

ARCH-2026-003 erklärt, was integrated im Governanceprozess bedeutet.
ARCH-2026-005 liefert den technischen Post-Merge-Nachweis.

Eine erfolgreiche technische Verifikation ersetzt weiterhin nicht die dokumentierte fachliche Entscheidung oder das Review.

Abgrenzung zu ARCH-2026-004¶

ARCH-2026-004 verantwortet:

fixierte Prüf- und Runtime-Baseline
kanonischen Contract Check
reproduzierbare App- und Docs-Artefakte
Release-ID
Aktivierungs- und Rollbackmechanismus

ARCH-2026-005 verwendet diese Baseline, definiert sie aber nicht.

Wesentliche Grenze:

ARCH-2026-004 beantwortet:
  Wie wird reproduzierbar geprüft und ein Release erzeugt?

ARCH-2026-005 beantwortet:
  Wurde exakt der tatsächlich integrierte Repository-Commit
  vollständig und nachvollziehbar geprüft?

Abgrenzung zu ARCH-2026-006¶

ARCH-2026-006 beginnt erst nach erfolgreicher Integration und Releaseerzeugung.

ARCH-2026-005
  verifiziert den Repository- und Integrationsstand

ARCH-2026-004
  erzeugt daraus einen identifizierbaren Release

ARCH-2026-006
  weist nach, welcher Release in welcher Umgebung tatsächlich aktiv ist
  und erkennt Abweichungen zwischen erwartetem und laufendem Stand

ARCH-2026-005 führt keine produktiven Endpunktprüfungen als Zustandswahrheit und keine Environment-Drift-Erkennung ein.

Post-Merge-Trigger¶

Empfohlene Zielrichtung:

push auf main
  automatische vollständige Verifikation des neuen main-Commits

workflow_dispatch
  bewusster Wiederholungslauf für einen angegebenen Commit

Releasevorbereitung
  explizite Prüfung, dass für den Release-Commit ein erfolgreicher
  IntegrationVerificationRecord vorliegt

Ein zeitgesteuerter Lauf kann später ergänzt werden, ist für den ersten privaten MVP jedoch nicht erforderlich.

Sauberer Verifikationskontext¶

Die Verifikation muss in einem frischen Checkout erfolgen:

keine uncommitted files
keine lokal synchronisierten, aber nicht versionierten Konfigurationskopien
keine Abhängigkeit von Server-Working-Tree oder produktiven Volumes
keine Wiederverwendung eines teilweise gebauten Releaseverzeichnisses

Der zu prüfende vollständige Git-Commit ist explizit zu protokollieren.

Kanonischer Prüfumfang¶

ARCH-2026-005 definiert keine parallele Liste ausführbarer Testbefehle.

Es gilt:

Der kanonische Contract Check wird durch ARCH-2026-004 festgelegt.
ARCH-2026-005 führt genau diesen Check für den integrierten Commit aus.

Zusätzlich sind integrationsspezifische Meta-Prüfungen erforderlich:

Commit liegt auf main oder einem ausdrücklich zulässigen Integrationsref
Repository ist sauber
Proposal- und Governance-Metadaten sind zulässig
keine Datei behauptet integrated ohne dokumentierten Integrationscommit
betroffene Zieldokumente sind vorhanden
Querverweise zeigen auf existierende Dateien
Manifest-, Schema-, Methoden- und Engineversionen sind synchron
kein erwartetes Zielartefakt fehlt
keine offene Konfliktmarkierung ist vorhanden
Dokumentationsnavigation enthält alle neu integrierten Dokumente

Prüfprofile¶

Die sichere Standardregel lautet:

Default = vollständige Verifikation

Eine spätere Optimierung darf unterschiedliche Profile definieren, beispielsweise:

full
  Code, Verträge, Konfiguration, Dokumentation und Browserpfad

documentation
  Governance, Links, MkDocs und relevante Konsistenzprüfungen

release-metadata
  nur technische Metadaten ohne Produktänderung

Voraussetzungen für reduzierte Profile:

Änderungsklassifizierung ist deterministisch und maschinell prüfbar
nicht zuordenbare Änderungen verwenden full
kritische Pfade verwenden immer full
Profile sind Teil des versionierten Prüfkatalogs

Die erste Umsetzung soll aus Einfachheits- und Sicherheitsgründen mit full beginnen.

IntegrationVerificationRecord¶

Empfohlene Mindeststruktur:

record_schema_version
verification_id
git_commit
base_commit optional
repository_ref
trigger_kind
started_at
completed_at
runtime_baseline_version
check_suite_version
check_profile
check_results
artifact_references
proposal_references
release_candidate_id optional
overall_status
failure_summary optional

Zulässige Ergebniswerte:

passed
failed
cancelled

Der Record ist technische Prüfevidenz und kein fachlicher Datenvertrag. Er gehört nicht in PropertyInput, AnalysisResult oder PropertyRecord.

Ablage der Prüfevidenz¶

Die Evidenz darf nicht zu einem Commit-Zyklus führen, bei dem jeder Nachweis den geprüften Commit selbst verändert.

Empfohlene Richtung:

GitHub Actions Run als primärer unveränderbarer Ausführungsnachweis
maschinenlesbarer Record als Workflow-Artefakt
Run-ID oder Record-ID im Proposal, Changelog oder Releaseprozess referenzieren

Eine zusätzliche dauerhafte, repository-externe Ablage kann später mit ARCH-2026-006 abgestimmt werden.

Bedeutung für Proposal-Status integrated¶

Eine erfolgreiche Post-Merge-Verifikation ist notwendig, aber nicht ausreichend.

Vor integrated müssen weiterhin erfüllt sein:

Proposal fachlich oder technisch angenommen
alle Zieldokumente aktualisiert
Schemas, Konfiguration, Code und Tests synchron, soweit betroffen
Legacy- und Migrationsfolgen behandelt
Versionierung korrekt
Review abgeschlossen
IntegrationVerificationRecord passed
Browserabnahme erfolgt, soweit UI betroffen und produktive Abnahme erforderlich
Integrationscommit dokumentiert

ARCH-2026-005 setzt den Status nicht automatisch. Die Statusänderung bleibt eine bewusste Governancehandlung.

Wiederholung und Idempotenz¶

Für denselben Commit, dieselbe Runtime-Baseline und dieselbe Check-Suite soll ein Wiederholungslauf denselben fachlichen Prüfausgang erzeugen.

Unterschiede durch Zeit, bewegliche Images oder Hostabhängigkeiten sind über ARCH-2026-004 zu minimieren und im Record sichtbar zu machen.

Ein späterer erfolgreicher Wiederholungslauf ersetzt einen früheren Fehler nicht still. Beide Runs bleiben nachvollziehbar.

Fehler- und Abbruchregeln¶

fehlgeschlagene Pflichtprüfung -> overall_status failed
fehlende Runtime-Baseline -> Abbruch
nicht sauberer Checkout -> Abbruch
unbekannter Prüfprofilwert -> Abbruch
nicht auflösbarer Commit -> Abbruch
fehlender Pflichtnachweis -> kein Status integrated

Ein Fehler löst kein automatisches Deployment und keine automatische Rücknahme bereits gemergter Änderungen aus.

Auswirkungen auf Architektur, Roadmap und Spezifikation¶

Architektur:

Post-Merge-Verifikation wird eigenständiges Integrations-Gate.
Prüfung, Releaseerzeugung und Deploymentnachweis bleiben getrennte Schritte.

Roadmap:

Stabilisierung des Integrationsprozesses
keine neue Produktphase
Voraussetzung für belastbare Integration größerer Architektur-Proposals

Spezifikation:

Validierungsstrategie und Governance werden nach Annahme präzisiert.
Keine fachliche Modelländerung.

Auswirkungen auf Formeln, KPIs und Datenverträge¶

keine Änderung
keine Modellversion
keine Engineversion
keine Schemaänderung der Fachverträge

Für den IntegrationVerificationRecord ist eine unabhängige technische Record-Version vorzusehen.

Auswirkungen auf UI, Reporting und Speicherung¶

keine direkte UI-Änderung
keine Änderung fachlicher Reports
keine Änderung gespeicherter PropertyRecords
keine neue Browserpersistenz

Sichtbare Änderungen werden weiterhin über die jeweiligen Fach- oder Architektur-Proposals spezifiziert und geprüft.

Auswirkungen auf Tests¶

Erforderlich:

Post-Merge-Workflow läuft auf main
manueller Wiederholungslauf für expliziten Commit
sauberer Checkout wird erzwungen
kanonischer Contract Check aus ARCH-2026-004 wird verwendet
IntegrationVerificationRecord wird immer erzeugt oder Fehler eindeutig dokumentiert
fehlgeschlagener Check erzeugt keinen passed-Record
Run und Record nennen denselben vollständigen Commit
Querverweise und Proposal-Metadaten werden geprüft
Dokumentationsbuild läuft gegen integrierten Stand

Referenzfälle:

normaler erfolgreicher Merge
Merge mit manuell gelöstem Konflikt
zwei Proposals ändern denselben Index
veraltete Dokumentationsaussage trotz interner Textkonsistenz
fehlende Navigationsreferenz
Schema- oder Manifestdrift
manueller Wiederholungslauf desselben Commits

Legacy- und Migrationsfolgen¶

keine Datenmigration
keine Änderung bestehender PropertyRecords
bestehende Pull-Request-CI bleibt bis zur kontrollierten Umstellung aktiv
bestehende Deploymentprüfung bleibt bis ARCH-2026-004 integriert ist bestehen
ältere integrierte Commits besitzen rückwirkend nicht zwingend einen Record
neue Pflicht gilt ab einem dokumentierten Einführungscommit

Eine rückwirkende Rekonstruktion alter Prüfevidenz darf nicht vorgetäuscht werden.

Risiken¶

zusätzliche CI-Laufzeit
Doppelprüfung unmittelbar nach einem erfolgreichen Pull Request
falsches Sicherheitsgefühl trotz unvollständiger Meta-Prüfung
zu komplexe Change-Klassifizierung
instabile externe Runner oder Browserumgebung
Evidenzartefakte werden zu früh gelöscht
Proposal wird trotz fehlender fachlicher Entscheidung technisch als integriert verstanden

Gegenmaßnahmen:

kanonischen Check wiederverwenden statt duplizieren
zunächst immer full ausführen
technischen Record klar von Governanceentscheidung trennen
Retention und Referenzierung festlegen
ARCH-2026-004 vor vollständiger Aktivierung berücksichtigen

Sicherungs- und Rückfallstrategie¶

Vor Integration:

aktuellen Workflowstand sichern
aktuelle erfolgreiche PR- und Deploymentläufe dokumentieren
bestehende Checkliste und Laufzeiten erfassen
main-Commit vor Workflowänderung festhalten
Workflowänderung zunächst auf Testbranch prüfen
keine Branch-Protection-Pflicht aktivieren, bevor der neue Lauf stabil ist

Rollback:

Post-Merge-Trigger deaktivieren
vorherigen Workflow wiederherstellen
bestehende Pull-Request-Prüfung unverändert weiterverwenden
keine produktiven Daten betroffen

Empfohlene Umsetzungsstruktur nach vollständiger Annahme¶

Phase 0
  kanonischen Check und Runtime-Baseline aus ARCH-2026-004 festlegen

Phase 1
  integrationsspezifische Meta-Prüfungen definieren
  IntegrationVerificationRecord spezifizieren

Phase 2
  workflow_dispatch für expliziten Commit einführen
  auf Testbranch und aktuellem main-Commit erproben

Phase 3
  push-main-Trigger aktivieren
  Evidenzartefakt und Retention prüfen

Phase 4
  Governance und Proposal-Integration mit Record-Referenz verbinden
  Dokumentation und Changelog aktualisieren

Weitere offene Einzelentscheidungen¶

2. Trigger
   push main, workflow_run, workflow_dispatch oder Kombination?

3. Record-Ablage
   nur GitHub-Artefakt oder zusätzliche dauerhafte Ablage?

4. Record-Schema
   welche Pflichtfelder, IDs und Versionsregeln?

5. Prüfprofile
   zunächst ausschließlich full oder direkt dokumentationsspezifische Profile?

6. Status-Gate
   wie wird ein passed-Record im Proposal und Changelog referenziert?

7. Retention
   wie lange bleiben Logs und Records verfügbar?

8. Fehlerbehandlung
   welche Fehler blockieren Releasebereitstellung und welche nur Integration?

Entscheidungsmehrwert¶

exakt der integrierte main-Commit wird geprüft
Merge- und Konfliktfolgen werden sichtbar
kein dritter paralleler Prüfkatalog
reproduzierbare Wiederholung möglich
Proposal-Status integrated erhält technische Evidenz
klarer Übergang von Integration zu Release und Deployment
veraltete, aber intern konsistente Statusaussagen werden besser erkennbar

Prüfergebnis¶

Die ursprüngliche Empfehlung für einen Wiederholungslauf ist bestätigt, aber zu eng.

Der aktuelle Stand benötigt nicht nur eine optional erneut ausführbare Prüfkette, sondern ein formales Post-Merge-Gate für den tatsächlichen integrierten Commit.

Die technische Prüfung muss dabei strikt getrennt bleiben von:

fachlicher Entscheidung
Releaseerzeugung
produktiver Aktivierung
Browserabnahme
Proposal-Statusänderung

Entscheidung¶

Teilentscheidung 1 am 2026-07-07 bestätigt:

Variante B – formale Post-Merge-Verifikation des tatsächlich integrierten
Repository-Commits mit kanonischem Contract Check und versioniertem
IntegrationVerificationRecord.

Eine erfolgreiche Verifikation ist notwendige Evidenz für integrated,
setzt den Proposal-Status jedoch nicht automatisch und ersetzt weder
Review noch produktive Abnahme.

Gesamtentscheidung: offen
Proposal-Status: under_review

Zieldokumente bei späterer Annahme¶

.github/workflows/contract-check.yml
gegebenenfalls eigener post-merge-workflow
scripts/check-contract.sh aus ARCH-2026-004
neues Integrations-Metaprüfskript
technische Definition des IntegrationVerificationRecord
docs/governance/change-control.md
docs/governance/documentation-system.md
docs/specification/data-quality-and-validation/validation.md
docs/operations/deployment.md
docs/operations/browser-acceptance.md
docs/changes/changelog.md
docs/roadmap/current-status.md
AGENTS.md

Integrationscommit¶

offen