odoo-at-payroll/.agents/skills/payroll/SKILL.md

---
name: payroll
description: |
  Guidance for implementing Austrian payroll on the Odoo 19 hr_payroll
  engine: Bgld. GemBG 2014 besoldung (Entlohnungsgruppen/-stufen,
  quarterly Sonderzahlung), Lohnsteuer, SV/Dienstgeberbeitrag, the
  shared AT core module l10n_at_hr_payroll, VRV account posting via the
  gem360 bridge module l10n_at_gemeinde_payroll_vrv, L16/eSV
  melde-dateien, annual Bezügeanpassung updates, and multi-Bundesland
  extension. Use for any work on addons/l10n_at_hr_payroll,
  addons/l10n_at_gemeinde_payroll or the legal foundations in
  personalverrechnung/.
disable-model-invocation: false
---

## Applicability

Use this skill whenever work touches the Austrian payroll localization or
its foundations: the core module `addons/l10n_at_hr_payroll` (SV values,
TASY import, upcoming Lohnsteuer/Meldewesen/Belege), the municipal module
`addons/l10n_at_gemeinde_payroll` (Bgld. GemBG besoldung, payslip
structures/salary rules), Lohnsteuer, SV/DB contributions, payroll
reports and melde-dateien (L16, eSV/ELDA), annual value updates
(Bezügeanpassung), or extending the payroll to another Bundesland or to
the general private economy (`l10n_at_hr_payroll_private`).

Skills do not replace the mandatory `AGENTS.md` workflow. For payroll
work, combine this skill with:

- `odoo19-development/SKILL.md` (always);
- for GL posting / VRV work on the bridge module
  `l10n_at_gemeinde_payroll_vrv` (which lives in the gem360 repository),
  additionally consult the gem360 repo's `odoo19-accounting`, `vrv2015`
  and `accounting-review` skills.

## Required project sources (read before planning)

1. `personalverrechnung/PLAN-payroll-bgld.md` — project frame, scope
   variants, estimates and their revisions.
2. `personalverrechnung/RECHTSQUELLEN-Bgld.md` — the verified legal
   inventory (status marks: ✅ verified / ⚠ plausible / ❓ open).
   Treat these marks as binding: never code a ❓ value without
   resolving it against a primary source first.
3. `personalverrechnung/ANGEBOTS-KALKULATION-Bgld-Personalverrechnung.md`
   — approved scope (APs), Prämissen P1–P10, options and exclusions.
   Changes that violate a Prämisse or an exclusion need explicit user
   approval first.
4. Raw legal material (local, not versioned): `.firecrawl/` contains
   the consolidated Bgld. GemBG 2014, GemBÜG 2014, the 2026
   Bezügeanpassung tables (RV 0715), official SV-Werte 2026, and
   ASVG/FLAG extracts. If `.firecrawl/` is missing, re-fetch from RIS
   (ris.bka.gv.at) and sozialversicherung.at before working from
   memory.
5. `personalverrechnung/RECHTSQUELLEN-Privat.md` — the verified legal
   inventory for the General-AT private-economy product
   (`l10n_at_hr_payroll_private`), GP0 2026-09. Binding for any
   private-economy work: § 67 EStG for begünstigte Bezüge, § 6 UrlG
   for Urlaubsentgelt, BMSVG Anwartschaft model for EOSB, § 41 FLAG
   and KommStG for the private Dienstgeberabgaben.

## Legal model (Burgenland — verified 2026-09)

- **One single legal source for the running payroll:** Bgld. GemBG 2014
  (LGBl. Nr. 42/2014). All Gemeindebedienstete hold privatrechtliche
  Dienstverhältnisse; no new öffentlich-rechtliche Dienstverhältnisse
  (§ 1 Abs 3), no Kollektivvertrag, no AZG/UrlG/AngG/ATV references.
  The GemBG itself governs Dienstzeit (40 h, § 33), Urlaub (28/33
  Arbeitstage, §§ 92–94), Abfertigung (§ 130), Karenz (§§ 106 ff. with
  Bgld. MVKG, LGBl. 16/2005).
- **Besoldung ab 1. 1. 2021** (IVa. Hauptstück, §§ 132 ff):
  Entlohnungsgruppen, Entlohnungsstufen, Besoldungsdienstalter,
  Vorrückungen; Zulagen incl. Kinderzulage (uncut for part-time),
  Funktions-/Erschwernis-/Journaldienst-/Sonn-Feiertags-/Bereitschafts-
  components (§§ 61–63, 74–87).
- **Sonderzahlung is quarterly:** 50 % of the Monatsentgelt (incl.
  Kinderzulage) per Kalendervierteljahr — not a classic 13th/14th.
  The lohnsteuerliche mapping to begünstigte Bezüge runs via **§ 67
  EStG** (GP0 2026-09 verified: § 67 = sonstige Bezüge fixed rates;
  § 68 EStG only covers Zulagen/Zuschläge free limits); the detailed
  LStR-2002 interpretation of the quarterly SZ remains an open point
  (see below).
- **€ values come from annual Bgld. Bezügeanpassungs-Sammelgesetzen**
  (tables in Anlagen/§-Ersetzungen; 2026: RV 0715/XXIII. GP / LGBl.
  50/2026) — never from a KV catalog, never hard-coded from a prior
  year.
- **Out of GemBG scope:** Lehrlinge (§ 1 Abs 2 Z 1), Gemeindeorgane
  (Bürgermeisterbezüge per Gemeindegesetz/Bgm-PensionsG 1979), Freie
  Städte Eisenstadt/Rust (Hauptstück VI Sonderregeln).
- **Federal law supplies:** EStG (§ 33 tariff, § 68 Pauschalbesteuerung,
  § 84 Lohnzettel/L16), LStR 2002 (findok), ASVG contributions and
  limits (values: annual "Beitragsrechtliche Werte" PDF,
  sozialversicherung.at), öffentlicher FLAF-Dienstgeberbeitrag
  (§ 49a ASVG), KommStG exemption for the municipality's own employees,
  Meldewesen (FinanzOnline, ELDA/eSV).

## Architecture rules

- Build strictly on the Odoo 19 `hr_payroll` engine: structures per
  employee group, salary rules, rule parameters. No parallel engine,
  no side tables for entitlements that the engine can express.
- **Shared federal core:** sector-neutral rules and values (Lohnsteuer,
  SV/DB, Meldewesen, Belege, annual values) live in
  `l10n_at_hr_payroll`; both the municipal module and the future
  general product consume the core. Never fork core values.
- Annual and legal values (LSt tariff, SV rates, limits,
  Bezügeanpassung tables) live in `hr.rule.parameter` data or
  equivalent data files — never as literals inside rule code.
- Per-Bundesland separation from day one: katalog data, structures and
  state-specific rules go into clearly separated data/models (Bgld.
  first). A follow-up Bundesland must be expressible as data plus few
  specific rules, not as a rewrite.
- GL posting via `hr_payroll_account` into VRV accounts (Anlage 3b
  Klassen 4/5/6) with Ansatz/MVAG attribution happens **in the gem360
  repository** via the bridge module `l10n_at_gemeinde_payroll_vrv`
  (depends on this repo's `l10n_at_gemeinde_payroll` plus gem360's
  `l10n_at_vrv2015`, EHH/FHH behaviour, provisions with
  Rückstellungskonten and reconciliation anchors Anlage 1a/2a). This
  repo stays free of any VRV dependency.
- Meldewesen is **file-based**: produce validated L16 (FinanzOnline)
  and eSV/ELDA-XML export files plus Prüfprotokolle. Transmission,
  certificates and Behördenkonten remain with the client or their tax
  advisor (Prämisse P7) — do not build transmission infrastructure
  without explicit approval.

## Verify before assuming (open points — resolve via RIS/findok)

- Öffentlicher FLAF-Dienstgeberbeitrag: exact current rate
  § 49a Abs 8/9 ASVG (historisch 4,5 %).
- KommStG 1993 § 6 (own employees exempt) — confirm the text.
- Bgld. MVKG full text (RIS-GesNr 20000326) for Karenz/MSchG details.
- Quartalsweise Sonderzahlung ↔ LSt begünstigte Bezüge (LStR 2002).
- Personalvertretungsumlage/AK-Umlage question for GemBG-Bedienstete;
  Krankengeldumlage (§ 62 ASVG) for public employers; SV-Träger
  confirmation (ÖGK Bgld.) from the client's payroll history.

Any further legal value must be taken from
`personalverrechnung/RECHTSQUELLEN-Bgld.md` or its named primary
sources (RIS, sozialversicherung.at, usp.gv.at, findok). If a value is
not verified there, stop and resolve it first — do not use training
knowledge for legal numbers.

## Annual change management (Wartung)

Each calendar year: fetch the new Bgld. Bezügeanpassung tables, the
SV-Werte PDF and LSt parameter changes; update rule-parameter data;
run the regression suite; document in `docs/CHANGELOG.md` and in
`personalverrechnung/` notes.

## Testing

- Rule-level unit tests for every GemBG, Lohnsteuer and SV component,
  including Rechenfälle for Eckfälle: Ein-/Austritt im Monat,
  Teilzeit/Herabsetzung, quartalsweise SZ, Geringfügigkeit, Karenz,
  Jubiläumszuwendung, Über-/Mehrdienstleistung.
- Golden-Master against the client's reference runs as soon as they
  exist (Angebotsphase: none available — see Prämissen P1/P10); the
  contracted Parallellauf (2–3 months) is part of acceptance.
- Municipal GL posting tests live with the bridge in the gem360 repo
  and must reconcile payroll postings against the Anlage-1a/2a engines
  of `l10n_at_vrv2015` there.