docs(qa): add Control Quality Pipeline documentation

QA process, article types, match rates, preamble dedup rules,
and next steps documented in MkDocs under Entwicklung.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs-src/development/qa-control-quality.md

@@ -0,0 +1,133 @@
+# QA: Control Quality Pipeline
+
+## Übersicht
+
+Die Control Quality Pipeline prüft und verbessert die ~9.000 Canonical Controls der Compliance-Bibliothek. Sie nutzt **PDF-basierte Verifizierung** als Ground Truth — jeder Control-Originaltext wird direkt im Quelldokument (PDF) lokalisiert.
+
+## Architektur
+
+```
+Original-PDFs (~/rag-ingestion/pdfs/)
+        ↓
+  PDF Text-Extraktion (PyMuPDF)
+        ↓
+  Artikel-Index aufbauen
+  (Erwägungsgründe → Artikel → Anhänge)
+        ↓
+  source_original_text im PDF suchen
+  (Substring-Match, normalisiert)
+        ↓
+  Artikel/§/Section zuordnen + article_type setzen
+        ↓
+  Duplikat-Erkennung
+  (Preamble vs. Artikel: Artikel hat Vorrang)
+```
+
+## PDF-basierte Artikelzuordnung
+
+### Konzept
+
+Jeder Control hat ein Feld `source_original_text` — der Chunk-Text aus dem Quelldokument. Statt über Qdrant-Hashes wird dieser Text **direkt im Original-PDF gesucht**. Die Position im PDF bestimmt den Artikel.
+
+### Dokumenttypen
+
+| Typ | Struktur | Beispiel |
+|-----|----------|---------|
+| EU-Verordnung | Erwägungsgründe → Artikel → Anhänge | DSGVO, KI-VO, CRA |
+| Deutsches Gesetz | §-Paragraphen | BDSG, GewO, HGB |
+| NIST | Control Families (AC-1, SC-7) | SP 800-53, CSF 2.0 |
+| OWASP | Kategorien (A01:2021, V1.1) | Top 10, ASVS, MASVS |
+| EDPB/ENISA | Nummerierte Abschnitte | Leitlinien, Guidelines |
+
+### Article Types
+
+| article_type | Bedeutung | Beispiel |
+|---|---|---|
+| `article` | Gesetzesartikel / Paragraph | Artikel 25 DSGVO |
+| `preamble` | Erwägungsgrund | Erwägungsgrund (78) |
+| `annex` | Anhang | Anhang III |
+| `control` | NIST Control Family | AC-6, SA-7 |
+| `section` | Nummerierter Abschnitt | Section 2.1 |
+| `category` | OWASP Kategorie | A01:2021 |
+| `requirement` | OWASP Requirement | V1.1, MASVS-STORAGE-1 |
+
+### Ergebnisse (Stand 2026-03-20)
+
+| Metrik | Wert |
+|---|---|
+| Controls mit source_original_text | 7.943 |
+| Im PDF lokalisiert | **6.259 (79%)** |
+| Nicht gefunden (Sprachmismatch) | 1.651 |
+| Kein PDF vorhanden | 33 |
+| 100% Match-Rate | 19 Regulations (inkl. DSGVO, KI-VO, NIS2, NIST 800-53) |
+
+### Nicht-matchende Controls
+
+| Ursache | Controls | Erklärung |
+|---|---|---|
+| Blue Guide EN vs. DE PDF | ~562 | Controls aus englischem PDF, wir haben nur deutsches |
+| OWASP multilingual | ~632 | Controls aus PT/AR/ID/ES-Übersetzungen |
+| CRA Encoding | ~76 | PDF-Ligaturen/Sonderzeichen-Differenzen |
+| CISA Secure by Design | ~113 | Falsches PDF (ENISA statt CISA) |
+
+## Brute-Force-Suche
+
+Für Controls mit unbekannter Quelle: Text gegen **alle ~100 PDFs** suchen. Findet:
+- Korrekte Quelldokument-Zuordnung
+- Falsche Source-Zuordnungen (44 entdeckt)
+
+## Erwägungsgrund-Controls (Wettbewerbsvorteil)
+
+Controls aus Erwägungsgründen (`article_type = preamble`) sind **kein Nachteil**. Sie decken Aspekte ab, die reine Artikel-basierte Compliance-Tools übersehen.
+
+**Duplikat-Regel:** Wenn ein Preamble-Control das gleiche Thema wie ein Artikel-Control behandelt (Jaccard-Ähnlichkeit ≥ 0.40), hat der **Artikel Vorrang**. Das Preamble-Control wird als `duplicate` markiert.
+
+### Ergebnis der Preamble-Dedup
+
+| Metrik | Wert |
+|---|---|
+| Preamble-Controls geprüft | 838 |
+| Als Duplikat markiert | 190 |
+| **Unique Preamble-Controls** | **648** |
+
+## Pipeline-Versionen
+
+| Version | Controls | Mit Originaltext | Beschreibung |
+|---|---|---|---|
+| v1 | 5.332 | 4.137 (78%) | Automatisch + manuell erstellt |
+| v2 | 2.258 | 2.258 (100%) | Automatisch aus Chunks |
+| v3 | 1.570 | 1.548 (99%) | Neueste Pipeline |
+
+Die 1.195 v1-Controls **ohne** Originaltext sind manuell erstellt (`strategy=ungrouped`) und haben keine Chunk-Referenz.
+
+## DB-Status (Stand 2026-03-20)
+
+| release_state | Count |
+|---|---|
+| draft | 5.365 |
+| needs_review | 818 |
+| duplicate | 2.674 |
+| too_close | 303 |
+| **Aktiv** | **6.183** |
+
+## Scripts
+
+Alle QA-Scripts liegen in `scripts/qa/`:
+
+| Script | Beschreibung |
+|---|---|
+| `pdf_qa_all.py` | Haupt-QA: Controls gegen PDFs matchen |
+| `pdf_qa_inventory.py` | Inventar: Regulations, Controls, PDFs |
+| `apply_pdf_qa_results.py` | Ergebnisse in DB schreiben |
+| `preamble_dedup.py` | Preamble vs. Artikel Duplikat-Erkennung |
+| `qa_dedup_controls.py` | Jaccard-basierte Titel-Dedup |
+| `qa_normalize_sources.py` | Source-Namen normalisieren |
+| `db_status.py` | DB-Status-Übersicht |
+
+## Nächste Schritte
+
+1. **Blue Guide EN-PDF** beschaffen → +562 Controls matchen
+2. **CISA Secure by Design** echtes PDF finden → +113 Controls
+3. **Brute-Force Ergebnisse anwenden** — 44 falsche Source-Zuordnungen korrigieren
+4. **Frontend-Anzeige** — `article_type` im Control-Detail anzeigen
+5. **Continuous QA** — Bei neuen Controls automatisch PDF-Match prüfen

mkdocs.yml

@@ -114,3 +114,4 @@ nav:
     - Testing: development/testing.md
     - Dokumentation: development/documentation.md
     - CI/CD Pipeline: development/ci-cd-pipeline.md
+    - QA Control Quality: development/qa-control-quality.md