odoo-at-payroll/personalverrechnung/RUNBOOK.md

RUNBOOK — Personalverrechnung

Operational memory for recurring workflows. Update when a procedure changes or a validation step catches an error it should have caught.

KV-Library (alle aktuellen Kollektivverträge, maschinenlesbar)

Stand: 2026-09-09 · Aufbau siehe quellen/kv/ und die Skript-Docstrings.

Architektur

Quelle	Rolle	Werkzeug	Rohdaten (unversioniert)
kollektivvertrag.at (ÖGB-Verlag)	Baseline — einziger vollständiger, maschinenlesbarer Korpus über alle Kammern; Kreuzcheck-Referenz	tools/fetch_kv_portal.py	.firecrawl/kv-portal/
wko.at KV-Datenbank	Main source für WKO-Gewerbe/Industrie/Handel…	tools/fetch_wko_kv.py	.firecrawl/wko-kv/
Kammern (Ärzte, Apotheke, RA, Notariat, LWK, öffentl. Dienst)	Main source soweit öffentlich; Registry der Quellen + Lücken	quellen/kv/chambers/chambers.json (kuratiert)	—

Merge/Crosscheck: tools/build_kv_catalog.py → quellen/kv/kv-catalog.json|.csv mit chamber, main_source, cross_check (Match-Status + Datumsabgleich WKO „gültig ab" vs. ÖGB-Slice-Version) und manual_review-Listen.

Kuratierte Texte: quellen/kv/oegb/texts/SI-*.json|.md (Struktur: §-Hierarchie, Slices = Teile mit Versionsdatum, Topics; JSON ist das maschinenlesbare Primärformat, MD nur Review/Diff) sowie quellen/kv/wko/texts/{slug}.json|.md. Lohntafel-PDFs werden nicht downgeloadet (nur verlinkt); im KV-Text enthaltene Entgelttabellen sind Bestandteil der Konvertierung.

Aktuell halten (Wartungszyklus)

Mindestens jährlich mit der Bezügeanpassungs-Runde (Jänner) und nach bekannten KV-Abschluss-Runden (üblich: Jänner + Juli):

python3 personalverrechnung/tools/fetch_kv_portal.py --refresh   # diff lastContentUpdate/validFrom
python3 personalverrechnung/tools/fetch_wko_kv.py --refresh      # diff wko_lastmod (DV-Sitemap)
python3 personalverrechnung/tools/build_kv_catalog.py            # Merge + Crosscheck neu

Danach manuell sichten (Reihenfolge):

1. oegb/update-reports/update-<datum>.json — changed/new/removed.
2. kv-catalog.json → manual_review:
   • wko_without_clear_match (Match-Heuristik! Titelmorphologie, Hilfsdokumente wie Lohnordnungen/Tabellen landen hier),
   • date_disagreements (WKO-Datum vs. Portal-Slice — meist noch nicht aktualisierte WKO-Seite oder neuere Konsolidierung),
   • unclassified (v. a. Einzelträger-KVs: Austro Control, Diözesen, Orchester … — nur prüfen, ob eine Zuordnung Sinn ergibt).
3. chambers/chambers.json stichprobenartig verifizieren (URLs können sich ändern); nicht mehr öffentliche Quellen als solche vermerken.

Validierung

• Strukturcheck: Katalog-Zahlen (entries = oegb + wko_only), alle texts/*.json parsebar, jede ÖGB-Variante hat json+md (Skript-Schnelltest siehe git-history dieses RUNBOOKs).
• Rechenfälle gegen Portaldarstellung: 2–3 bekannte KVs (z. B. SI-2203 Handwerk und Gewerbe, SI-2748 Metallgewerbe, SI-2757 Zahntechnik) im Dashboard/Volltext gegen texts/*.md halten.
• Änderungen niemals aus Trainingswerten — nur aus den gespeicherten Rohdaten (--build-only baut kuratierte Ausgaben offline neu).

Bekannte Limitierungen (Stand 2026-09-09)

• Match WKO↔ÖGB ist heuristisch (Token-Overlap mit Prefix-Fuzzy); alles unter Score 0,75 bzw. Hilfsdokumente landet bewusst in manual_review statt stillschweigend zugeordnet zu werden.
• WKO-Übersichtsseiten listen je Bundesland identische, regionenneutrale aktuelle Dokumente (614 aktuell); Archivjahre nur über die DV-Sitemap (3.879 URLs, wko_lastmod getrieben).
• Kammer-PDFs teils Scans ohne Textlage (RA Vbg, LÄK NÖ/OÖ/Bgld) — OCR wäre nötig, ist nicht eingebaut; ÖGB-Portal liefert dafür maschinenlesbare Texte.
• Öffentlicher Dienst: GÖD-Volltexte member-only; Gemeindebedienstete teils Landesgesetze statt KV (Bgld. GemBG 2014 — siehe RECHTSQUELLEN-Bgld.md).
• Angestelltenärzte-KV (Krankenanstalten): nirgends öffentlich — einzige systematische Lücke des Korpus.

Lexis360-Wissensbasis (Lexis Briefings Personalrecht)

Stand: 2026-09-10 · Konventionen und Schema: wissensbasis/README.md (dort auch die Lizenz-Entscheidung: Volltexte/PDFs lokal unversioniert, nur Kuratierung versioniert).

Architektur

Schicht	Pfad	Werkzeug	Versioniert?
PDF-Exporte (Lexis 360, lizenziert)	.lexis360/*.pdf	manueller Export	nein (gitignored)
Layer 1 — Volltexte + Katalog	.lexis360/md/	tools/build_lexis_kb.py --extract	nein
Layer 2 — kuratierte Einträge	wissensbasis/dokumente/<slug>.md	manuell (Vorlage lb-atz-07)	ja
Registry + Index	wissensbasis/kb.json, wissensbasis/INDEX.md	tools/build_lexis_kb.py --registry	ja (generiert)

Batches 1–6: 277 Einträge, 40 Cluster (atz 15 · leh 16 · jug 8 · pra 4 · bes 8 · tzb 6 · beh 4 · ent 11 · gsf 5 · lei 1 · prm 6 · sac 21 · vst 4 · son 4 · zus 8 · pen 9 · rei 9 · vor 11 · ges 2 · lsd 13 · gpl 7 · lnk 7 · pfa 14 · lvr 9 · naz 4 · azg 4 · azm 7 · mip 4 · nsc 3 · rhz 4 · sch 1 · ues 4 · zer 3 · swa 5 · asc 12 · dnh 7 · glb 7 · mob 1 · fir 6 · wei 3); Batch 7: 97 Einträge, 16 neue Cluster (url 14 · krs 9 · grz 8 · kzs 7 · elt 6 · kar 6 · kbg 6 · prd 6 · tel 6 · msf 5 · dvh 4 · aug 2 · efz 2 · pap 2 · pfl 2 · wie 2; bestehende Cluster erweitert: asc 12→16, sch 1→7) — insgesamt 374 Einträge, 56 Cluster, Quell-Stände 2024-03 bis 2026-09. Zehn Briefings- Kapitel: „Beschäftigungsverhältnisse“, „Entgelt: Anspruch & Abrechnung“, „Arbeitszeit“, „Arbeitnehmerschutz“, „Verhaltenspflichten“ sowie aus Batch 7 „Urlaub & Karenzierung“, „Schwangerschaft & Elternkarenz“, „Krankenstand & Arbeitsunfall“, „Dienstverhinderung“ und „Außerhalb des Betriebsstandortes“. IDs sind eingefroren (lb-<prefix>-<nn>) — neue Batches hängen hinten an, Nummern werden nie wiederverwendet; topic im Frontmatter = beschreibender ASCII-Slug (altersteilzeit, lehrlinge, jugendliche, ferialpraktikanten, beschaftigungsformen, teilzeit), nicht das ID-Präfix.

Neue Batches einspielen

# 1. PDFs nach .lexis360/ kopieren (Export-Namenskonvention beibehalten)
# 2. BATCH-Konstante in tools/build_lexis_kb.py hochsetzen
python3 personalverrechnung/tools/build_lexis_kb.py --extract   # Layer 1 + Katalog
# 3. neue Layer-2-Einträge kuratieren (Schema/Regeln: wissensbasis/README.md)
python3 personalverrechnung/tools/build_lexis_kb.py --registry  # kb.json + INDEX.md, validiert Frontmatter
python3 personalverrechnung/tools/build_lexis_kb.py --check     # Vollständigkeit Layer-1↔Layer-2

Validierung

• --registry prüft: Pflicht-Keys, ID-Muster, ID-Präfix↔topic-Konsistenz, stand-Format, batch, dangling cross_refs.
• --check prüft: 1:1-Katalog↔Kuratierung, Layer-1- und PDF-Existenz.
• Stichproben: Kernwerte gegen Layer-1-Volltext (sed -n '16,$p' .lexis360/md/<slug>.md); Werte nie aus Trainingswerten.

Bekannte Limitierungen / offene Punkte (Stand 2026-09-10)

• Korpus-Widersprüche (⚠, in den Einträgen dokumentiert): AMS- Ersatzquote geblockte ATZ 2026 — lb-atz-07 nennt 28,5 %, lb-atz-09/12 nennen 27,5 % (RIS/AMS-Klärung vor Implementierung nötig); DAG-Grenze 2023 751,36 € (lb-bes-02) vs 751,37 € (lb-bes-06); Lehrlinge- Kurzarbeit lb-leh-11 („100 %") vs lb-leh-07 (seit 2023 ausgenommen); Bande 3–4 Monate lb-jug-01 vs lb-pra-02; Kleinwohnungsgrenzen lb-sac-09 (35/45 m²) vs lb-sac-10 (30,1–40 m², bis 2024); Pensionisten-Begünstigung lb-sac-02 (LStR Rz 104 vs geänderte Briefing-Ansicht).
• Alte Quell-Stände: leh-Cluster teils 2024-03/2025-08; gsf/vst/lei teils 2025-06; son-01/02/03 2025-06 — €-Werte nur mit Stand-Kennzeichnung verwenden; Vorzug für neuere Briefings desselben Clusters (Abgleich son-01–03 ↔ lb-son-04 2026-08 erfolgt, Werte deckungsgleich bis HBG-SZ 6.930/13.860 € 2026).
• Offene Detailpunkte (⚠/❓, in den Einträgen dokumentiert): u. a. €-14,53-Parkplatz ohne SV-/LSt-Kategorisierung in der Quelle (lb-sac-18), Incentive-Reisen nur mit LStR-Rz ohne §-Ebene (lb-sac-16), VwGH-Spannungsverhältnis § 67 Abs 10 vs. Abs 1/2 (lb-sac-13), Schadenersatz-Mindestbeträge ohne §-Fundstelle + Quell-Tippfehler vereinfachter 6 %-Tarif lb-prm-04 (maßgeblich ist die verifizierte §-67-Staffel in RECHTSQUELLEN-Privat.md); § 124b-ÜStd-Maßnahme 2026 (lb-zus-07): Quelltext „Z 440 lit c"/ BGBl I 4/2026 — verbindlich laut RECHTSQUELLEN „Z 476 lit c idgF BGBl I 43/2026", Aufrollung bis 30. 9. 2026 (Substanz 15 ÜStd/170 € 2026 ident); lb-ent-01 nennt § 68 Abs 2 pauschal 120 € ohne 2026-Maßnahme (verbindlich 170 €); lb-pen-09: Tabellenwert „€ 3.672" beim aliquoten großen PP > 60 km vermutlich Druckfehler (rechnerisch € 2.448 — ⚠); lb-pen-01: PendlerVO § 2 Abs 3 (Zeitdauer) vs. BMF-FAQ (Entfernung); 183-Tage-Regel Finanz vs. UFS Salzburg (lb-rei-01/02/08); Teleworker-Fahrten Finanz vs. BFG/VwGH (lb-rei-07); SV-Pflicht der Belegschaftsbeteiligungsstiftung ⚠ (lb-vor-01); Kundengeschenke ohne generelle SV-Wertgrenze ❓ (lb-ges-02).
• Batch-4-Konflikte (⚠, in den Einträgen dokumentiert): lb-lnk-02 DB-Freibetragsbedingung: Quelle formuliert invertiert („übersteigt 1.460 €“ statt „übersteigt nicht“) — RECHTSQUELLEN-Fassung verbindlich, korrekte Staffel über lb-lnk-03 belegt; lb-lnk-05 WBF-Wien: Quelle 1,5 % vs. RECHTSQUELLEN/SV-Werte 1,0 % — RIS-Klärung vor Implementierung; lb-pfa-03/05: Bezeichnungskonflikt erhöhter vs. allgemeiner Grundbetrag 2026/2025 (1.308/1.273 vs. 1.526/1.486 €); lb-pfa-12/14: absolutes Geldexistenzminimum 2022 (500 vs. 515 €); lb-lsd-13: verstümmeltes Gesetzeszitat („§ 14 Abs 1 Z 1 und 28“) — ❓ RIS-Verifikation vor Implementierung; lb-lsd-08: 10 %-Grenze aus LSDB-Richtlinien 2015 (Verwaltungsrichtlinie, keine Norm); §-124b-Zitier-Varianten im Korpus (lb-zus-07 „Z 440“, lb-lvr-07 „Z 449“, lb-naz-03 „Z 440“) vs. RECHTSQUELLEN-verbindlich „Z 476 lit c idgF BGBl I 43/2026“; § 49a ASVG in keiner Batch-4-Quelle zitiert (offener GP0-Punkt bleibt quellenoffen).
• Batch-5-Konflikte (⚠, in den Einträgen dokumentiert): lb-ues-01 („§ 7 Abs 1") vs lb-ues-04 („§ 7 Abs 6 AZG") für das Ablehnungsrecht — Abs 6 als plausibel, ⚠ RIS-Konsolidierung; lb-nsc-01: NSchG-Beitrag 2026 (3,8 %) nur „vorerst“ ohne BGBl-Beleg ⚠; lb-nsc-03: Quellfundstelle „§ 10a NSchG“ vermutlich § 10a UrlG gemeint; lb-rhz-03: MAV-START-EU-Konflikt ⚠; lb-zer-01: § 12 Abs 2a vs § 12a AZG (Bezeichnungskonflikt); EuGH C-254/18 (lb-zer-01) vs C-55/18 (lb-zer-02) — gleichlautende Schlussfolgerung, Zitierdivergenz vermerkt; lb-azm-06: KAB-Richtlinie lt. Quelle mit alten SV-Beitrags- werten beim 39,05 %-Teilbetrag; lb-azm-07: hM/aA-Streit 50 vs 60 h Wochen-NAZ; lb-sch-01: All-in-Reduktion § 2g AVRAG nur Quellen- einschätzung („wohl“). Kurzarbeit-Lehrlinge jetzt trianguliert: lb-azm-05 (2026-07) bestätigt lb-leh-07 (Lehrlinge seit 1. 1. 2023 ausgenommen) gegen lb-leh-11 („100 %") — Umsetzung nach lb-leh-07/ lb-azm-05.
• Batch-6-Konflikte (⚠, in den Einträgen dokumentiert): GKV-Version asc-01 (2020) vs. asc-07 (2021) — ⚠ RIS; asc-06 „§ 34 Abs 3 AStV“ vermutlich § 36 Abs 3; dnh: § 3-DHG-Fristenstreit (hL 6 Monate für alle Grade vs. Mindermeinung 3 Jahre), SV-/Lohnsteuer-Behandlung abgezogener Schadenersatzbeträge ❓; glb-07 vs. beh-04: Aufstiegsschaden „3 Monatsentgelte“ vs. „3 Monate Differenzbetrag“, €-1.000-Zuordnung, Schlichtungsstellen-Namen — ⚠ RIS-Klärung; swa-03: Teilpension 2026/Regelpensionsalter ohne Normzitat ⚠; ASchV/NSchG in RECHTSQUELLEN nicht erschlossen ❓;
• Batch-7-Konflikte/offene Punkte (⚠/❓, in den Einträgen dokumentiert): lb-asc-15: Rechenbeispiel schöpft das Kontingent mit nur 42 Kalendertagen (6 Wochen) aus, obwohl „seit vier Jahren im Unternehmen“ — Stufentabelle desselben Briefings und lb-krs-08 (2026-07: ab 2. Dienstjahr 8 Wochen 100 % + 4 Wochen 50 % = 56 Tage) sprechen für das 2.+ Dienstjahr; Werte passen zum 1. Arbeitsjahr, AU-Teilrechnung (43+13 = 56) ist konsistent — beide Lesarten dokumentiert, ⚠ RIS vor Übernahme der Beispielwerte; lb-aug-01/02: §-Garbel „§ 11503/§ 1503 Abs 30 ABGB“ (vermutlich § 1153 Abs 30 ABGB) — nicht in legal_bases, ❓ RIS; lb-grz-08: OGH-Folgepflicht-Judikatur (9 ObA 51/99m, 9 ObA 48/00z) vs. ausdrückliche Quellenkritik (Reissner: mit § 905 ABGB „unhaltbar“) — beide Positionen dokumentiert, RIS vor Umsetzungsentscheidungen; lb-efz-01: Zeitausgleich für Feiertagsarbeit „mind. 1 Kalendertag oder 36 Stunden“ ⚠ RIS-Detailverifikation; lb-dvh-01: Epidemiegesetz-Entgeltfortzahlung ohne §-Zitat ⚠; lb-dvh-04 (Streik) ❓: Entgeltanspruch streikferner Arbeitnehmer bei AG-zurechenbarem Streik laut Quelle mangels Grundlagen/Praxis ausdrücklich ungeklärt; Abzug überlassener Arbeitskräfte bei Streikbeginn (Lehre ja, keine Rsp); lb-efz-02: Quelltext ohne DB/DK-Aliquotierung (flat rule: voll DB-, DZ- und Kommunalsteuerpflicht), Zeitachse komplementär ✅ zu lb-zus-05 („Initiativantrag 16.12.2025“ = BGBl I 2026/4); asc-14/15: Export-Link „siehe hier“ (AUVA-Zuschuss Kleinbetriebe) ohne Ziel — nicht rekonstruiert; asc-14 Quell-Slip „der Arbeiter“ im AngG-Absatz in der Kuratierung richtig gestellt.
• Nicht im Korpus enthalten und deshalb ❓/Beschaffungskandidaten für Folgebatches: Bildungskarenz/Beihilfen-Beitrag (Verweis in lb-tzb-01), Personalrabatte bis 2015 (lb-sac-02), Telearbeitspauschale (lb-sac-15), Begünstigt behinderte Arbeitnehmer / Belästigung / Prämien bei Beendigung (beh-/prm-Cluster), Leitende Angestellte in der Rechtsprechung (lb-lei-01), Abfertigung Alt / Verfügungsmöglichkeiten über die Abfertigung Neu (lb-vor-10), Corona-Kurzarbeit (lb-vor-03), pfändungsrechtliche Behandlung von Sonderzahlungen (lb-pfa-05), Rückzahlung von Darlehen / Mustervereinbarung Darlehen (lb-lvr-02), Entgeltfortzahlung an Feiertagen (lb-rhz-01), Motivkündigung (lb-rhz-04), Gefahrenevaluierung und Arbeitsverbote (lb-sch-01), Muster/Checklisten der Briefings generell. Mit Batch 3/4/5/6 geschlossen: „Sonderzahlungen – Steuer“ (lb-prm-04 → lb-son-04), „Darlehen und Vorschüsse“ (lb-sac-13 → lb-lvr-02), „Lohnzettel und Beitragsgrundlagennachweis“ (lb-sac-21 → lb-lvr-05), „Jugendliche – Arbeitszeit“ (lb-jug-04/lb-jug-05 → lb-jug-08), „Aufzeichnungspflicht, Formen der Zeiterfassung“ (lb-jug-05 → lb-zer-01/02), „Belästigung“ (lb-beh-04 → lb-glb-03) — Querverweise jeweils nachgetragen; „Gefahrenevaluierung und Arbeitsverbote“ teilweise via lb-sch-01 → lb-asc-01. Mit Batch 7 geschlossen: „Entgeltfortzahlung an Feiertagen“ (lb-rhz-01 → lb-efz-01/02), „Bildungskarenz“ (Verweis in lb-tzb-01 → kzs-Cluster), „Abfertigung Alt“ (→ lb-kar-01), „Gefahrenevaluierung und Arbeitsverbote“ (lb-sch-01 → lb-sch-04), „Telearbeit“ (→ tel-Cluster lb-tel-01…06); zudem prd-Cluster (Präsenzdienst/ Zivildienst) und pfl-Cluster (Pflegefreistellung) neu erschlossen.
• Copilot-Deployment (❓ offen): Layer-1-Volltexte sind nicht im Repo-Verteilungsumfang (Lizenz) — Bereitstellungspfad für RAG/Skills muss separat lizenkonform geregelt werden.
• Dossier-Stil-Exporte (pra-Cluster): Breadcrumb kann mit Fließtext in einer Zeile stehen, Footer („Page n“, „Erstellt von …“) im Text — Parser behandelt das, Kuratierung muss es ignorieren.

Weitere Workflows

(SV-Werte/TASY-Import und GemBG-Katalog siehe tools/-Docstrings und docs/CHANGELOG.md; hier ergänzen, wenn sich wiederholende Beobachtungen zeigen.)