breakpilot-core/control-pipeline/INSTRUCTION-session-handover.md

# Session-Instruktionen: Pipeline-Qualitaet + Gesetze

**Datum:** 2026-05-03
**Fuer:** Naechste Claude-Session
**Repo:** breakpilot-core (~/Projekte/breakpilot-core)

---

## ZUSAMMENFASSUNG: WO STEHEN WIR

### Was fertig ist (Bloecke A-D5+)

| Block | Was | Status |
|-------|-----|--------|
| Pass 0b | 151.675 atomare Controls, dedupliziert, mit Dependencies | ✅ |
| Block A | v1 Tag, Healthcheck, Textkorrektur, Dependencies (15.291) | ✅ |
| Block B | Review-Verify (67k Paare, 43.527 DUPLIKAT via Haiku) | ✅ |
| Block C | Adversarial Tests (30), Regression Harness (387 Tests) | ✅ |
| Block D | Strukturelles Chunking End-to-End (D1-D5) | ✅ |
| **D5+** | **NIST/BSI/ENISA PDF-Qualitaet gefixt** | ✅ |

### D5+ Details (Session 02-03.05.2026)

**Problem geloest:** 4 NIST-PDFs hatten 0 Chunks (D5-Script hatte delete-before-upload, Upload scheiterte).

**Was gemacht wurde:**
- `_normalize_pdf_text()` in embedding-service: Repariert gebrochene Sektionsnummern ("1 . 1"→"1.1", "AC - 1"→"AC-1"), Ligaturen, Soft Hyphens
- `_LEGAL_SECTION_RE` erweitert: NIST CSF 2.0, NIST Enhancements, OWASP Top 10
- `_SECTION_NUMBER_RE` erweitert: NIST Control-IDs (AC-1), numbered sections (3.1), OWASP (A01:2021)
- `_SINGLE_NUM_ALLCAPS_RE` (case-sensitive): "1. INTRODUCTION" fuer ENISA/BSI-Docs
- pdfplumber Toleranzen: x_tolerance=3, y_tolerance=4 (war 2/3)
- **Lokale PDF-Extraktion Workaround:** Embedding-Service-Container crasht bei PDFs >5 MB (OOM). Fix: pdfplumber lokal auf Mac Mini, dann .txt hochladen.
- `reingest_d5.py` Safety Fix: Upload → Verify → Delete old (mit `must_not` Filter)
- `reingest_nist.py` (NEU): Sicheres Re-Ingest-Script
- `reupload_legal_strategy.py` (NEU): Re-Upload mit chunk_strategy="legal"
- `extract_and_upload_nist.py` (NEU): Lokale PDF-Extraktion fuer grosse Dateien
- `scripts/qdrant-snapshot.sh` (NEU): Backup aller Qdrant-Collections
- 2 korrupte PDFs (nistir_8259a, nist_ai_rmf) waren 263-Byte XML-Fehler in MinIO → Neu von nist.gov heruntergeladen und ingestiert
- **99 Embedding-Service-Tests gruen** (28 neue NIST-Tests)
- **Qdrant-Snapshot erstellt:** 14 Collections, ~1 GB unter `backups/qdrant/`

### Aktuelle Qualitaet (Stand 03.05.2026)

| Dokumenttyp | Section-Rate | Status |
|-------------|-------------|--------|
| DE Gesetze (TXT) | **79-100%** | ✅ Exzellent |
| HTML (EUR-Lex + gesetze-im-internet) | **40-99%** | ✅ Gut |
| PDF (EDPB/DSK Leitlinien) | **60-98%** | ✅ Gut |
| PDF (NIST SP 800-53/82/160/207) | **27-45%** | ✅ Gut (war 0%) |
| PDF (NIST CSF, 800-30, ENISA) | **5-13%** | 🟡 Akzeptabel |
| PDF (CISA Secure by Design) | **0%** | ⚪ Prose-Dokument, erwartet |
| TXT (OWASP) | **0%** | ❌ OFFEN |
| Legal Templates (JSON/MD) | **0%** | ⚪ Erwartet |

**NIST Section-Rate-Verbesserungen (diese Session):**
- NIST SP 800-53: 0% → **45%** (2.847 Chunks)
- NIST SP 800-207: 0% → **43%** (207 Chunks)
- NIST SP 800-160: 0% → **36%** (977 Chunks)
- NIST SP 800-82: 0% → **27%** (2.301 Chunks)
- ENISA ICS/SCADA: 0% → **22%** (235 Chunks)
- ENISA Supply Chain Good Practices: 2% → **12%** (159 Chunks)
- ENISA Supply Chain Security: 0% → **5%** (184 Chunks)

**Qualitaetsreport (500 Controls Stichprobe, Stand 02.05.):**
- 13% vollstaendig korrekt
- 41% Article-nicht-im-Source-Text (Controls aus alten kaputten Chunks)
- 7% kein Article in Citation
- 39% sonstige Matching-Issues

---

## WAS ALS NAECHSTES ZU TUN IST (PRIORISIERT)

### PRIO 1: Citation-Backfill (D6 — Block D Abschluss)

**Problem:** 41% der Controls haben falsche source_citation.article weil sie aus alten (kaputten) Chunks generiert wurden. Die Chunks sind jetzt sauber (mit Section-Metadaten), aber die Controls tragen noch die alten Citations.

**Loesung:**
1. Fuer jeden Control: `source_citation.source` → regulation_code ermitteln
2. In Qdrant nach Chunks mit diesem regulation_code + passender section suchen
3. Wenn Match: `source_citation.article` und `source_citation.paragraph` aktualisieren
4. Wenn kein Match: als "needs_regeneration" markieren

**Basis-Script existiert:** `control-pipeline/scripts/quality_report.py`
Muss erweitert werden um UPDATE statt nur Report.

**Bestehender Backfill-Service:** `control-pipeline/services/citation_backfill.py`
Hat 3-Tier-Matching: Hash → Regex → LLM. Muss fuer neues Chunk-Format angepasst werden.

**Aufwand:** ~0.5 Tag

### PRIO 2: Fehlende Gesetze ingestieren (Block E)

**Neue Gesetze (noch nicht im RAG):**
- **BEG IV** (Viertes Buerokratieentlastungsgesetz, BGBl. 2024 I Nr. 323)
- ArbZG, MuSchG, NachwG, MiLoG, GmbHG, AktG, InsO
- Gesetz fuer faire Verbrauchervertraege
- CSRD, EU Taxonomy, CSDDD, eIDAS 2.0
- CH: OR, DSV, ISG, ArG
- AT: ArbVG, AngG, AZG, GmbHG-AT, NISG

**Veraltete Gesetze (aktualisieren):**
- TMG → ersetzen durch TDDDG (TMG aufgehoben seit 2024)
- GwG aktualisieren (Aenderungen 2024)
- HGB aktualisieren (MoPeG 2024)

**Quellen:**
- gesetze-im-internet.de (DE-Gesetze, HTML, charset beachten!)
- eur-lex.europa.eu (EU-Recht, HTML via CELEX-Nummer)
- fedlex.admin.ch (CH-Recht)
- ris.bka.gv.at (AT-Recht)

**Lizenzregeln (KRITISCH — immer pruefen!):**
- Rule 1 (Gesetze, Urteile): Volltext erlaubt
- Rule 2 (CC-BY): Mit Zitation erlaubt
- Rule 3 (Behoerden-Presse, proprietaer): NUR eigene Formulierungen
- VERBOTEN: ISO, beck-online, juris, DIN

### PRIO 3: Frontend 500-Fehler untersuchen

macmini:3007/sdk/control-library zeigt noch 500-Fehler bei API-Aufrufen.
Der `requirements.map` TypeError ist gefixt (commit fe6764d im compliance-repo).
Die 500er koennten vom Compliance-Backend (Port 8002) kommen — separat pruefen.

---

## GESAMTPLAN (Bloecke A-G)

### ✅ ERLEDIGT
- **Block A:** v1 Abschluss (Healthcheck, Dependencies, v1 Tag)
- **Block B:** Review-Verify (67k Paare)
- **Block C:** Tests (Adversarial + Regression)
- **Block D1-D5:** Strukturelles Chunking End-to-End
- **Block D5+:** NIST/ENISA/BSI PDF-Qualitaet (Text-Normalisierung, Section-Detection, Re-Ingestion)

### 🔥 NAECHSTER SCHRITT
- **Block D6:** Citation-Backfill — Controls auf neue Chunks umhaengen (Prio 1)

### 📋 AUSSTEHEND

**Block E: Gesetze aktualisieren + neue ingestieren**
- E1: Veraltete Quellen aktualisieren (TMG→TDDDG, GwG, HGB)
- E2: Fehlende DE-Gesetze (ArbZG, MuSchG, NachwG, MiLoG, etc.)
- E3: Fehlende EU-Regulierung (CSRD, EU Taxonomy, CSDDD, eIDAS 2.0)
- E4: Fehlende Standards lizenzgerecht (GoBD, BAIT/VAIT, PCI DSS Rule 3)
- E5: Urteils-Control-Packs (Google Fonts, CNIL, Planet49, Schrems II — 12 Packs)
- E6: CH + AT Gesetze (OR, DSV, ISG, ArG, ArbVG, AngG, etc.)
- E7: Lizenzpruefung bei JEDER neuen Quelle

**Block F: Hardcoded Knowledge Migration (bis Juli 2026)**
- F1: legal_basis_validator.py → Control Library
- F2: 5 weitere Dateien migrieren (service_registry, mandatory_content_checker, etc.)
- F3: Keyword-Synonyme durch LLM ersetzen

**Block G-pre: Master Control Konsolidierung**
- G-pre1: Object-Normalisierung (128k → 15-25k Gruppen)
- G-pre2: Control-Ketten als Master Controls
- G-pre3: Master Control API

**Block G: Compliance Execution Layer (langfristig)**
- G1: Decision Trace
- G2: Compliance Git
- G3: Full Decision Memory
- G4: Pre-Deployment Enforcement

---

## KRITISCHE DATEIEN

### Aenderungen Session 03.05.2026 (breakpilot-core)

| Datei | Was |
|-------|-----|
| `embedding-service/main.py` | `_normalize_pdf_text()`, `_SECTION_NUMBER_RE` NIST-Patterns, `_SINGLE_NUM_ALLCAPS_RE`, pdfplumber Toleranzen |
| `embedding-service/test_nist_normalization.py` | 41 neue Tests (Normalisierung, Section-Detection, Metadata) |
| `control-pipeline/scripts/reingest_nist.py` | Sicheres Re-Ingest (upload-before-delete) |
| `control-pipeline/scripts/reingest_d5.py` | Safety Fix: `_delete_old_chunks_safe()` mit must_not Filter |
| `control-pipeline/scripts/reupload_legal_strategy.py` | Re-Upload mit chunk_strategy="legal" |
| `control-pipeline/scripts/extract_and_upload_nist.py` | Lokale PDF-Extraktion Workaround (Container-OOM) |
| `scripts/qdrant-snapshot.sh` | Qdrant Backup aller Collections |

### Wichtig: Embedding-Service Container-Limit

Der Embedding-Service-Container (8 GB RAM) crasht bei PDFs >5 MB. Workaround:
1. PDF lokal auf Mac Mini extrahieren (`pdfplumber` ist dort installiert)
2. `_normalize_pdf_text()` anwenden
3. Als .txt mit `chunk_strategy="legal"` hochladen

Wenn das Container-Limit erhoehrt werden soll: `docker-compose.yml` Zeile ~445:
```yaml
deploy:
  resources:
    limits:
      memory: 12G  # war 8G
```

---

## DB-STAND

### Qdrant (Mac Mini, Port 6333)

| Collection | Chunks | Section-Rate | Aenderung |
|-----------|--------|-------------|-----------|
| bp_compliance_ce | ~23.600 | ~50% | NIST/ENISA re-ingestiert |
| bp_compliance_gesetze | ~32.000 | ~86% | Unveraendert |
| bp_compliance_datenschutz | ~13.000 | ~40% | NIST 800-53/207 re-ingestiert |
| bp_dsfa_corpus | ~8.200 | ~60% | Unveraendert |
| bp_legal_templates | ~1.460 | ~7% | Unveraendert |
| **Gesamt** | **~78.000** | **~65%** | Verbessert (war 62%) |

**Qdrant-Backup:** `backups/qdrant/` — 14 Collections, ~1 GB (Stand 03.05.2026 08:21)

### PostgreSQL (Mac Mini, Port 5432)

| Tabelle | Anzahl | Schema |
|---------|--------|--------|
| canonical_controls | ~291.000 | compliance |
| obligation_candidates | ~234.000 | compliance |
| control_dependencies | ~15.300 | compliance |

### MinIO (Hetzner, nbg1.your-objectstorage.com)

Alle Originaldokumente sind sicher in MinIO, Bucket: `breakpilot-rag`.
**Achtung:** 2 Dateien waren korrupt (263-Byte XML statt PDF):
- `nistir_8259a.pdf` — Neu heruntergeladen von nist.gov, re-ingestiert ✅
- `nist_ai_rmf.pdf` — Neu heruntergeladen von nist.gov, re-ingestiert ✅
Die neuen PDFs wurden nur in Qdrant ingestiert, NICHT in MinIO ersetzt.
Fuer MinIO-Update: Manuell via RAG-Service-Upload oder mc-CLI.

---

## TESTS AUSFUEHREN

```bash
# Embedding-Service (99 Tests inkl. 41 NIST-Tests)
cd embedding-service && python3 -m pytest test_chunking.py test_d4_bgb.py test_nist_normalization.py -v

# RAG-Service (32 Tests)
cd rag-service && PYTHONPATH=. python3 -m pytest tests/ -v

# Control-Pipeline (387 Tests)
PYTHONPATH=control-pipeline python3 -m pytest control-pipeline/tests/ -v

# Qualitaetsreport (500 Controls gegen Qdrant)
python3 control-pipeline/scripts/quality_report.py --db-host macmini --sample 500

# Qdrant-Snapshot erstellen
ssh macmini "cd ~/Projekte/breakpilot-core && bash scripts/qdrant-snapshot.sh"

# Qdrant-Snapshots auflisten
ssh macmini "cd ~/Projekte/breakpilot-core && bash scripts/qdrant-snapshot.sh --list"
```

---

## MEMORY-DATEIEN (LESEN!)

Alle unter `/Users/benjaminadmin/.claude/projects/-Users-benjaminadmin-Projekte-breakpilot-core/memory/`:
- `MEMORY.md` — Index aller Memories
- `project_structural_chunking.md` — Architektur-Entscheidung
- `project_control_pipeline_masterplan.md` — Gesamtplan A-G
- `feedback_batch_api_safety.md` — NIEMALS curl-Retry fuer Batch-Submits
- `feedback_legal_source_licensing.md` — Rule 1/2/3 Lizenzregeln
- `feedback_no_hardcoded_knowledge.md` — Kein hartkodiertes Rechtswissen
- `project_missing_legal_sources.md` — Fehlende Gesetze + 20 Urteile
- `project_test_strategy.md` — 4-Ebenen Teststrategie

## PLAN-DATEI

Vollstaendiger Masterplan: `/Users/benjaminadmin/.claude/plans/jazzy-snacking-creek.md`
Enthaelt Bloecke A-G mit allen Details.