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

Session-Instruktionen: Pipeline-Qualitaet + Gesetze

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

---

ZUSAMMENFASSUNG: WO STEHEN WIR

Was fertig ist (Bloecke A-D)

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	✅

Block D Details (diese Session, 01-02.05.2026)

• D1: Embedding-Service extrahiert section/section_title/paragraph/paragraph_num/page
• D2: RAG-Service speichert diese Felder im Qdrant-Payload
• D3: Control Generator liest sie fuer source_citation (section > article > section_title Prioritaet)
• D4: BGB § 312k Validierung — kritischen Bug gefunden: Phase-3-Overlap zerstoerte den [§]-Prefix. Gefixt.
• D5: 430 von 436 Dokumenten re-ingestiert (alle 6 Compliance-Collections, ~70.000 Chunks)
• HTML-Fix: Stripping + Charset-Erkennung (ISO-8859-1) + Opening-Block-Tags → HTML: 0%→97.6% Section-Rate
• EUR-Lex: 20 EU-Verordnungen als HTML ersetzt (DSGVO: 0%→92%, AI Act: 33%→55%)
• pdfplumber: Als PDF-Backend, PDF_EXTRACTION_BACKEND=auto in docker-compose.yml
• NIST Regex: Nummerierte Abschnitte (1.1 Title), Control-IDs (AC-1, PO.1)
• Frontend-Bug: requirements.map TypeError in breakpilot-compliance gefixt

Aktuelle Qualitaet (Stand 02.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/BSI/ENISA)	0-10%	❌ OFFEN
TXT (OWASP)	0%	❌ OFFEN
Legal Templates (JSON/MD)	0%	⚪ Erwartet

Qualitaetsreport (500 Controls Stichprobe):

• 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: NIST/ENISA/BSI/OWASP Dokumente sauber ingestieren

Problem: pypdf UND pdfplumber brechen den Text mehrspaliger PDFs. Die Regex-Erweiterung fuer NIST-Nummern hat nicht geholfen weil die Nummern nach der PDF-Extraktion gebrochen sind ("1 . 1" statt "1.1", "AC - 1" statt "AC-1").

3 grosse NIST-PDFs fehlen in Qdrant (Chunks geloescht, Upload 500-Error):

• NIST_SP_800_53r5.pdf (6 MB) — 0 Chunks
• nist_sp_800_82r3.pdf (8.5 MB) — 0 Chunks
• nist_sp_800_160v1r1.pdf (8.2 MB) — 0 Chunks Die Originale sind sicher in MinIO.

Loesungsansaetze (in dieser Reihenfolge testen):

1. Text-Normalisierung nach PDF-Extraktion in embedding-service/main.py:

   def _normalize_pdf_text(text: str) -> str:
       """Fix broken spacing from pypdf/pdfplumber multi-column extraction."""
       # "1 . 1" → "1.1"
       text = re.sub(r'(\d+)\s+\.\s+(\d+)', r'\1.\2', text)
       # "AC - 1" → "AC-1"
       text = re.sub(r'([A-Z]{2})\s*-\s*(\d+)', r'\1-\2', text)
       # "GV . OC - 01" → "GV.OC-01"
       text = re.sub(r'([A-Z]{2})\s*\.\s*([A-Z]{2})\s*-\s*(\d+)', r'\1.\2-\3', text)
       return text
   

   Einfuegen in extract_pdf_pdfplumber() und extract_pdf_pypdf() vor dem Return.

2. Fehlende Regex-Patterns in _LEGAL_SECTION_RE:

   • GV.OC-01 (NIST CSF 2.0): [A-Z]{2}\.[A-Z]{2}-\d{2}
   • A01:2021 (OWASP Top 10): A\d{2}(?::\d{4})?
   • AC-1(1) (NIST Enhancements): [A-Z]{2}-\d+\(\d+\)

3. HTML-Download von NIST/ENISA-Websites (wie bei EUR-Lex):

   • NIST: https://csrc.nist.gov/pubs/sp/800/53/r5/upd1/final (HTML-Version)
   • ENISA: https://www.enisa.europa.eu/publications/ (HTML)
   • Eigenes Script analog zu control-pipeline/scripts/replace_eu_pdfs_with_html.py

4. D5-Script fixen: control-pipeline/scripts/reingest_d5.py Zeile ~170: KRITISCH: Aktuell: Delete-THEN-Upload. Wenn Upload fehlschlaegt, sind Chunks weg. Fix: Upload ZUERST in temp-Collection oder mit neuem document_id, DANN alte loeschen.

Betroffene Dokumente (105 PDFs mit <50% Section-Rate): Vollstaendige Liste in eu_pdfs_to_replace.json im Repo-Root.

PRIO 2: Citation-Backfill

Problem: 41% der Controls haben falsche source_citation.article weil sie aus alten (kaputten) Chunks generiert wurden. Die Chunks sind jetzt sauber, 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.

PRIO 3: Fehlende Gesetze ingestieren (Block E)

Neue Gesetze (noch nicht im RAG):

• BEG IV (Viertes Buerokratieentlastungsgesetz, BGBl. 2024 I Nr. 323) — verkuerzte Aufbewahrungsfristen
• 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):

• BGB: § 312k Kuendigungsbutton seit 01.07.2022 (existiert jetzt als TXT, sollte aktuell sein)
• TMG → ersetzen durch TDDDG
• 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 4: Frontend 500-Fehler untersuchen

macmini:3007/sdk/control-library zeigt noch 500-Fehler bei API-Aufrufen:

• /controls, /canonical, /control-instances, /findings, /vendors, /contracts

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 D: Strukturelles Chunking (D1-D5)

🔄 IN ARBEIT

• Block D5+: NIST/ENISA/BSI Dokumente (Prio 1 oben)
• Block E1: EU-Verordnungen als HTML (20 von ~50 erledigt)

📋 AUSSTEHEND

Block E: Gesetze aktualisieren + neue ingestieren

• E1: Veraltete Quellen aktualisieren (BGB, 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

Hauptaenderungen dieser Session (breakpilot-core)

Datei	Was
embedding-service/main.py	Overlap-Bug-Fix (Phase 3), pdfplumber-Backend, NIST-Regex
embedding-service/requirements.txt	pdfplumber>=0.11.0 hinzugefuegt
embedding-service/test_d4_bgb.py	18 BGB-Validierungstests
embedding-service/tests/fixtures/bgb_312_excerpt.txt	BGB §§ 312-312k Testfixture
rag-service/api/documents.py	D2 Payload-Felder + HTML-Erkennung + Encoding
rag-service/html_utils.py	HTML-Strip + Charset (NEU)
rag-service/embedding_client.py	ChunkResult Dataclass (D2)
rag-service/tests/	32 Tests (D2 + HTML)
control-pipeline/services/rag_client.py	page: Optional[int] in RAGSearchResult
control-pipeline/services/control_generator.py	section>article>section_title Prio + page
control-pipeline/services/decomposition_pass.py	Seitenzahl in _format_citation
control-pipeline/tests/test_d3_metadata.py	16 D3-Tests
control-pipeline/scripts/reingest_d5.py	Re-Ingestion Script (MUSS GEFIXT WERDEN: Upload-before-Delete)
control-pipeline/scripts/reingest_d5_config.py	Config + Helpers
control-pipeline/scripts/replace_eu_pdfs_with_html.py	EUR-Lex HTML Replacement
control-pipeline/scripts/quality_report.py	E2E Qualitaetstest (500 Controls)
docker-compose.yml	PDF_EXTRACTION_BACKEND=auto

Aenderungen in breakpilot-compliance

Datei	Was
backend-compliance/compliance/services/canonical_control_service.py	_ensure_list() fuer JSONB-Arrays
admin-compliance/app/sdk/control-library/components/ControlDetail.tsx	Array.isArray() Guard

---

DB-STAND

Qdrant (Mac Mini, Port 6333)

Collection	Chunks	Dokumente	Section-Rate
bp_compliance_ce	~23.600	~55	47%
bp_compliance_gesetze	~32.000	~98	86%
bp_compliance_datenschutz	~13.000	~107	36%
bp_dsfa_corpus	~320	~20	60%
bp_legal_templates	~1.460	~100	7%
Gesamt	~70.000	~430	62%

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. Pfad-Format: {data_type}/{bundesland}/{use_case}/{year}/{filename}

---

TESTS AUSFUEHREN

# Embedding-Service (58 Tests)
cd embedding-service && python3 -m pytest test_chunking.py test_d4_bgb.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

---

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.