PLAN-leave-payroll-fixes.md

Overview

This plan addresses two critical issues reported by the client:

Leave Balances Inconsistency: When manual adjustments (like less 3 days) or carried forward leaves are applied to an employee's leave balance, they are ignored or wiped out upon leave application approval.
Automated/Random Payroll Adjustments: During payroll runs, unexpected adjustments (such as -₱647.50) are seen on employees (e.g. Princess Rose Acosta) even when no adjustments were manually added for that cutoff.

WEB (Laravel / Inertia / React)

Leave balance remaining days are always calculated as: (allocated_days + carried_forward + manual_adjustment) - used_days.
Approving or rejecting leave applications correctly updates the remaining days using the unified calculation method instead of overriding it.
The source of unexpected/random payroll adjustments is identified, and resolved so they do not populate automatically.
All feature tests for leaves and payroll pass.

Agent: backend-specialist
Skill: clean-code
Description: Update the updateLeaveBalance method in app/Models/LeaveApplication.php to call the unified calculateRemainingDays() method instead of the hardcoded allocated_days - used_days calculation.
Input: app/Models/LeaveApplication.php
Output: Updated app/Models/LeaveApplication.php
Verify: Inspect updateLeaveBalance method to ensure it calls $leaveBalance->calculateRemainingDays(). [x] Done.

Agent: backend-specialist
Skill: clean-code
Description: Audit the store, update, and adjust methods in app/Http/Controllers/LeaveBalanceController.php to ensure they consistently call calculateRemainingDays() and save the model correctly.
Input: app/Http/Controllers/LeaveBalanceController.php
Output: Cleaned and consistent controller code.
Verify: Review calculations inside the controller to prevent manual override logic. [x] Done.

Agent: test-engineer
Skill: testing-patterns
Description: Create a test in tests/Feature/LeaveBalanceAdjustmentTest.php that sets up a leave balance with manual adjustments and carried forward leaves, approves a leave application, and asserts that the remaining balance matches the correct formula.
Input: Test suite.
Output: tests/Feature/LeaveBalanceAdjustmentTest.php
Verify: Run ./vendor/bin/pest tests/Feature/LeaveBalanceAdjustmentTest.php and verify it passes. [x] Done.

Agent: frontend-specialist
Skill: frontend-design
Description: Verify if the adjustments column in the React page is misaligned or shifted in Inertia prop delivery.
Input: resources/js/pages/hr/payroll-runs/show.tsx
Output: Verified mapping or alignment fix in the React template.
Verify: Ensure that the adjustments columns match the database entries for the respective employees. [x] Done.

Agent: backend-specialist
Skill: clean-code
Description: Ensure that when a payroll run is processed, any existing entries or adjustments are cleaned up or not carried over unless explicitly requested.
Input: app/Models/PayrollRun.php
Output: Secured payroll generation logic.
Verify: Test processing a run multiple times and verify that adjustments do not replicate or cross-populate. [x] Done.