Brainversum · tuxametrics Graph Admin

know-how vertraulich owner: matus

CLAUDE.md — tuxametrics

CLAUDE.md — tuxametrics

Ablauf-Prototyp einer klinischen Entscheidungsunterstützung für die orthomolekulare Medizin (Labor-Interpretation → Therapieempfehlung → ärztliche Freigabe). Fachliche Herkunft: Repo tuxamed, Verzeichnis Bearbeitet/ — Umfang ist der dort in 00-bericht.md §9 vorgeschlagene Schnitt „Gold Path E1/E3".

WICHTIG — was dieses Produkt ist und was nicht

Dieser Absatz gehört in jede Zusammenfassung dieses Repos, in jedes Angebot und auf jede Demo-Folie. Er ist wörtlich aus tuxamed Bearbeitet/00-bericht.md §10 übernommen:

Was der Prototyp beantworten kann Was er nicht beantworten kann
Ist der Ablauf Patient → Befund → Prüfung → Empfehlung → Freigabe → Report richtig geschnitten? Sind die klinischen Regeln richtig?
Sind die richtigen Dinge Pflicht und die richtigen optional? Stimmen die nationalen Höchstmengen und die Eisen-Zielwerte? (OF-10, OF-67)
Ist die Trennung „System schlägt vor / Therapeut entscheidet" (GM-7) in der Oberfläche erkennbar? Ist die Verhältnislogik tragfähig? (E-7 — gar nicht enthalten, auch nach v1.2 nicht)
Versteht ein Therapeut, warum eine Empfehlung nicht erzeugt wurde? Ist die Dosisempfehlung fachlich korrekt?
Ist der Bericht in der Praxis verwendbar? Ist der Pilot rechtlich zulässig? (E-1, E-20 — extern vergeben, nicht beantwortet)

Geändert nach Backlog v1.2 (2026-08-09): In Zeile 2 stand rechts bis v1.1 „Stimmen die kritischen Schwellen? (E-8)". E-8 ist entschieden (FACH-045 Z. 1137–1165) — die Schwellen sind freigegeben und damit prüfbar statt bloß illustrativ. An ihre Stelle tritt die verbliebene echte Zahlenlücke: die nationalen Höchstmengenempfehlungen sind im Material selbst leer (OF-10, Z. 1599), die Eisen-Zielwerte unbeziffert (OF-67).

Keine klinisch validierten Regeln. Keine Aussage zur regulatorischen Zulässigkeit.

WICHTIG — fünf nicht verhandelbare Leitplanken

Alle fünf sind Architekturentscheidungen, keine Nice-to-haves. Wer daran rührt, braucht ein neues ADR, keinen Commit.

  1. GM-7 ist strukturell, nicht kosmetisch. Eine Empfehlung ist immer „vorgeschlagen"; final wird sie ausschließlich durch die Freigabe einer Person mit benannter Qualifikation. Es gibt keine technische Sperre, die eine Therapeutenentscheidung verhindert — außer den zwei Fällen von GM-7.5 (Zielpopulationsausschluss, nicht unterstützte Analyt-Matrix-Kombination), wo gar kein Ergebnis entsteht. Alles andere ist Hinweis plus Pflichtbestätigung. Wer eine Sicherheitsregel als harte Validierung implementiert, widerspricht GM-7 frontal.

    Nicht verwechseln mit Zugriffskontrolle (seit ADR-0005): wer das System benutzen darf ist eine andere Frage als was ein Therapeut entscheiden darf — und sie wird seit 2026-08-10 hart durchgesetzt. Die drei Capabilities der GM-7-Kette (txm.empfehlung.decide, txm.uebersteuerung.create, txm.freigabe.grant) sind im Capability-Katalog dauerhaft allowedActors=[USER] und nie an einen AGENT grantbar (tuxametrics-platform-service/util/Gm7Schutz, belegt in Gm7SchutzTest inklusive der Gegenprobe „ein Therapeut mit Grant darf freigeben"). Das sperrt keine klinische Entscheidung — es sagt nur, dass sie von einem Menschen kommt. Genau das behauptet GM-7 ohnehin; neu ist, dass es jetzt ein Mechanismus ist statt einer Zusage.

    Seit 2026-08-17 auch: nie über ein Profil (ADR-0008). Das ist keine Wiederholung der Zeile darüber, sondern eine eigene Aussage — die allowedActors=[USER]-Prüfung hätte einen Profil-Grant bestanden, weil ein Profil immer von einem Menschen ausgeübt wird. GM-7 verlangt aber eine Person mit benannter Qualifikation, und ein Profil ist eine Rolle mit einem Namen, den niemand validiert. Die drei Schlüssel bleiben Einzelgrants an namentlich bekannte Menschen — der eine Ort, an dem dieses Produkt bewusst nicht bündelt, obwohl es das Werkzeug dafür jetzt hat.

  2. Die vier „unbequemen" Elemente bleiben sichtbar: gesperrte Empfehlung mit Grund, Stufenkappung (GM-1.1), Konfundierung (GM-1.3), informierte Übersteuerung (GM-7.2). Sie sind Zustände im Datenmodell, keine UI-Details — siehe ADR-0004.

  3. Ebene E2 kommt in diesem Repo nirgends vor — kein Enum-Wert, kein Feld, kein Konzept, keine Referenz. Nicht belegbar: zu keinem der sieben Verhältnisse liegt ein Auffälligkeitsbereich vor (OF-01 / E-7). Das Ebene-Enum hat E1 und E3; die Lücke ist Absicht. Backlog v1.2 hat daran nichts geändert — E-7 blieb offen — einer von zwei Punkten, die v1.2 nicht abgeraeumt hat (der andere ist E-18, die Ausarbeitung der Referenzfaelle); FACH-040, FACH-050 und FACH-051 sind dort wörtlich unverändert. Wer „16 von 20 Entscheidungen getroffen" liest, schließt sonst das Gegenteil.

  4. Medikamenten-Interaktionen werden erfasst und angezeigt, aber NICHT regelbasiert geprüft. Medikationseintrag.interaktionspruefung ist ein Enum mit genau einem Wert (nicht-automatisiert-geprueft) — unbequemer als ein weggelassenes Feld, und genau das ist der Zweck. Grund: die Auflösung Handelsname → Wirkstoff hat im Material keine Quelle (OF-07).

    Seit 2026-08-26 gibt es die Auflösung trotzdem — und die Leitplanke gilt unverändert (ADR-0012). tuxametrics-substanzstammdaten-service führt einen eigenen, extern belegten Katalog (Wirkstoff als zentrale Entität, Handelsname referenziert genau einen). Das schließt die Lücke aus OF-07 als Fähigkeit, nicht als Freigabe: eine Interaktionsprüfung bräuchte zusätzlich einen Interaktionskatalog (Wirkstoff × Mikronährstoff), und der ist eine völlig andere Quelle, die es weder im Fachmaterial noch in jenem Service gibt. FACH-021 („nur der aufgelöste Wirkstoff ist Grundlage der Interaktionsprüfung") nennt eine notwendige, keine hinreichende Bedingung — wer sie für hinreichend hält, liest den Satz rückwärts. Die Auflösung ist damit vorhanden und ungenutzt; sie in die Auswertungslogik zu verdrahten ist eine eigene, spätere Entscheidung mit eigenem ADR.

  5. Zwei externe Fragen bleiben sichtbar unentschieden. tuxametrics.regulatorik.einstufung und tuxametrics.pilot.betriebsmodus müssen auf UNGEKLAERT stehen; RegulatorikGuard bricht den Start sonst ab. Siehe ADR-0002 und ADR-0003. Von ADR-0005 unberührt: dass IdP und Autorisierung jetzt entschieden sind, sagt über die regulatorische Einstufung und den Pilot-Betriebsmodus nichts — das sind Fragen an Dritte (Regulatory/Recht), keine Infrastrukturfragen. Wer die eine für die andere hält, löst einen Guard auf, der genau dafür gebaut wurde.

BEFORE touching any file — dieser Working Tree hat mehrere parallele Schreiber

Dieser Abschnitt steht vor der fachlichen Leseliste, weil er auch für die dreizeilige UI-Korrektur gilt, für die niemand die Leseliste durchgeht. Genau daran ist es am 2026-08-26 gescheitert (agentic-engineering/CLAIMS.md § Historie).

  1. agentic-engineering/CLAIMS.md prüfen — ist das benötigte Modul (Zeile aus guidelines/project/service-landscape.md) schon beansprucht? Falls ja: User fragen statt loszulegen. Falls frei: eigene Zeile eintragen, nach Abschluss entfernen. GG-AGENTIC-ENGINEERING-0002
  2. Im selben Zug agentic-engineering/STATE.md lesen — was gilt gerade über das laufende System auf tuxametrics-vm (Grant fehlt, Realm neu importiert, Tenant existiert schon). Erneut vor jeder Aktion gegen die laufende Umgebung, nicht nur beim Sessionstart. GG-AGENTIC-ENGINEERING-0007
  3. Kein pauschaler Agent-Log-Read. Ist das Modul frei, direkt loslegen. Gezielt greppen nur bei Claim-Konflikt (ab LastChanged) oder unklarem Zustand. GG-AGENTIC-ENGINEERING-0003
  4. Nach jedem Write/Edit eine Zeile an agentic-engineering/agent-log/YYYY-MM-DD.md anhängen — [YYYY-MM-DD HH:MM] | AKTION | pfad | Begründung, plus die Prosa-Abschnitte (FUNDe, Entscheidungen samt verworfener Alternative). Konvention: agentic-engineering/agent-log/README.md.
  5. Committen nur pfadgenau: git add -- <pfade> + git commit -- <pfade> in einem Aufruf, Pfade exakt aus den eigenen heutigen Log-Einträgen. Nie git add -A/-a/git add . — so ist am 2026-08-26 eine fremde, gestagte Datei in einen fremden Commit geraten. Bei einer .git/index.lock-Kollision warten und erneut versuchen, die Lock-Datei nie löschen. Push auf master und jeder Force-Push bleiben rückfragepflichtig.

Alle vier Regeln sind in guidelines/INDEX.md § GG-AGENTIC-ENGINEERING gelistet, jeweils mit der Begründung, warum sie für dieses Produkt zählt — inklusive der ehrlichen Einordnung von GG-AGENTIC-ENGINEERING-0005 (Worktree-Isolation), die den Fall zweier unabhängiger Sessions im selben Checkout gerade nicht löst.

Die Punkte 1 und 4 sind seit 2026-08-26 keine Zusage mehr, sondern ein Mechanismus. Drei projektlokale Hooks setzen sie durch (.claude/hooks/README.md, verdrahtet in .claude/settings.json): ein PreToolUse-Guard blockiert Schreibzugriffe auf fremd beanspruchte Module, ein PostToolUse-Hook schreibt das Zeilenprotokoll selbst, ein SessionStart-Hook meldet ungefragt laufende Fremdsessions, offene Claims und bereits gestagte fremde Dateien. Kein anderes Projekt dieser Werkstatt hat so etwas — dort ist es überall reine Konvention (DOTs ADR-0012 sagt das wörtlich). Wer allein arbeitet, merkt von den Hooks nichts: sie hängen an einer nachweisbaren Fremdsession, nicht an einer Vermutung.

Was sie nicht können, steht vollständig im README und ist beim Arbeiten mitzudenken. Vor allem: sie greifen nur bei Edit/Write, nicht bei Bash — der git add -A-Fall vom 2026-08-26 ist mechanisch weiterhin ungeschützt (Punkt 5 oben bleibt Handarbeit) — und sie sind fail-open: dass keine Blockade kam, beweist nicht, dass geprüft wurde. Nach jeder Hook-Änderung node .claude/hooks/selftest.mjs laufen lassen.

BEFORE implementing anything

  1. Globale Regeln (GG-*) liegen im Zwirn-Repo (dev.zwirn), lokal unter ../zwirn/guidelines/ — dort zuerst lesen (Master-Index: ../zwirn/guidelines/INDEX.md). Ist Zwirn nicht als Geschwister-Checkout vorhanden → klonen (git clone <zwirn-repo-url> ../zwirn). Nie hierher kopieren.
  2. Dieses Repo hält nur produktspezifische Regeln (PG-*) unter guidelines/ (siehe guidelines/INDEX.md).
  3. Reihenfolge: guidelines/INDEX.md → guidelines/project/gold-path-scope.md → guidelines/project/domain-map.md → documentation/domain/laborauswertung.md → agentic-engineering/BACKLOG.md → dann Code.
  4. Standard-Framework: Quarkus (Zwirn-ADR-0007), Muster aus ../zwirn/samples/sample-data-service-quarkus. Frontend-Slices nach ../zwirn/samples/sample-frontend-react. Wer eine Liste oder Tabelle baut, liest vorher GG-ARCH-FRONTEND-0003 (../zwirn/guidelines/architecture/web-frontend/frontend-tables-pagination.md): Pagination mit start/limit, Seitengrößen-Auswahl, 400 ms Debounce, DataTable/SearchInput/EmptyState aus @zwirn/web — auch bei drei Demo-Zeilen. Bis 2026-08-26 stand hier nur das Beispielprojekt, und ein Beispiel zum Abschauen ist keine Regel: wer sich die nächstgelegene Seite als Vorlage nimmt, erwischt mit KatalogeRegelwerkPage ausgerechnet die dokumentierte Ausnahme. Alle sieben Frontend-Regeln und die Begründung, warum sie hier zählen: guidelines/INDEX.md § GG-ARCH-FRONTEND.
  5. Docker-Build braucht ZWIRN_M2 in .env — siehe .env.example und ../zwirn/guidelines/project/devops/docker-zwirn-m2-build-context.md.
  6. Autorisierungs-relevante Reviews: zusätzlich ../zwirn/policies-opa/capability/*.rego lesen — das ist die tatsächliche Enforcement-Logik und taucht in keinem Diff dieses Repos auf (Zwirn-ADR-0005).

BEFORE changing fachliches Verhalten

Die fachliche Quelle ist ein anderes Repo. Alle Zahlen, Kataloge und Regeln stammen aus tuxamed Bearbeitet/ (anonymisiertes Extraktionsergebnis nach GG-META-0005). Die Arbeitszone raw/ dort ist versiegelt und wurde nie geöffnet — sie darf auch künftig nicht geöffnet werden. Maßgeblich ist seit 2026-08-09 die Kundenfassung quelle-01-v1.2.md; quelle-01.md (v1.1) bleibt nur als Referenz für „was vorher dastand".

Jede Zahl im Code trägt ihre Fundstelle (FACH-NNN, Zeilennummer). Wo das Material keine Zahl hat, hat der Code auch keine:

Leitregel für jeden weiteren Nachzug auf v1.2:

Korrigiert wird, was v1.2 widerlegt. Nicht gebaut wird, was v1.2 neu ermöglicht.

Was v1.2 erstmals belegbar macht (eGFR-Modifikator, klinische Tragweite, Aktualitätsgrenzen, E-14-Blockadekriterien, Eisen-Sonderregel, X-3a/X-3b, Patientenversion), ist eine Scope-Erweiterung und braucht eine eigene Entscheidung — nicht einen Commit: agentic-engineering/backlog/v12-nachzug-scope.md.

Alle Zahlen und Kataloge liegen an einer Stelle: tuxametrics-laborauswertung-service/.../regelwerk/Regelkatalog.java. Neue Fachzahlen gehören dorthin oder in die Fragenliste — nie „klingt plausibel".

Seit 2026-08-24 mit genau einer Ausnahme, und sie ist keine Aufweichung (ADR-0011): eine Praxis kann ein R-Global-Feld praxiseigen überschreiben — das Reevaluationsintervall (FACH-074), und auch das nur verkürzend. Das ist keine neue Zahlenquelle, sondern die Umsetzung von FACH-063/E-11, das in v1.2 entschieden wurde und genau festlegt, welche Regelarten eine Praxis ändern darf. Von den fünf dort freigegebenen führt Regelkatalog.java nur diese eine; die vier gesperrten Kataloge dieses Repos (Dosisobergrenzen/FACH-072, kritische Schwellen, Kontraindikationen, Sicherheitshinweise) bleiben unveränderbar und lehnen jeden Versuch mit Grund ab. Wer eine wirksame Zahl sucht, liest deshalb Regelkatalog.java plus die Momentaufnahme des jeweiligen Falls (auswertung_regelbindung) — und jede Aussage weist ihre Herkunft aus (GM-6.2). Das Mockup zeigt an dieser Stelle eine editierbare Dosisobergrenze; die ist nach E-11 gerade nicht änderbar.

Struktur

Dazu betrieben, nicht importiert (Zwirn-ADR-0006, fertige Docker-Images): zwirn-audit-service und seit 2026-08-14 zwirn-autoimprove-service, je mit eigener DB, plus ein eigenes Redis als Ingest-Weg des Audit-Streams. Umfang und Begründung: agentic-engineering/backlog/audit-feedback-processhub-integration.md. Audit-Events blockieren nichts (GM-7) und tragen keine Gesundheitsdaten — nur Schlüssel und Zählungen.

zwirn-feedback-service wird nicht mehr betrieben (ADR-0007). Zwirn bietet beide Bausteine unverändert an — den leichtgewichtigen Rückkanal (zwirn-feedback-service) und die claim-basierte Karten-Pipeline (zwirn-autoimprove-service); für ein Produkt ist die Wahl ein Entweder-oder, und tuxametrics hat sich für die Pipeline entschieden. Das ist eine Produktentscheidung und sagt über Zwirn nichts. Dieselbe ADR hat das kurzlebige Eigenbau-Modul tuxametrics-feedback-process (ADR-0006, angenommen und abgelöst binnen eines Tages) ersatzlos entfernt.

Mit dem Autoimprove-Service hat dieses Produkt seinen ersten AGENT-Actor: ein Keycloak-Client tuxametrics-autoimprove-agent, eine AGENT-Identity in tuxametrics-virtual-identity-service (boot/AgentIdentitySeeder) und drei autoimprove.*-Grants. Er handelt nicht — es gibt keinen Scheduler und keinen Bot, der ihn bedient; das wäre eine eigene Entscheidung. GM-7 ist davon unberührt: die drei geschützten Capabilities bleiben [USER] und sind an einen AGENT nicht grantbar.

Dieselbe Adoption bringt zwei Dinge mit, die nicht nach ihr aussehen und deshalb hier stehen: der Autoimprove-Service bekommt einen eigenen Keycloak-Client (tuxametrics-autoimprove-service) statt des geteilten tuxametrics-services — der erste Schritt weg von der benannten DEV-Vereinfachung, mit DOT als Präzedenzfall (C:\dev\dl-controlling\dot, ADR-0071) — und die Authority bekommt GET /me/capabilities (web/MeResource), weil jede handelnde Schaltfläche der Zwirn-Frontend-Pakete daran hängt. Beides ist in ADR-0007 begründet.

Seit 2026-08-12 ebenfalls betrieben, nicht importiert: zwirn-testmanagement-service — der produktneutrale Katalog (TestGroup→TestSubgroup→TestCase, plus TestRun-Protokoll) hinter der Nav-Sektion „Testfälle" in tuxametrics-ui (src/domains/testfaelle, kein fertiges Frontend-Paket, weil Zwirn keins mitbringt). „Ausführen" ruft den bestehenden POST /demo/referenzfall erneut auf — kein zweiter Mechanismus. Umfang, Begründung und was noch offen ist (62 von 63 Fällen ohne Mock-Szenario): agentic-engineering/backlog/testmanagement-integration.md.

Bauen

mvn -f pom.xml test                     # Reactor: alle fünf Module + ArchUnit-Regeln
cd tuxametrics-ui && npm run typecheck

Der Reactor aggregiert seit 2026-08-26 fünf Module (Authority, VID, Substanzstammdaten, Laborauswertung, Process-Hub-Cockpit). Am 2026-08-13 waren es schon einmal fünf; jenes fünfte (tuxametrics-feedback-process) ist am 2026-08-14 mit ADR-0007 entfallen — das heutige fünfte ist ein anderer Fall (ADR-0012, echte Datenhoheitsgrenze statt zweiter Schnitt derselben Domäne). Jedes Quarkus-Modul ist auch einzeln baubar (mvn -f <modul>/pom.xml test) und hat bewusst keinen <parent> — Aggregation ist in Maven unabhängig von Vererbung.

Nativer Bau (GG-DEVOPS-0003, Pflicht für jeden nicht-lokalen Einsatz):

mvn -f <modul>/pom.xml package -DskipTests -Pnative \
    -Dquarkus.native.container-build=true \
    -Dquarkus.native.builder-image=quay.io/quarkus/ubi9-quarkus-mandrel-builder-image:jdk-25

Der Heap-Deckel native-image-xmx=6g steht in allen vier native-Profilen und ist nicht optional: ohne ihn bemisst native-image seinen Heap an der sichtbaren Maschine statt am freien Speicher. Bei Exit 137 den Deckel senken, nicht erhöhen — 137 ist SIGKILL von außen, ein größerer -Xmx verschlimmert es (Quarkus' eigene Meldung rät hier falsch herum). Am 2026-08-10 liefen zwei Module erst mit -Dquarkus.native.native-image-xmx=4g durch. Alle drei Module sind nativ gebaut; gestartet wurde keines — das ist eine andere Aussage.

tuxametrics-process-hub-cockpit bleibt bewusst JVM (Flowable/Spring, Reflection) — eine benannte Ausnahme von GG-DEVOPS-0003, kein Versehen.