# SupplierPulse QAF-Vergleich

## Autonomer Umsetzungsplan in geschlossenen Qualitäts-Loops

**Zweck:** Dieses Dokument definiert, wie Claude Code beziehungsweise Aria den vorhandenen Stand vollständig autonom prüfen, verbessern und in eine belastbare V2 überführen soll.

## 1. Grundmodus

Der Agent arbeitet nicht als einmaliger Codegenerator, sondern als wiederholender Engineering-Loop.

Jeder Loop besteht zwingend aus:

1. Ist-Zustand lesen
2. relevante Quellen und Tests identifizieren
3. Hypothese formulieren
4. kleinsten fachlich vollständigen Änderungsschnitt planen
5. implementieren
6. statische Prüfungen ausführen
7. fokussierte Tests ausführen
8. vollständige Tests ausführen
9. Mutationsprobe durchführen
10. Gegenprobe durchführen
11. Golden Output vergleichen
12. Security und Performance prüfen
13. Dokumentation und Decision Log aktualisieren
14. offene Punkte neu priorisieren
15. nächsten Loop ohne Rückfrage starten

Der Agent darf nicht nach jedem Teilabschnitt auf Bestätigung warten.

## 2. Stop-Regeln

Der Agent stoppt nur bei einem echten externen Blocker:

- erforderlicher Zugriff oder Secret fehlt
- eine benötigte Quelldatei ist nicht verfügbar
- zwei verbindliche fachliche Anforderungen widersprechen sich und keine konservative, reversible Lösung ist möglich
- eine irreversible Datenmigration wäre ohne Backup oder Freigabe notwendig
- ein Security-Fund verhindert jede sichere Fortsetzung

Normale Architekturentscheidungen, Refactorings, Tests, Migrationen und UI-Entscheidungen sind keine Stop-Gründe.

Bei einem Blocker muss der Agent:

1. den genauen Blocker benennen
2. die bereits geprüften Alternativen dokumentieren
3. eine reversible Zwischenlösung anbieten
4. alle nicht blockierten Arbeiten fortsetzen

## 3. Unveränderliche Regeln

- Keine Original-QAF überschreiben.
- Keine Zahlen durch ein LLM berechnen.
- Keine verbindlichen Mappings durch ein LLM entscheiden.
- Kein stiller Datenverlust.
- Kein leerer Bereich ohne Zustandsangabe.
- Kein Diagramm, das eine nicht geschlossene Reconciliation kaschiert.
- Keine V2-Funktion ohne Test.
- Keine Entfernung einer V1-Funktion ohne Paritätsnachweis.
- Keine neue parallele Feldregistry.
- Keine harte UI-Berechnung.
- Kein großer Rewrite ohne dokumentierten Beweis, dass der bestehende Kern unrettbar ist.
- Keine Nutzung von Rot und Grün als alleinige Informationscodierung.
- Keine automatische Aktivierung einer KI-Zusammenfassung, solange `safeToSummarize` falsch ist.

## 4. Loop 0: Reproduzierbare Ausgangsbasis

### Ziel

Einen belegbaren, ausführbaren Ausgangszustand herstellen.

### Aufgaben

- Repository klonen oder öffnen.
- exakten Commit und Branch dokumentieren.
- Laufzeitversionen dokumentieren.
- Abhängigkeiten installieren.
- Environment prüfen.
- Datenbankmigrationen prüfen.
- Testsuite ausführen.
- Typecheck ausführen.
- Lint ausführen.
- Security Gates ausführen.
- aktuelle Seiten lokal rendern.
- HICE-Referenzvergleich reproduzieren.
- bestehende JSON-, XLSX-, DOCX-, Markdown- und PDF-Exporte erzeugen.
- Laufzeiten und Speichernutzung messen.

### Pflichtartefakte

- `audit/baseline/environment.md`
- `audit/baseline/test-results.json`
- `audit/baseline/build-log.txt`
- `audit/baseline/runtime-metrics.json`
- `audit/baseline/current-ui-screenshots/`
- `audit/baseline/current-exports/`
- `audit/decisions/ADR-000-baseline.md`

### Exit-Kriterien

- Build ist reproduzierbar oder alle Fehler sind klassifiziert.
- Tests sind ausführbar.
- HICE-Vergleich kann erzeugt werden.
- aktuelle Exporte sind archiviert.
- keine Änderung am Produktcode vor Abschluss dieses Loops.

## 5. Loop 1: Architektur- und Abhängigkeitsgraph

### Ziel

Den tatsächlichen Datenfluss vollständig verstehen.

### Aufgaben

- alle 190 Module gegen das Modul-Inventar verifizieren.
- Importgraph erzeugen.
- zyklische Abhängigkeiten prüfen.
- Server- und Client-Bundles prüfen.
- UI-Berechnungen suchen.
- Deep Imports suchen.
- direkte Zelladressen in UI suchen.
- Vergleichsmodus-Dispatches suchen.
- Capability-Gates katalogisieren.
- parallele Feldregistries katalogisieren.
- Persistenzpfade und Rehydration dokumentieren.
- Source Artifact Lifecycle dokumentieren.
- Exportpfade dokumentieren.

### Pflichtartefakte

- `audit/architecture/module-graph.json`
- `audit/architecture/data-flow.md`
- `audit/architecture/gates.md`
- `audit/architecture/registries.md`
- `audit/architecture/persistence.md`
- `audit/architecture/export-flow.md`
- `audit/architecture/hotspots.md`

### Exit-Kriterien

- Jeder fachliche Output ist bis zur Quelle zurückverfolgbar.
- Jeder Vergleichsmodus ist vollständig dokumentiert.
- alle hart codierten Gates sind katalogisiert.
- `actions.ts` Verantwortlichkeiten sind vollständig aufgeteilt dokumentiert.

## 6. Loop 2: Golden Corpus und Testhärtung

### Ziel

Reale QAF-Strukturen als CI-fähige, anonymisierte Regression abdecken.

### Aufgaben

- vorhandene operator-lokale Golden Files inventarisieren.
- PII und Lieferantendaten anonymisieren.
- Formeln und strukturelle Sonderfälle erhalten.
- Fixtures für QAF 8.8, QAF 9.1 Standard, QAF 9.1 Zeilen, G60 und Multi-QAF erstellen.
- Fehlerfälle erstellen:
  - verbundene Köpfe
  - leere Führungszellen
  - `#N/A`
  - verschobene Endzeilen
  - Formel zu Hardcode
  - Textdatum gegen Excel-Datum
  - fehlende Sachnummer
  - externe Links
  - Makros
  - ZIP-Bomb-Simulation
  - Split und Merge
  - Nullkosten-Zugang
  - gleiche Namen mit anderen Parametern
- Hash-Golden-Files erzeugen.
- alle Kern-Golden-Tests in reguläre CI übernehmen.
- flaky Wertstromtests reparieren oder isolieren.

### Exit-Kriterien

- keine Kernabnahme ist env-gated.
- jede unterstützte QAF-Familie besitzt mindestens eine reale anonymisierte Fixture.
- HICE-Ergebnis ist Golden Test.
- zwei identische Läufe erzeugen denselben Hash.

## 7. Loop 3: Vollständiger Differenzkatalog

### Ziel

Alle fachlichen Ebenen in einen stabilen, nachvollziehbaren Differenzkatalog überführen.

### Aufgaben

- `differences-from-material.ts` implementieren.
- `differences-from-manufacturing.ts` implementieren.
- bestehende Tooling- und Finding-Übersetzungen prüfen.
- stabile IDs für alle Bereiche sicherstellen.
- Split und Merge im Katalog abbilden.
- Formeländerungen getrennt von Wertänderungen führen.
- Nullkosten-Zugang in Strukturstatus und Kostenstatus zerlegen.
- `scope_removed` ergänzen.
- Traceability validieren.
- Evidence Panel gegen alle neuen Bereiche testen.

### Exit-Kriterien

- jede UI-Aussage referenziert Difference IDs.
- jede Difference ID besitzt mindestens eine Source Reference.
- Material, Fertigung und SBM sind vollständig enthalten.
- deterministische ID-Stabilität ist mutativ getestet.

## 8. Loop 4: Datenqualitäts- und Vergleichsklassifikation

### Ziel

Fehlende Regeln schließen und Vergleichstypen belastbar einordnen.

### Aufgaben

- D15 implementieren.
- D16 implementieren.
- D17 implementieren.
- R-03 implementieren.
- `comparison_type` mit Evidenz erzeugen.
- manuelle Deklaration als auditierbaren Fallback ermöglichen.
- Make-or-Buy-Abweichungen gesondert führen.
- Stammdatenkonflikte nicht als bloße Warnung verstecken.
- Dateiname nur als Signal, nicht als alleinige Wahrheit verwenden.

### Exit-Kriterien

- kein produktiver Vergleich bleibt ohne begründeten Vergleichstyp.
- unbestimmte Einordnung hat einen sichtbaren Reviewstatus.
- neue Regeln besitzen Positiv-, Negativ-, Mutations- und Gegenproben.

## 9. Loop 5: Source Artifact und Reparse

### Ziel

Originaldatei, Parserergebnis und vollständige Provenienz dauerhaft verbinden.

### Aufgaben

- Source Artifact Entity einführen.
- Storage Object Key speichern.
- SHA-256 speichern.
- Größe, MIME, Dateiname und Ingestzeit speichern.
- Workbook Safety Manifest speichern.
- Parser-, Adapter- und Registryversion speichern.
- immutable Source Policy einführen.
- Reparse aus Originaldatei implementieren.
- Rehydrate gegen Originalhash prüfen.
- Formeln und Blattnamen im V2-Detail verfügbar machen.
- Legacy-Datensätze migrieren oder sichtbar als eingeschränkt markieren.

### Exit-Kriterien

- jeder neue Vergleich kann aus der Originaldatei reproduziert werden.
- Formeln, Blattnamen und Zellzustände sind vollständig erreichbar.
- Originaldateien werden nie überschrieben.
- fehlende Legacyquelle wird explizit angezeigt.

## 10. Loop 6: Kanonischer JSON-Vertrag

### Ziel

Den UI-View-Model-Export durch einen vollständigen, serverseitigen Fachvertrag ersetzen.

### Aufgaben

- 24 Zielbereiche final beschließen.
- Konflikt zur aktuellen 19er-Konstante beheben.
- JSON Schema v1.0 implementieren.
- kanonische Entitäten, Facts, Relationships und Mapping Groups ausgeben.
- Differences, Reconciliation, Findings und Actions ausgeben.
- Capabilities und Coverage ausgeben.
- Unmapped Regions ausgeben.
- Manual Overrides mit Auditspur ausgeben.
- AI-ready getrennt ableiten.
- Presentation Package getrennt ableiten.
- UI-State optional abtrennen.
- Content Hash über volatile-freies Dokument berechnen.
- Schema-Validation als Build- und Laufzeitgate einführen.
- Export serverseitig erzeugen.
- bisherigen View-Model-Export als Legacyprofil befristet erhalten.

### Exit-Kriterien

- Export ist schema-valide.
- derselbe Input erzeugt denselben Content Hash.
- UI und Präsentation können aus demselben JSON lesen.
- kein Bereich wird still ausgelassen.
- `analysis_status` ist nur dann `complete`, wenn alle Pflichtbereiche einen zulässigen Zustand besitzen.

## 11. Loop 7: Comparison Set für ein bis sechs QAFs

### Ziel

Mehrere eigenständige QAFs als eine Vergleichsmenge modellieren.

### Aufgaben

- `comparison_set` persistieren.
- ein bis sechs Dokumente zulassen.
- Rollen und Reihenfolge speichern.
- Baseline-Auswahl speichern.
- Zeitreihenmodus implementieren.
- Baseline-Modus implementieren.
- Paar-Detail implementieren.
- Matrixmodus implementieren.
- vorhandenes `compareQafPair` als Pair Engine wiederverwenden.
- globalen Mapping Assembler implementieren.
- transitive Konflikte blockieren.
- Split, Merge, Rename, Remove und Re-Add über mehrere Stände abbilden.
- Baselinewechsel ohne Reparse ermöglichen.
- Pair Cache aus globalem Datenmodell ableiten.

### Exit-Kriterien

- Vergleich mit ein bis sechs Dateien.
- keine 15 unabhängig gepflegten Mappings bei sechs Dateien.
- Baselinewechsel ändert keine Extraktion.
- Zeitreihe und Paarvergleich stimmen rechnerisch überein.
- Konflikte sind sichtbar und reviewbar.

## 12. Loop 8: Capability-basierte Navigation

### Ziel

Die Oberfläche flexibel machen, ohne fachliche Bereiche zu verstecken.

### Aufgaben

- primäre Navigation an QAF-Terminologie ausrichten:
  - Überblick
  - Zusammenfassung
  - Material
  - Fertigungskosten
  - SBM, Vorrichtungen und Folgewerkzeuge
  - Logistik und Zoll
  - Rohstoffrisiken
  - Zusatzmodule
  - Qualität und Maßnahmen
  - Technischer Nachweis
- nur verfügbare Hauptreiter anzeigen.
- Abdeckung und Grenzen zentral anzeigen.
- technische Platzhalter aus der Primärnavigation entfernen.
- gleiche semantische IDs im Hintergrund erhalten.
- G60-, Multi-QAF- und Benchmark-spezifische Unteransichten registrieren.
- aktuelle 14-Sektionen-Langseite als Kompatibilitätsansicht erhalten.
- Deep Links auf semantische Bereiche einführen.

### Exit-Kriterien

- jede QAF ist navigierbar.
- kein leerer Hauptreiter überlädt die UI.
- nicht berechnete Bereiche sind in Coverage sichtbar.
- QAF-Nutzer erkennen ihre Excel-Terminologie wieder.

## 13. Loop 9: V2 Header und Aktionen

### Ziel

Den Kopfbereich auf Entscheidung und Kontext reduzieren.

### Aufgaben

- fachlichen Titel aus Daten erzeugen.
- technische Paarungswarnung als Status darstellen.
- QAF-Dokumente A bis F darstellen.
- drei sichtbare Hauptaktionen:
  - prüfen
  - exportieren
  - weitere Aktionen
- Datei ersetzen, Swap, Tags, Kalkulator, Wertstrom und Umbenennen in passende Menüs verschieben.
- Exportprofile bündeln.
- mobile Aktionendarstellung implementieren.
- Accessibility prüfen.

### Exit-Kriterien

- keine überladene Buttonreihe.
- Kontext, Status und Dateien sind auf einen Blick verständlich.
- alle bisherigen Aktionen bleiben erreichbar.

## 14. Loop 10: UI-Komponenten zerlegen

### Ziel

Große Detailkomponenten in registrierte, testbare Module zerlegen.

### Aufgaben

- `qaf-comparison-detail.tsx` zerlegen.
- `qaf-multi-qaf-detail.tsx` zerlegen.
- `actions.ts` schrittweise zerlegen.
- pro fachlichem Reiter einen View Adapter.
- keine Berechnung in Komponenten.
- gemeinsames Evidence Panel.
- gemeinsame Table Engine.
- gemeinsame Filter Engine.
- gemeinsame Empty State Komponenten.
- gemeinsame Comparison A-F Header.
- Virtualisierung für große Tabellen.
- URL-State für Filter und Auswahl.

### Exit-Kriterien

- keine zentrale Detailkomponente über vereinbartem Größenlimit.
- alle Ansichten lesen View Specs.
- keine fachliche Berechnung im Client.
- Tabellen bleiben bei großen QAFs interaktiv.

## 15. Loop 11: BMW Design System

### Ziel

Die V2 konsequent in das bereitgestellte BMW Group Design System überführen.

### Aufgaben

- Design Tokens zentralisieren.
- BMWGroupTN aus genehmigter App-Assetquelle laden.
- keine Schriftdateien als Ergebnisartefakt verteilen.
- Sentence Case.
- Eyebrows in All Caps.
- Ocean Teal als Anker.
- weiße Flächen.
- quadratische Ecken.
- Hairline Rules.
- keine dekorativen Schatten.
- keine vollflächigen farbigen Headerbars.
- Wordmark nach interner Freigabe oben rechts.
- Kostenrichtung nicht pauschal als RAG.
- Fokuszustände und Kontrast prüfen.
- Screenshots gegen Referenzkomponenten testen.

### Exit-Kriterien

- Token-Audit besteht.
- keine verbotenen Farben oder Fonts.
- keine unzulässigen Rundungen oder Schatten.
- visuelle Regression für Desktop, Tablet und Mobil.

## 16. Loop 12: Exporte und Präsentation

### Ziel

Alle Artefakte aus demselben kanonischen JSON erzeugen.

### Aufgaben

- Voll-JSON.
- AI-JSON.
- Run Manifest.
- XLSX.
- Markdown.
- DOCX, soweit weiterhin erforderlich.
- PDF-Druckprofil.
- Präsentationspaket.
- PNG nur als kontextbezogener Export.
- BMW-CI-Validierung.
- Quellverweise in Exporten.
- personenbezogene Felder maskieren.

### Exit-Kriterien

- keine Exportvariante rechnet selbst.
- alle Zahlen stimmen mit dem kanonischen JSON überein.
- Exportprofile sind versioniert.
- Presentation Package referenziert Difference IDs.

## 17. Loop 13: KI- und Aria-Schicht

### Ziel

KI als Erklärungsschicht sicher anbinden.

### Aufgaben

- ausschließlich AI-ready verwenden.
- `safeToSummarize` hart prüfen.
- Facts und Difference IDs mitgeben.
- keine Rohformeln ohne Kontext an Modell senden.
- PII filtern.
- Prompts versionieren.
- Antworten auf Quellen prüfen.
- Halluzinationstests.
- widersprüchliche Fragen beantworten, ohne neu zu rechnen.
- Export für weitere KI-Analysen bereitstellen.

### Exit-Kriterien

- KI kann keine Zahl erzeugen, die nicht als Fact vorliegt.
- jede quantitative Aussage referenziert Fakten.
- nicht berechnete Bereiche werden nicht als "keine Auffälligkeit" beschrieben.

## 18. Loop 14: Wertstromintegration

### Ziel

Fertigungsdaten kontrolliert in den Wertstrom übergeben.

### Aufgaben

- kanonische Prozessentitäten verwenden.
- QAF-Stand und Source Ref mitgeben.
- Zykluszeit, Personal, MSS, Ausschuss und Kosten übernehmen.
- Übernahmestatus dokumentieren.
- manuelle Änderungen im Wertstrom getrennt halten.
- Rückverfolgung zum QAF ermöglichen.
- keine automatische Rückschreibung in Original-QAF.
- mehrere QAF-Stände im Wertstrom vergleichbar machen.

### Exit-Kriterien

- Übernahme ist nachvollziehbar.
- Original-QAF bleibt unverändert.
- Wertstromänderung überschreibt keine QAF-Fakten.
- Vergleichsstand ist jederzeit sichtbar.

## 19. Loop 15: Migration und Abschaltung

### Ziel

V1 kontrolliert durch V2 ersetzen.

### Aufgaben

- Funktionsparitätsmatrix pflegen.
- Datenmigrationen versionieren.
- alte Vergleiche lesbar halten.
- Legacy JSON weiterhin importierbar machen.
- V1 und V2 im Shadow Mode vergleichen.
- Nutzerfeedback erfassen.
- Performance vergleichen.
- Security vergleichen.
- Abschaltkriterien definieren.
- Rollback ermöglichen.

### Exit-Kriterien

- alle Pflichtfunktionen paritätisch.
- Golden Outputs akzeptiert.
- kein kritischer Funktionsverlust.
- Rollback getestet.
- V1 erst danach read-only setzen und später entfernen.

## 20. Abschlussdefinition

Die Arbeit ist erst abgeschlossen, wenn:

- der deterministische Kern vollständig belegt ist
- ein bis sechs QAFs unterstützt werden
- der kanonische JSON-Vertrag aktiv ist
- jede Zahl rückverfolgbar ist
- die UI QAF-nah, flexibel und responsiv ist
- das BMW Design System eingehalten wird
- Exporte aus demselben Datenvertrag entstehen
- KI nur erklärt
- V1 ohne Funktionsverlust abgelöst werden kann