feat: initial F∆I Law-Heatmap Phase 0 scaffold

First end-to-end-buildable cut of the pflicht-/graph-basierte Wirkungsanalyse von Rechtsnormen, running on Ch∆In. Demo runs without external dependencies and without a hub connection so the methodology + UI stack can be reviewed before any Verbands- Kooperation or Beirats-Validierung kicks in. Tree layout MACHBARKEITSSTUDIE.md v0.3 — pflicht-basierte Methodik, 4-Tier-Evidenz, 8 law*-Module auf Ch∆In statt der alten F∆I- Plattform. RUN.md one-page how-to-run. flows/durchstich-gewo-14.yaml vertical Phase-0 flow: pull → normalize → duties → citations → cohort → skm → frust → benefit → attribution → system.approval. app/ Flutter macOS client, design language pulled from fai_web (ink #08090A, paper #F4F3EF, petrol signal #2E8F9E). Mock repository ships five fixture norms with real source URLs and a permanent T4 demo-banner so no figure can be mistaken for a validated one. Module repos (separate, see chain-modules*/): text-akoma-normalize, text-deontic-extract, graph-citation- extract, text-readability-score, stats-cohort-size, graph- shapley-attribution, econ-skm-score, law-benefit-score. What runs today - flutter analyze: 0 issues - flutter test: 2/2 (landing + nav-to-shell smoke) - flutter build macos (via app/build-macos.sh) and ad-hoc codesign, app launches and the Dart VM service comes up - native cargo test green on every module - cargo build --release --target wasm32-wasip2 produces a 130 KiB artefact for text-akoma-normalize What is deliberately mock / stub - gRPC wire from the client to a chain serve hub (Repository abstraction is in place; live impl is the next step) - NKR Bürokratiekosten-Datenbank ingestion (for the canonical h-Werte that close out the Engpass per Studie §6.7) - DESTATIS GENESIS-API adapter for stats.cohort_size License: Apache-2.0. Author/contact in MACHBARKEITSSTUDIE.md. Signed-off-by: flemming-it <sf@flemming.it>
2026-06-18 11:26:28 +02:00 · 2026-06-18 11:26:28 +02:00 · 8ee6a294a1
commit 8ee6a294a1
64 changed files with 5641 additions and 0 deletions
--- a/RUN.md
+++ b/RUN.md
@ -0,0 +1,107 @@
+# F∆I Law-Heatmap — Run-Guide (Phase 0)
+
+> Stand v0.1.0 — Demo-Modus, ohne externe Daten, ohne Hub-Verbindung.
+
+## Layout
+
+```
+fai_lawheatmap/
+├── MACHBARKEITSSTUDIE.md     # die Studie (v0.3, AG-intern)
+├── RUN.md                    # diese Datei
+├── app/                      # Flutter-Client, Brand-Skin fai_web
+│   ├── lib/                  # Dart-Code (Pages, Widgets, Data, Theme)
+│   ├── assets/
+│   │   ├── fonts/            # SIL-OFL TTFs (setup.sh holt sie)
+│   │   └── fixtures/         # Phase-0 Demo-Daten
+│   ├── macos/                # Plattform-Scaffolds (auto-generiert)
+│   ├── setup.sh              # Fonts + Pakete
+│   └── pubspec.yaml
+└── flows/
+    └── durchstich-gewo-14.yaml   # vertikaler Phase-0-Flow
+```
+
+Die acht zugehörigen Module liegen unter `fai_chain_modules/` als
+eigene Crate-Verzeichnisse, ABI `chain:platform`, alle Apache 2.0:
+
+- `text-akoma-normalize/` (Pflicht-Eingang, gesetze-im-internet-XML-Adapter)
+- `text-deontic-extract/` (Pflicht-Tupel via Regex + LLM-Vorschlag im Flow)
+- `graph-citation-extract/` (`cites`, `verweist_iVm`)
+- `text-readability-score/` (Flesch-DE + Verweistiefe)
+- `stats-cohort-size/` (DESTATIS-/IHK-Kohorten, Phase 0 mit Stub-Tabelle)
+- `graph-shapley-attribution/` (Pfad-anteilige Splittung)
+- `econ-skm-score/` (Standardkostenmodell P×F×T×h)
+- `law-benefit-score/` (7-dim. Nutzen-Aggregation — das einzige genuin
+  domänen-spezifische Modul, gehört in `chain-modules-law/`)
+
+## Sofort starten (Demo-UI, kein Hub nötig)
+
+```bash
+cd app
+./setup.sh                # Fonts + flutter pub get
+./build-macos.sh          # Robust-Build (strippt macOS-xattrs vor CodeSign)
+open build/macos/Build/Products/Debug/lawheatmap_app.app
+```
+
+Direkter `flutter run -d macos` funktioniert auch, kann aber bei
+einem frischen Checkout an `com.apple.provenance`-xattrs scheitern
+(macOS-Eigenheit bei via curl/iCloud erstellten Dateien) — dann
+einmal `./build-macos.sh` und danach `flutter run -d macos`.
+
+Erwartet: Brand-Landing → Klick auf „App öffnen (Demo-Modus)" →
+NavigationRail (Heatmap / Normen / Hub / Methodik) mit fünf
+Pilot-Norm-Punkten und einem permanenten T4-Demo-Banner.
+
+Test-Suite (smoke):
+```bash
+flutter test
+```
+
+## Modul-Tests (lokal grün ohne Hub)
+
+```bash
+for m in text-akoma-normalize text-deontic-extract \
+         graph-citation-extract text-readability-score \
+         stats-cohort-size graph-shapley-attribution \
+         econ-skm-score law-benefit-score; do
+  (cd ../fai_chain_modules/$m && cargo test) || break
+done
+```
+
+## WASM-Build (für `chain install`)
+
+```bash
+cd ../fai_chain_modules/text-akoma-normalize
+cargo build --release --target wasm32-wasip2
+# Artefakt: target/wasm32-wasip2/release/text_akoma_normalize.wasm
+```
+
+Selber Aufruf für die anderen sieben Verzeichnisse.
+
+## Live-Flow (sobald `chain serve` läuft — Phase 0 Woche 1)
+
+```bash
+chain serve &
+chain install text.akoma_normalize text.deontic_extract \
+              graph.citation_extract text.readability_score \
+              stats.cohort_size graph.shapley_attribution \
+              econ.skm_score law.benefit_score \
+              http.request system.approval
+chain run flows/durchstich-gewo-14.yaml \
+  --input norm_url=https://www.gesetze-im-internet.de/gewo/__14.xml \
+  --input cohort_id=berlin-kmu
+chain admin events --limit 10
+chain admin approvals list   # Juristen-Gate
+```
+
+Im Flutter-Client den `MockRepository` durch eine `HubRepository`
+(gRPC gegen `localhost:50051`) ersetzen — Interface bleibt gleich,
+keine UI-Änderung nötig.
+
+## Was Phase 0 NICHT enthält (bewusst)
+
+- gRPC-Anbindung Flutter ↔ Hub (Woche 1)
+- Echte NKR-Datenbank-Anbindung (Woche 2-3)
+- DESTATIS GENESIS-API-Adapter (Woche 4)
+- Juristen-Approval-Backend-Anbindung (Woche 5)
+- Volle Akoma-Ntoso-Konvertierung (v0.2)
+- HTML- und FORMEX-Adapter für `text.akoma_normalize` (v0.2/0.3)