[ADD] odoo-at-payroll: repo bootstrap (AGENTS, skills, README, CHANGELOG, private skeleton)

.agents/skills/payroll/SKILL.md

@@ -0,0 +1,151 @@
+---
+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.
+
+## 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 (§ 68 Abs 5/6 EStG)
+  is a designated 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.