hr_lite 0.23.1 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f73917345c95226e4a223cbe4e3e13b4819e4ca6ea3831cbc4c129eff64bbe1
-  data.tar.gz: '03581e4aa969660467a7b7ecfd04938677398dbf57fe49b43beaee3b82c635e9'
+  metadata.gz: 3323d772472049e0607345bdd5443230a8976239aae71e4ebc2bb1dcb414380f
+  data.tar.gz: 1f83df9c391642235c7da41b913757564b2ad9d60069c52ff06a6143fef18d06
 SHA512:
-  metadata.gz: ce7315e67fa6cafd5beb9cba391e05545281e3d4af17bf1ef27576cbccef1195e0b6788f80cc9c702de68bbed0e1e9a1d754bb175f1557d8023932c22073cb66
-  data.tar.gz: 73934a9be7d733498691e8f35cf6705501992a28163040133165e599287793e0810ca194f6b0e744ab23f6dee9c4742f3a957e1a30efb4672dc3a9451e5828e8
+  metadata.gz: d64948ae1e08cdaed32254dcc70541c98cf7ed4daa0c5726b0977c1eaf615953bc267313df369fc7fc53a0f38df595f52c6f584df8b1ddd98a7bd9ecf201e61f
+  data.tar.gz: ff03f9c30cad45019ccc7404d5fffffcaf0240b63b9028ee8ddcaff4f5dfd1e0030906b506a07cd716afd2f70e44e13ef296626691478d36bbbab4b316a8a813

data/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.25.0] - 2026-10-10
+
+Three migrations: `senior` and `landlord_pan` (encrypted) on declaration lines; a data migration adding the FY 2026-27 and October 2026 rate cards to installs that already have cards; a data migration giving HR `tax.view` and `tax.manage` (all).
+
+### Added
+- Statutory cards ship for FY 2026-27 (Finance Act 2026 left slabs, standard deduction and the §87A rebate unchanged; the Income-tax Act 2025 is in force) and from 1 October 2026, when the EPF/EPS/EDLI wage ceiling rose to ₹25,000 (Notification S.O. 5109(E), 17 Sep 2026; applied from October payroll, so September stays on ₹15,000). Both are seeded already verified, with the source in the card's notes. Cards may now take effect on the 1st of any month for a change notified mid-year. `StatutoryRateCard::SOURCES`.
+- `HrLite::TaxComputation`: a person's income tax worked out now — the structure in force, the slips already paid and the declaration — for both regimes, using payroll's own TDS calculator. Each step is shown: salary paid and expected, HRA exemption, standard deduction, every deduction with what was claimed, what counts and the limit, taxable income, each slab, tax with rebate and cess, TDS deducted and each remaining month. `Calculators::Tds.slab_rows`.
+- The legal limits apply by themselves (old regime): Sec 123 / 80C ₹1,50,000, Sec 124 / 80CCD(1B) ₹50,000, home-loan interest ₹2,00,000, Sec 126 / 80D ₹25,000 or ₹50,000 for a senior — now with a separate line for parents. HRA is the least of the HRA received, rent less 10% of Basic and 50% (metro) / 40% of Basic. A landlord's PAN is required above ₹1,00,000 of rent. Payroll's TDS uses the same capped figures.
+- Proof on every declaration line: PDF, JPG or PNG up to 5 MB each. HR opens each file through an audited download (`tax_proof.downloaded`) and can "Accept all and verify" in one click.
+- The employee's Tax page leads with this year's tax, TDS a month, deducted and still to deduct, the two regimes side by side with the cheaper one named, and the full working. It re-works the tax as you type (`POST /tax_declaration/preview`, `hr_lite/tax_preview.js`), nothing saved; each line's limit bar follows the amount.
+- HR and admin: the full working on every declaration, both regimes; "Everyone's tax" (`/admin/tax_declarations/overview`) lists each person's regime, tax, TDS so far and a month, the cheaper regime, and declaration status; each name opens that person's working whether or not they filed. HR gets a "Tax checks" link under Manage.
+
+### Changed
+- Section labels name the Income-tax Act 2025 section beside the old one ("Sec 123 (old 80C) — …").
+- A claim above its legal limit no longer lowers TDS beyond the limit.
+
+## [0.24.0] - 2026-10-10
+
+Three migrations: `annual_ctc` (encrypted) and `metro` on salary structures; `first_approved_by_id`, `first_approved_at` and `auto_approved_at` on payroll runs; and a data migration granting the new `payroll.approve` permission to HR and Super Admin, plus `payroll.view`, `salary.view`, `salary.manage` and `profile.manage` to HR. Schedule `HrLite::PayrollAutoApproveJob` on the 3rd.
+
+### Added
+- Salary structures take the Annual CTC only. Saving splits it — Basic 50% of CTC (the labour codes' wage floor), HRA 50% of Basic for a metro (new "Works in a metro" box) and 40% elsewhere, employer PF, ESI and gratuity (4.81% of Basic) inside the CTC, special allowance the rest — and stores the CTC, encrypted. The form shows the monthly split read-only; Basic, HRA, special and other are no longer typed. Existing structures keep their numbers until next saved, and their CTC is unchanged (gratuity is counted only on a CTC-split structure). `SalaryStructure::GRATUITY_RATE`, `#gratuity`.
+- Payroll needs two approvals: anyone with `payroll.approve` approves a reviewed run (Approve), and a second, different person — one of the two able to run payroll — approves it again, which finalizes and publishes it. Recomputing clears the first approval. The run page says who approved and what is left. Approvers without `payroll.manage` (HR) get a "Payroll approval" link under Manage, read every run and approve, but cannot compute, unlock or delete.
+- `HrLite::PayrollAutoApproveJob`: on the 3rd, a run still in review is approved and published by the system (`auto_approved_at`, audit `payroll.auto_approved`), unless it has blocking warnings — no salary structure for someone, a state with no PT slabs, or a statutory rate card that is last year's or not yet verified — when approvers hear `payroll.overdue` instead.
+- Payroll warns when leave or attendance fixes for the month are still pending: they are paid as loss of pay until approved.
+
+### Changed
+- HR (role defaults and, on existing installs, the data migration) can now set salary structures, read and approve payroll, and edit employee profiles — which includes the screens gated on `profile.manage`: employees, resignations, awards, leave types, holidays, offices, company settings and the audit trail. Roles stay `role.manage`.
+- Salary structures are gated on `salary.manage` (was `payroll.manage`), and the employee page shows them to `salary.view`.
+- The single-person Finalize button and route are gone: a run is finalized by its second approval. Publish stays for a run unlocked and re-approved.
+- `PayrollAutoDraftJob` notifies `payroll.approve` holders as well as `payroll.manage`.
+
+## [0.23.2] - 2026-10-10
+
+No migrations.
+
+### Added
+- Timeline "Private records" card: a Leave balance line per leave type for the current leave year ("Casual leave · 7 of 10 left"), and pending or rejected leave requests ("Casual leave — pending"), for the employee and anyone `leave.view` reaches (their manager, HR). `leave_requests/_balance_chips` takes optional `user:` and `bare:` locals.
+
 ## [0.23.1] - 2026-10-10
 
 No migrations.

data/README.md

@@ -381,7 +381,8 @@ whatever you run). Each is idempotent and sends nothing on a quiet day.
 | Job | Schedule | Purpose |
 |---|---|---|
 | `HrLite::DailyDigestJob` | each morning | Leadership digest: who is out today, pending approvals, flagged punches, missing checkouts |
-| `HrLite::PayrollAutoDraftJob` | monthly, on the 1st | Draft and compute the previous month's payroll from attendance, then notify leadership for review (publishing stays a human action) |
+| `HrLite::PayrollAutoDraftJob` | monthly, on the 1st | Draft and compute the previous month's payroll from attendance, then notify the approvers (`payroll.approve`) and payroll operators |
+| `HrLite::PayrollAutoApproveJob` | monthly, on the 3rd | Approve and publish last month's run if nobody finished approving it — unless it has blocking warnings (no salary structure, no PT slabs, a stale or unverified statutory card), when the approvers are told it is overdue instead |
 | `HrLite::LeaveYearRolloverJob` | leave year's first day (Jan 1, or Jul 1 for a July–June year) | Materialize carry-forward into the new year's balances |
 | `HrLite::AttendanceCloseJob` | each night, `55 23 * * * Asia/Kolkata` | Close the day: an open punch is checked out at 23:59 and marked half day; a run before noon (a retry, or a morning schedule that lets night shifts check out first) closes the previous day instead; nobody checked in stays absent. Each is emailed how to fix it. Skips weekends, holidays and approved leave. Run it once a day — a re-run tells the no-shows again. |
 

data/app/assets/javascripts/hr_lite/tax_preview.js

@@ -0,0 +1,38 @@
+// Live tax: a form with data-hrl-tax-preview="<url>" posts what is on screen
+// (files left out) as it is typed, and the server's worked-out tax replaces
+// #hrl-tax-preview. Nothing is saved; the Save button still does that.
+(function () {
+  "use strict";
+  var form = document.querySelector("form[data-hrl-tax-preview]");
+  var panel = document.getElementById("hrl-tax-preview");
+  if (!form || !panel) return;
+
+  var timer;
+  function refresh() {
+    var data = new FormData(form);
+    Array.from(data.keys()).forEach(function (key) { if (/\[proofs\]/.test(key)) data.delete(key); });
+    data.delete("_method");
+    fetch(form.dataset.hrlTaxPreview, { method: "POST", body: data, credentials: "same-origin", headers: { "Accept": "text/html" } })
+      .then(function (response) { return response.ok ? response.text() : null; })
+      .then(function (html) { if (html) panel.innerHTML = html; });
+  }
+  var rupees = new Intl.NumberFormat("en-IN", { style: "currency", currency: "INR", maximumFractionDigits: 0 });
+  // The limit bar and "₹X of the ₹Y limit counts" follow the amount as typed.
+  function updateCap(input) {
+    var field = input.closest(".hrl-field");
+    var hint = field && field.querySelector("[data-hrl-cap]");
+    if (!hint) return;
+    var cap = Number(hint.dataset.hrlCap);
+    var counts = Math.min(Math.max(Number(input.value.replace(/[^0-9.]/g, "")) || 0, 0), cap);
+    field.querySelector("progress").value = counts;
+    hint.textContent = rupees.format(counts) + " of the " + rupees.format(cap) + " limit counts";
+  }
+  function schedule(event) {
+    if (event.target.type === "file") return;
+    if (/declared_amount/.test(event.target.name)) updateCap(event.target);
+    clearTimeout(timer);
+    timer = setTimeout(refresh, 400);
+  }
+  form.addEventListener("input", schedule);
+  form.addEventListener("change", schedule);
+})();

data/app/assets/stylesheets/hr_lite/hr_lite.css

@@ -318,7 +318,8 @@ summary.hrl-btn::-webkit-details-marker { display: none; } /* Safari before 18.4
 
 /* Forms */
 .hrl-field { margin-bottom: .8rem; }
-.hrl-field label { display: block; font-size: var(--hrl-t-small); font-weight: 600; margin-bottom: .3rem; }
+.hrl-field label, .hrl-field legend { display: block; font-size: var(--hrl-t-small); font-weight: 600; margin-bottom: .3rem; }
+fieldset { border: 0; margin: 0; padding: 0; min-width: 0; }
 .hrl-hint { color: var(--hrl-muted); font-size: var(--hrl-t-small); margin-top: .25rem; }
 /* Full-width text-ish controls only — checkboxes/radios/hidden must keep
    their natural size (a bare [type] selector out-ranked .hrl-field--check
@@ -390,6 +391,16 @@ summary.hrl-btn::-webkit-details-marker { display: none; } /* Safari before 18.4
 .hrl-card--private .hrl-timeline__item::before { background: var(--hrl-bg); border: 2px solid var(--hrl-field); }
 .hrl-card--private .hrl-badge--muted { background: var(--hrl-card); }
 
+/* Tax: the two regimes side by side, then the working as a plain table. */
+.hrl-tax-compare { display: grid; grid-template-columns: 1fr 1fr; gap: var(--hrl-s-3); margin: var(--hrl-s-4) 0 var(--hrl-s-2); }
+.hrl-tax-compare__col { border: 1px solid var(--hrl-line); border-radius: var(--hrl-radius-sm); padding: var(--hrl-s-3); min-width: 0; }
+.hrl-tax-compare__col--chosen { border: 2px solid var(--hrl-accent); }
+.hrl-tax-compare__amount { font-size: var(--hrl-t-title); font-weight: 700; margin-top: var(--hrl-s-1); overflow-wrap: anywhere; }
+.hrl-tax-working { margin-top: var(--hrl-s-3); }
+.hrl-tax-working__table td { vertical-align: top; overflow-wrap: anywhere; }
+.hrl-tax-working__total td { font-weight: 700; border-top: 1px solid var(--hrl-line); }
+.hrl-tax-cap { display: block; width: 100%; height: 8px; margin-top: var(--hrl-s-1); accent-color: var(--hrl-accent); }
+
 /* Mention autocomplete menu */
 .hrl-mention-wrap { position: relative; }
 .hrl-mention-menu {

data/app/controllers/hr_lite/admin/payroll_runs_controller.rb

@@ -1,6 +1,9 @@
 module HrLite
   module Admin
     class PayrollRunsController < SuperadminController
+      # Approvers (HR) read runs and approve them without running payroll.
+      skip_before_action :require_money_access!, only: %i[index show approve]
+      before_action :require_approver_or_money!, only: %i[index show approve]
       # The register carries every bank account: its own key, not just payroll.manage.
       before_action -> { hr_require_permission!("payroll.export", scope: :all) }, only: :register
       def index
@@ -41,8 +44,8 @@ module HrLite
         transition { |run| run.compute!(actor: hr_current_user) && "Computed — review the slips." }
       end
 
-      def finalize
-        transition { |run| run.finalize!(actor: hr_current_user) && "Run finalized." }
+      def approve
+        transition { |run| run.approve!(actor: hr_current_user) && (run.published? ? "Second approval — run finalized and published." : "Approved — one more approver publishes it.") }
       end
 
       def unlock
@@ -74,12 +77,19 @@ module HrLite
 
       private
 
+      def require_approver_or_money!
+        return if hr_can?("payroll.manage", scope: :all)
+
+        hr_require_permission!("payroll.approve", scope: :all)
+      end
+
       def transition
         run = PayrollRun.find(params[:id])
         notice = yield(run)
         redirect_to admin_payroll_run_path(run), notice: notice
-      rescue ActiveRecord::RecordInvalid
-        redirect_to admin_payroll_run_path(run), alert: "That step is not available from #{run.status}."
+      rescue ActiveRecord::RecordInvalid => e
+        alert = e.message.match?(/approver/) ? e.message.sub(/\AValidation failed: /, "").capitalize + "." : "That step is not available from #{run.status}."
+        redirect_to admin_payroll_run_path(run), alert: alert
       end
 
       def register_csv(run)

data/app/controllers/hr_lite/admin/salary_structures_controller.rb

@@ -1,6 +1,9 @@
 module HrLite
   module Admin
+    # salary.manage, not payroll.manage: HR sets structures without running payroll.
     class SalaryStructuresController < SuperadminController
+      skip_before_action :require_money_access!
+      before_action -> { hr_require_permission!("salary.manage", scope: :all) }
       before_action :set_profile
 
       def new
@@ -12,9 +15,7 @@ module HrLite
         @structure = SalaryStructure.new(structure_params.merge(
           user_id: @profile.user_id, created_by_id: hr_current_user.id
         ))
-        return fill_from_ctc(:new) if params[:fill_from_ctc]
-
-        if @structure.save
+        if @structure.save(context: :ctc_form)
           redirect_to admin_employee_path(@profile), notice: "Salary structure saved."
         else
           render :new, status: :unprocessable_entity
@@ -28,9 +29,7 @@ module HrLite
       def update
         @structure = SalaryStructure.where(user_id: @profile.user_id).find(params[:id])
         @structure.assign_attributes(structure_params)
-        return fill_from_ctc(:edit) if params[:fill_from_ctc]
-
-        if @structure.save
+        if @structure.save(context: :ctc_form)
           redirect_to admin_employee_path(@profile), notice: "Salary structure updated."
         else
           render :edit, status: :unprocessable_entity
@@ -39,22 +38,13 @@ module HrLite
 
       private
 
-      # Shows the split for a check; only the Save button writes it.
-      def fill_from_ctc(view)
-        @structure.fill_from_ctc
-        return render(view, status: :unprocessable_entity) unless @structure.valid?
-
-        flash.now[:notice] = "Filled from CTC — check the lines, then Save."
-        render view
-      end
-
       def set_profile
         @profile = EmployeeProfile.find(params[:employee_id])
       end
 
       def structure_params
         params.require(:salary_structure).permit(
-          :annual_ctc, :effective_from, :basic, :hra, :special_allowance, :other_earnings,
+          :annual_ctc, :effective_from, :metro,
           :pf_applicable, :pf_on_full_basic, :esi_applicable, :pt_state, :notes
         )
       end

data/app/controllers/hr_lite/admin/tax_declarations_controller.rb

@@ -17,6 +17,51 @@ module HrLite
 
       def show
         @declaration = find_visible
+        @tax = TaxComputation.new(user: @declaration.user, declaration: @declaration)
+      end
+
+      # Everyone's tax this year, worked out now, whether or not they declared.
+      def overview
+        visible = hr_access.visible_user_ids("tax.view")
+        profiles = EmployeeProfile.active_for(Date.current).includes(:user).order(:employee_code)
+        profiles = profiles.where(user_id: visible) if visible
+        @profiles = paginate(profiles)
+        @declarations = TaxDeclaration.where(user_id: @profiles.map(&:user_id),
+                                             financial_year: FinancialYear.start_for(Date.current)).index_by(&:user_id)
+      end
+
+      # Anyone's full working, filed or not.
+      def person
+        @person = HrLite.user_klass.find(params[:user_id])
+        hr_require_reach!("tax.view", @person)
+        @tax = TaxComputation.new(user: @person)
+      end
+
+      # The proof, through a permission check and an audit row — never a bare blob link.
+      def proof
+        declaration = find_visible
+        file = declaration.tax_declaration_items.flat_map { |item| item.proofs.to_a }.find { |p| p.id == params[:proof_id].to_i }
+        raise ActiveRecord::RecordNotFound unless file
+
+        AuditLog.record!(action: "tax_proof.downloaded", subject: declaration, actor: hr_current_user,
+                         changes: { "file" => file.filename.to_s, "owner" => HrLite.display_name(declaration.user) })
+        redirect_to Rails.application.routes.url_helpers.rails_blob_path(file, disposition: "attachment", only_path: true),
+                    allow_other_host: false
+      end
+
+      # One click when the proof matches the claim: every unchecked line is
+      # accepted at what was claimed (the legal limit still applies), then verified.
+      def accept_all
+        declaration = find_manageable
+        TaxDeclaration.transaction do
+          declaration.tax_declaration_items.each do |item|
+            item.update!(verified_amount: item.declared_amount) if item.verified_amount.nil?
+          end
+          declaration.verify!(actor: hr_current_user, note: "Proof accepted")
+        end
+        redirect_to admin_tax_declarations_path, notice: "Accepted and verified — payroll uses these amounts now."
+      rescue ActiveRecord::RecordInvalid
+        redirect_to admin_tax_declaration_path(declaration), alert: "Only a submitted declaration can be accepted."
       end
 
       def update
@@ -26,6 +71,7 @@ module HrLite
         if @declaration.update(verification_params)
           redirect_to admin_tax_declaration_path(@declaration), notice: "Amounts recorded."
         else
+          @tax = TaxComputation.new(user: @declaration.user, declaration: @declaration)
           render :show, status: :unprocessable_entity
         end
       end

data/app/controllers/hr_lite/tax_declarations_controller.rb

@@ -8,6 +8,16 @@ module HrLite
       # A saved draft holds only its claims; the rest still need a line to fill.
       fill_missing_sections(@declaration)
       @regime = @declaration.regime
+      @tax = TaxComputation.new(user: hr_current_user, declaration: @declaration)
+    end
+
+    # The form posts here as it is typed in: the tax worked out on what is on
+    # screen, nothing saved.
+    def preview
+      declaration = current_declaration || TaxDeclaration.new(user_id: hr_current_user.id, financial_year: financial_year)
+      declaration.regime = declaration_params[:regime] if declaration_params[:regime]
+      declaration.tax_declaration_items_attributes = preview_items
+      render partial: "hr_lite/tax/computation", locals: { tax: TaxComputation.new(user: hr_current_user, declaration: declaration), both: false }
     end
 
     def update
@@ -32,6 +42,7 @@ module HrLite
         # Re-render needs the full set of lines back, or the form loses the
         # sections the person had not filled in yet.
         fill_missing_sections(@declaration)
+        @tax = TaxComputation.new(user: hr_current_user, declaration: @declaration)
         render :show, status: :unprocessable_entity
       end
     end
@@ -75,6 +86,13 @@ module HrLite
       end
     end
 
+    # Lines for a preview: amounts only, never files (a blanked line is marked
+    # for removal, which the computation skips). Already filtered by the
+    # permit in declaration_params, so plain hashes are safe here.
+    def preview_items
+      (declaration_params[:tax_declaration_items_attributes] || {}).to_unsafe_h.transform_values { |row| row.except("proofs") }
+    end
+
     def employee_regime
       EmployeeProfile.find_by(user_id: hr_current_user.id)&.tax_regime.presence || "new"
     end
@@ -87,7 +105,7 @@ module HrLite
     def declaration_params
       permitted = params.require(:tax_declaration).permit(
         :regime,
-        tax_declaration_items_attributes: %i[id section label declared_amount _destroy]
+        tax_declaration_items_attributes: [ :id, :section, :label, :declared_amount, :senior, :landlord_pan, :_destroy, { proofs: [] } ]
       )
       items = permitted[:tax_declaration_items_attributes]
       return permitted if items.blank?

data/app/controllers/hr_lite/timelines_controller.rb

@@ -13,7 +13,8 @@ module HrLite
       @public_events = timeline.public_events
       @private_events = timeline.private_events
       # Shown only to someone who may see private rows at all: the person, or a reach-holder.
-      @private_card = @person.id == hr_current_user.id || @private_events.any?
+      @show_balance = HrLite.reaches?(hr_current_user, "leave.view", @person)
+      @private_card = @person.id == hr_current_user.id || @show_balance || @private_events.any?
     end
   end
 end

data/app/helpers/hr_lite/application_helper.rb

@@ -38,6 +38,11 @@ module HrLite
       { label: "Help desk",       path: :admin_hr_requests_path,     match: [ "/admin/hr_requests" ] },
       { label: "Assets",          path: :admin_assets_path,          match: [ "/admin/assets" ] },
       { label: "Benefits",        path: :admin_benefits_path,        match: [ "/admin/benefits" ] },
+      # HR approves payroll without running it; Super Admin reaches it under Organisation.
+      { label: "Payroll approval", path: :admin_payroll_runs_path, match: [ "/admin/payroll_runs" ],
+        if: -> { hr_can?("payroll.approve", scope: :all) && !hr_superadmin? } },
+      { label: "Tax checks", path: :admin_tax_declarations_path, match: [ "/admin/tax_declarations" ],
+        if: -> { hr_can?("tax.view", scope: :all) && !hr_superadmin? } },
       { label: "Joining & exits", path: :admin_checklists_path,      match: [ "/admin/checklists" ] }
     ].freeze
 

data/app/jobs/hr_lite/payroll_auto_approve_job.rb

@@ -0,0 +1,21 @@
+module HrLite
+  # The 3rd-of-month backstop (schedule it on the 3rd): last month's run that
+  # is still in review is approved and published by the system, unless it has
+  # blocking warnings — then the approvers are told it is overdue instead.
+  class PayrollAutoApproveJob < ApplicationJob
+    queue_as :default
+
+    def perform(month: Date.current.prev_month.beginning_of_month)
+      run = PayrollRun.find_by(period_month: month, status: "review")
+      return unless run
+      return if run.auto_approve!
+
+      people = HrLite.users_holding("payroll.approve", scope: :all).to_a
+      Notifications.publish(
+        "payroll.overdue",
+        title: "Payroll #{run.label} is overdue — not auto-approved: #{run.blocking_warnings.join('; ')}",
+        path: "/admin/payroll_runs/#{run.id}", bell_to: people, email_to: people
+      )
+    end
+  end
+end

data/app/jobs/hr_lite/payroll_auto_draft_job.rb

@@ -16,7 +16,7 @@ module HrLite
       return unless run.draft? && run.salary_slips.none?
 
       run.compute!(actor: nil)
-      payroll = HrLite.users_holding("payroll.manage", scope: :all).to_a
+      payroll = HrLite.users_holding("payroll.approve", scope: :all).to_a | HrLite.users_holding("payroll.manage", scope: :all).to_a
       Notifications.publish(
         "payroll.draft_ready",
         title: "Payroll #{run.label} computed from attendance — #{run.salary_slips.count} slips await review",

data/app/models/hr_lite/payroll_run.rb

@@ -9,6 +9,11 @@ module HrLite
     belongs_to :created_by, class_name: HrLite.config.user_class, optional: true
     belongs_to :finalized_by, class_name: HrLite.config.user_class, optional: true
     belongs_to :published_by, class_name: HrLite.config.user_class, optional: true
+    belongs_to :first_approved_by, class_name: HrLite.config.user_class, optional: true
+
+    # A run with one of these is not paid on the 3rd without a person looking:
+    # someone missing, a state levying ₹0, or last year's / unverified rates.
+    BLOCKING_WARNING = /\ANo (salary structure|professional-tax slabs)|statutory card/
 
     validates :period_month, presence: true, uniqueness: true
     validates :status, inclusion: { in: STATUSES }
@@ -40,7 +45,8 @@ module HrLite
         update!(status: "processing")
         PayrollRunProcessor.call(self)
         transaction do
-          update!(status: "review", processed_at: Time.current)
+          # New numbers: an approval of the old ones no longer counts.
+          update!(status: "review", processed_at: Time.current, first_approved_by_id: nil, first_approved_at: nil)
           audit!("payroll.computed", actor,
                  "slips" => salary_slips.count, "warnings" => warnings.length,
                  "from_status" => previous)
@@ -60,7 +66,7 @@ module HrLite
       raise ActiveRecord::RecordInvalid.new(self), "no slips" if salary_slips.none?
 
       transaction do
-        update!(status: "finalized", finalized_at: Time.current, finalized_by_id: actor.id)
+        update!(status: "finalized", finalized_at: Time.current, finalized_by_id: actor&.id)
         # Finalizing freezes every slip in the run. Who did it, to how many
         # people, is the row an investigation starts from.
         audit!("payroll.finalized", actor, "slips" => salary_slips.count)
@@ -74,6 +80,34 @@ module HrLite
       true
     end
 
+    # Two people approve a reviewed run, at least one of them able to run
+    # payroll; the second approval finalizes and publishes it.
+    def approve!(actor:)
+      raise_unless %w[review]
+      unless HrLite.can?(actor, "payroll.approve", scope: :all)
+        raise ActiveRecord::RecordInvalid.new(self), "not an approver"
+      end
+      return stamp_first_approval!(actor) if first_approved_by_id.nil?
+      if first_approved_by_id == actor.id || [ first_approved_by, actor ].none? { |u| HrLite.can?(u, "payroll.manage", scope: :all) }
+        raise ActiveRecord::RecordInvalid.new(self), "needs a second, different approver"
+      end
+
+      finalize!(actor: actor) && publish!(actor: actor)
+    end
+
+    def blocking_warnings = warnings.grep(BLOCKING_WARNING)
+
+    # The 3rd-of-month backstop: a clean run nobody finished approving is
+    # approved by the system and says so; a run with blocking warnings waits.
+    def auto_approve!
+      raise_unless %w[review]
+      return false if blocking_warnings.any?
+
+      update!(auto_approved_at: Time.current)
+      audit!("payroll.auto_approved", nil, "slips" => salary_slips.count)
+      finalize!(actor: nil) && publish!(actor: nil)
+    end
+
     def unlock!(actor:)
       raise_unless %w[finalized]
       transaction do
@@ -92,7 +126,7 @@ module HrLite
     def publish!(actor:)
       raise_unless %w[finalized]
       transaction do
-        update!(status: "published", published_at: Time.current, published_by_id: actor.id)
+        update!(status: "published", published_at: Time.current, published_by_id: actor&.id)
         audit!("payroll.published", actor, "slips" => salary_slips.count)
       end
 
@@ -145,6 +179,16 @@ module HrLite
 
     private
 
+    def stamp_first_approval!(actor)
+      update!(first_approved_by_id: actor.id, first_approved_at: Time.current)
+      audit!("payroll.approved", actor, "slips" => salary_slips.count, "step" => 1)
+      others = HrLite.users_holding("payroll.approve", scope: :all).reject { |u| u.id == actor.id }
+      Notifications.publish("payroll.approval_needed",
+                            title: "Payroll #{label}: #{HrLite.display_name(actor)} approved — one more approval publishes it",
+                            path: "/admin/payroll_runs/#{id}", bell_to: others, email_to: others)
+      true
+    end
+
     # A repayment is booked when the run is FINALIZED, never at compute: a
     # draft is recomputed as often as the operator likes, and each pass would
     # otherwise take another instalment off the loan.

data/app/models/hr_lite/salary_structure.rb

@@ -10,9 +10,15 @@ module HrLite
     belongs_to :user, class_name: HrLite.config.user_class
     belongs_to :created_by, class_name: HrLite.config.user_class, optional: true
 
-    encrypted_money :basic, :hra, :special_allowance, :other_earnings
-    # Typed on the form to fill the lines; CTC is always derived, never stored.
-    attribute :annual_ctc, :decimal
+    encrypted_money :basic, :hra, :special_allowance, :other_earnings, :annual_ctc
+
+    # Gratuity accrues at 15/26 days of Basic a year (4.81%), inside the CTC.
+    GRATUITY_RATE = BigDecimal("0.0481")
+
+    # The CTC is the input: saving one splits it, so no line is typed by hand.
+    before_validation :fill_from_ctc, if: -> { annual_ctc.present? }
+    # The admin form saves in this context: people only ever type the CTC.
+    validates :annual_ctc, presence: true, on: :ctc_form
 
     validates :effective_from, presence: true, uniqueness: { scope: :user_id }
     validates :basic, presence: true
@@ -49,7 +55,7 @@ module HrLite
       earnings, deductions, employer = [
         { "Basic" => basic, "HRA" => hra, "Special allowance" => special_allowance, "Other" => other_earnings },
         { "PF" => pf&.employee, "ESI" => esi.employee, "Professional tax" => pts.first },
-        { "PF" => pf && (pf.employer_eps + pf.employer_epf), "ESI" => esi.employer }
+        { "PF" => pf && (pf.employer_eps + pf.employer_epf), "ESI" => esi.employer, "Gratuity" => gratuity }
       ].map { |rows| rows.select { |_, amount| Money.d(amount).positive? } }
       monthly_ctc = gross + employer.values.sum(BigDecimal(0))
       in_hand = gross - deductions.values.sum(BigDecimal(0))
@@ -76,14 +82,22 @@ module HrLite
       (earlier || self).monthly_gross
     end
 
-    # Owner's split of annual_ctc: Basic 50% of the monthly CTC, HRA 40% of
-    # Basic, employer PF and ESI paid out of the CTC; Special takes the rest.
+    # Only a CTC-split structure carries gratuity in its CTC; older hand-typed
+    # ones never did, and their CTC must not move.
+    def gratuity
+      Money.round_rupee(Money.d(basic) * GRATUITY_RATE) if annual_ctc.present? && basic
+    end
+
+    # Owner's split of annual_ctc (the labour codes' 50% wage floor): Basic 50%
+    # of the monthly CTC, HRA 50% of Basic in a metro and 40% elsewhere,
+    # employer PF, ESI and gratuity paid out of the CTC; Special takes the rest.
     def fill_from_ctc(on: effective_from || Date.current)
       monthly_ctc = Money.round_rupee(Money.d(annual_ctc) / 12)
       self.basic = Money.round_rupee(monthly_ctc / 2)
-      self.hra = Money.round_rupee(basic * BigDecimal("0.4"))
+      self.hra = Money.round_rupee(basic * BigDecimal(metro ? "0.5" : "0.4"))
+      self.other_earnings = nil
       self.special_allowance = 0
-      rest = monthly_ctc - Money.d(breakup(on: on).dig(:employer, "PF"))
+      rest = monthly_ctc - Money.d(breakup(on: on).dig(:employer, "PF")) - Money.d(gratuity)
       # Employer ESI is a share of the gross beside it: gross + ESI = rest.
       gross = (rest / (1 + StatutoryRateCard.for(on.beginning_of_month)[:esi][:employer_rate])).floor
       self.special_allowance = gross - basic - hra - Money.d(other_earnings)

data/app/models/hr_lite/statutory_rate_card_record.rb

@@ -53,14 +53,14 @@ module HrLite
       hash.to_h { |key, value| [ key, Money.d(value) ] }
     end
 
-    # A card dated mid-year would mean two sets of slabs inside one financial
-    # year, and the TDS projector works on an annual figure — there is no
-    # sensible answer to "which slabs applied to this year's income" then.
+    # Cards take effect on the 1st of a month. Most open a financial year on
+    # 1 April; a mid-year card exists for a statutory change notified inside a
+    # year (the EPF wage ceiling, 17 Sep 2026) and repeats that year's tax
+    # slabs, because TDS projects one annual figure.
     def effective_from_opens_a_financial_year
-      return if effective_from.blank?
-      return if effective_from == FinancialYear.start_for(effective_from)
+      return if effective_from.blank? || effective_from.day == 1
 
-      errors.add(:effective_from, "must be 1 April — a card covers a whole financial year")
+      errors.add(:effective_from, "must be the 1st of a month (1 April for a new financial year)")
     end
 
     REQUIRED = {

data/app/models/hr_lite/tax_declaration.rb

@@ -47,6 +47,30 @@ module HrLite
       tax_declaration_items.sum(BigDecimal(0)) { |i| i.verified_amount || BigDecimal(0) }
     end
 
+    Deduction = Struct.new(:section, :label, :claimed, :allowed, :cap, keyword_init: true)
+
+    # Old-regime lines with the law applied: each section's limit, and HRA
+    # worked out from the rent against the salary structure — never typed.
+    def deduction_rows(structure:)
+      tax_declaration_items.reject { |item| item.declared_amount.nil? || item.marked_for_destruction? }.map do |item|
+        allowed = item.section == "hra" ? self.class.hra_exemption(item.allowed(verified: verified?), structure) : item.allowed(verified: verified?)
+        Deduction.new(section: item.section, label: item.section_label, claimed: Money.d(item.declared_amount),
+                      allowed: allowed, cap: item.cap)
+      end
+    end
+
+    def old_regime_deductions(structure:) = deduction_rows(structure: structure).sum(BigDecimal(0), &:allowed)
+
+    # Annual HRA exemption: the least of the HRA received, rent less 10% of
+    # Basic, and 50% of Basic in a metro (40% elsewhere).
+    def self.hra_exemption(rent, structure)
+      return BigDecimal(0) if structure.nil? || Money.d(rent).zero?
+
+      basic = Money.d(structure.basic) * 12
+      [ Money.d(structure.hra) * 12, Money.d(rent) - basic / 10, basic * BigDecimal(structure.metro ? "0.5" : "0.4") ]
+        .min.then { |amount| Money.round_rupee([ amount, BigDecimal(0) ].max) }
+    end
+
     def submit!(actor:)
       raise ActiveRecord::RecordInvalid.new(self), "not a draft" unless draft? || rejected?