From 4fd2bfefcd9f183ca1f43b5e1deb53e45335b2ba Mon Sep 17 00:00:00 2001 From: Benjamin Admin Date: Sun, 3 May 2026 22:51:23 +0200 Subject: [PATCH] docs: session handover updated for Block F start Next: F1 Regulation Registry (DB + API + Frontend + Auto-Create) Frontend at /sdk/regulation-registry in breakpilot-compliance admin Co-Authored-By: Claude Opus 4.6 (1M context) --- .../INSTRUCTION-session-handover.md | 311 +++++------------- 1 file changed, 77 insertions(+), 234 deletions(-) diff --git a/control-pipeline/INSTRUCTION-session-handover.md b/control-pipeline/INSTRUCTION-session-handover.md index 80c4df6..ed564ca 100644 --- a/control-pipeline/INSTRUCTION-session-handover.md +++ b/control-pipeline/INSTRUCTION-session-handover.md @@ -1,4 +1,4 @@ -# Session-Instruktionen: Pipeline-Qualitaet + Gesetze +# Session-Instruktionen: Block F — Hardcoded Knowledge Migration **Datum:** 2026-05-03 **Fuer:** Naechste Claude-Session @@ -6,267 +6,110 @@ --- -## ZUSAMMENFASSUNG: WO STEHEN WIR +## NAECHSTER SCHRITT: Block F1 — Regulation Registry -### Was fertig ist (Bloecke A-D5+) +### Was zu tun ist -| 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** | ✅ | +1. **DB-Tabelle** `compliance.regulation_registry` erstellen (Migration-Script) +2. **Daten migrieren** aus `control_generator.py` (135 Eintraege) + `source_type_classification.py` (58) +3. **Auto-Create** im RAG-Service bei Document-Upload (status='needs_review') +4. **Backend-API** in breakpilot-compliance Backend (GET/POST/PUT /v1/regulations) +5. **Frontend** in breakpilot-compliance Admin unter `/sdk/regulation-registry` (zwischen roadmap und isms) +6. **Sync-Check** Script (wöchentlich: Qdrant regulation_ids vs. DB) +7. **Code umstellen** in control_generator.py (Dict → DB-Query mit Cache) -### D5+ Details (Session 02-03.05.2026) +### Frontend-Anforderungen (breakpilot-compliance Admin, Port 3007) -**Problem geloest:** 4 NIST-PDFs hatten 0 Chunks (D5-Script hatte delete-before-upload, Upload scheiterte). +- NAV-Position: zwischen `/sdk/roadmap` und `/sdk/isms` +- Tabelle mit allen Regulations (sortierbar, filterbar) +- Status-Badge: "Needs Review" (gelb), "Active" (grün), "Deprecated" (grau) +- Counter im NAV für unreviewed Einträge +- Inline-Edit: license_rule, jurisdiction, source_type, names +- "Approve" Button → status='active' +- Diskrepanz-Anzeige: regulation_ids in Qdrant die nicht in DB sind -**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/` +### Kritische Dateien -### Aktuelle Qualitaet (Stand 03.05.2026) +| Repo | Datei | Aktion | +|------|-------|--------| +| core | `control-pipeline/services/control_generator.py` Z.75-236 | EDIT: Dict → DB | +| core | `control-pipeline/data/source_type_classification.py` | DELETE (nach Migration) | +| core | `rag-service/api/documents.py` | EDIT: Auto-Create bei Upload | +| compliance | `backend-compliance/compliance/api/regulations.py` | NEU: API Endpoints | +| compliance | `admin-compliance/app/sdk/regulation-registry/` | NEU: Frontend-Seite | -| 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 | +### DB-Schema -**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) +```sql +CREATE TABLE compliance.regulation_registry ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + regulation_id VARCHAR(100) UNIQUE NOT NULL, + regulation_name_de TEXT, + regulation_name_en TEXT, + regulation_short VARCHAR(50), + license_rule INTEGER NOT NULL DEFAULT 1 CHECK (license_rule IN (1, 2, 3)), + license_type VARCHAR(50), + source_type VARCHAR(20) NOT NULL DEFAULT 'law', + jurisdiction VARCHAR(10), + category VARCHAR(50), + celex VARCHAR(20), + url TEXT, + status VARCHAR(20) NOT NULL DEFAULT 'needs_review', + created_at TIMESTAMPTZ DEFAULT NOW(), + updated_at TIMESTAMPTZ DEFAULT NOW() +); -**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 +CREATE INDEX idx_reg_registry_status ON compliance.regulation_registry(status); +CREATE INDEX idx_reg_registry_jurisdiction ON compliance.regulation_registry(jurisdiction); ``` --- -## DB-STAND +## GESAMTPLAN Block F (4 Tage) -### 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. +| Phase | Was | Aufwand | Status | +|-------|-----|---------|--------| +| F1 | Regulation Registry (DB + API + Frontend + Auto-Create) | 1 Tag | 🔥 NAECHSTER | +| F2 | Action Types + Synonyme → DB | 1 Tag | Ausstehend | +| F3 | Object Synonyms → DB | 0.5 Tag | Ausstehend | +| F4 | LLM Synonym-Enrichment | 1 Tag | Ausstehend | +| F5 | Validation + Cleanup | 0.5 Tag | Ausstehend | --- -## TESTS AUSFUEHREN +## SESSION 02-03.05.2026 ERLEDIGT + +- Block D5+: NIST/ENISA PDF-Qualitaet (0%→45%) +- Block D6: Citation-Backfill (3.651 Controls) +- Block E2: 8 DE-Gesetze (1.629 Chunks) +- Block E3: 5 EU-Regulierungen (1.057 Chunks) +- Block E4: GoBD, BAIT, VAIT (144 Chunks) +- Block E6: 3 CH + 4 AT Gesetze (3.881 Chunks) +- Block E7: 9 Urteile als Volltext (709 Chunks total) + - Schrems II: 154, BVerfG Datenanalyse: 161, DSK OH Telemedien: 119 + - Meta: 101, BAG Zeiterfassung: 48, Planet49: 42, SCHUFA: 41 + - Schadenersatz: 29, Google Fonts: 14 +- Infra: Qdrant-Snapshot, Upload-before-Delete, 99 Tests + +**Gesamt neue Chunks diese Session: ~25.000+** + +--- + +## TESTS ```bash -# Embedding-Service (99 Tests inkl. 41 NIST-Tests) +# Embedding-Service (99 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 +# Qdrant-Snapshot 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. +Block F Detailplan: `/Users/benjaminadmin/.claude/plans/humming-nibbling-sonnet.md`