hr_lite 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ddcf4d252c3b0830d1b345dd44f63dc997cab9db77a408249cd8940ad2256c1
-  data.tar.gz: d525ae88d6a0b5c12ca68caff325bb655cd2ff7dfa0ac9afb7f178cbc8d362de
+  metadata.gz: 42a084897bd2831303410129ecaa25dac81fdb97b711bfe07071cf28496d58d1
+  data.tar.gz: 014663d43940503d5fa840f5bb0460b8fd3e20bfbaf07a1aa6821b491798d16d
 SHA512:
-  metadata.gz: 155c04f716bbf5907b17ce1dd86c06f44de4f3f8021afda1e2ed3570db8cf14aed2373db7791d4c65441e96b6d4e0318faeb8dc1116b35bea235ed4cb31775d8
-  data.tar.gz: be25c7f77087ae53dccb3e991167cc78282de562c5ef9f12739db9bc2bece99ad8b1e743577dc21d3aeb935cd1ca270ae64652bd036459c8c704b438db1ed8c0
+  metadata.gz: 40177d861f9579695084b3e0bca3fefd4dd9593d430d800c7c1bfed2c88d1de4820fd12c6c816c24cf29f0d70eb8db26efe2c9cc10870ec1f9be15b262c05f1d
+  data.tar.gz: 261892abb65e4ebb80f12cdfbdf7763d2e82f9040268efa796870ec6af413cc25079e9e124536e2eb0a4e1a937e0de6a98f98fde84901248a91a3ea944f684bf

data/CHANGELOG.md

@@ -7,6 +7,67 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-08-18
+
+A reusable approval engine. **Adds one migration** (flows, steps, approvals,
+delegations). Nothing changes for a module until a flow is configured for it,
+which is what lets the four existing ones migrate one at a time.
+
+### Fixed
+
+- **Cancelling a leave request left its approval sitting in somebody's
+  inbox.** Found by the coverage floor, which flagged `cancel_all!` as
+  unreachable — it was written and never called.
+
+### Added
+
+- `HrLite::ApprovalFlow` / `ApprovalStep` / `Approval` / `ApprovalDelegation`.
+  A flow is "leave needs the manager, then HR". A step names its approver by
+  RULE — manager, manager's manager, anyone holding a permission, or one named
+  person — so a flow survives somebody leaving; the rule resolves against the
+  subject when the request is raised.
+- Multi-level, sequential routing, with a `unanimous` step for the rungs where
+  everybody has to answer rather than the first person to look.
+- **A rung nobody occupies is skipped**, not left waiting. An employee with no
+  manager recorded would otherwise have a request no living person could
+  decide.
+- **Delegation.** "I am away until the 14th — Priya decides for me." The
+  approval does not move; a stand-in may answer it, and the row records both
+  who it was addressed to and who actually decided. Two hops, so a stand-in
+  who is also away is covered, and a loop cannot hand somebody their own
+  approvals back.
+- **SLA and escalation.** A step may carry a deadline; `ApprovalEscalationJob`
+  tells an approver once per overdue row, grouped into one message per person,
+  and stamps the rows so a daily run does not nag daily. Escalation TELLS
+  somebody — it does not reassign, because a decision made by somebody who
+  never saw the request is worse than a late one.
+- **One approval inbox** (`/approvals`) replacing four places to look. Employee
+  tier: holding an approval is the authorisation, so a manager, a stand-in and
+  a director reach the same screen and each sees only their own rows. It sits
+  after Calendar in the nav — the phone tab bar shows the first four, and this
+  screen is empty for anybody who is not an approver.
+- `HrLite::Approvable` — opts a model in WITHOUT taking over what its decisions
+  mean. `LeaveRequest` keeps its own `approve!`, including the balance lock;
+  the concern only answers "is it this person's turn, and does their answer
+  settle it". A settling decision runs the ordinary transition, so routing
+  never becomes a second path that can drift from the first.
+
+### Changed
+
+- `LeaveRequest` is the first module routed. With no flow it behaves exactly
+  as before, and somebody outside the current rung who holds `leave.approve`
+  at `all` can still settle it outright — the routed path is the normal one,
+  not the only one.
+- Branch-coverage floor 90.8% -> 90.3%, deliberately, with the arithmetic
+  written into `spec_helper.rb`: the engine added ~90 branches at once, and
+  holding the percentage would have meant contriving specs for untouched
+  files. Line coverage stayed at 100%.
+
+### Not yet
+
+- Comp-off, regularization and resignation still use their own single
+  decision. They are declared approvable and migrate next, one release each.
+
 ## [0.8.0] - 2026-08-18
 
 The deprecation 0.6.0 opened, closed. **Breaking** only for an install still
@@ -549,7 +610,8 @@ Initial release.
   bus with per-event channel matrix (bell, email, leadership email/bell),
   daily leadership digest and an append-only audit trail.
 
-[Unreleased]: https://github.com/kshtzkr/hr_lite/compare/v0.8.0...HEAD
+[Unreleased]: https://github.com/kshtzkr/hr_lite/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/kshtzkr/hr_lite/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/kshtzkr/hr_lite/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/kshtzkr/hr_lite/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/kshtzkr/hr_lite/compare/v0.5.3...v0.6.0

data/app/controllers/hr_lite/approvals_controller.rb

@@ -0,0 +1,31 @@
+module HrLite
+  # Everything waiting on the signed-in person, in one place. Before this,
+  # an approver had to visit four screens to find out whether anybody was
+  # waiting on them, and nothing told them if a request had gone stale.
+  #
+  # Employee tier on purpose: holding an approval IS the authorisation. A
+  # manager, a stand-in covering for one, and a director all reach the same
+  # screen and each sees only their own rows.
+  class ApprovalsController < ApplicationController
+    def index
+      @approvals = paginate(mine.includes(:step, :subject).order(:created_at))
+      @delegations = ApprovalDelegation.live_on(Date.current)
+                                       .where(from_user_id: hr_current_user.id)
+                                       .includes(:to_user)
+      @covering_for = ApprovalDelegation.live_on(Date.current)
+                                        .where(to_user_id: hr_current_user.id)
+                                        .includes(:from_user)
+    end
+
+    private
+
+    # Rows addressed to this person, plus rows belonging to anybody who has
+    # delegated to them while they are away.
+    def mine
+      standing_in_for = ApprovalDelegation.live_on(Date.current)
+                                          .where(to_user_id: hr_current_user.id)
+                                          .pluck(:from_user_id)
+      Approval.pending.where(approver_id: [ hr_current_user.id, *standing_in_for ])
+    end
+  end
+end

data/app/helpers/hr_lite/application_helper.rb

@@ -6,6 +6,12 @@ module HrLite
       { label: "Leaves",     path: :leave_requests_path, match: [ "/leave_requests", "/leave_balances", "/comp_off_requests" ] },
       { label: "Team",       path: :team_path,           match: [ "/team" ] },
       { label: "Calendar",   path: :calendar_path,       match: [ "/calendar", "/holidays" ] },
+      # After Calendar deliberately: the phone tab bar shows the first four
+      # and this screen is empty for everybody who is not an approver, so it
+      # belongs in "More" rather than displacing something everybody uses.
+      # Employee tier all the same — holding an approval IS the authorisation,
+      # so a manager and a stand-in covering for one reach the same screen.
+      { label: "Approvals",  path: :approvals_path,      match: [ "/approvals" ] },
       { label: "Org",        path: :org_path,            match: [ "/org" ] },
       { label: "Kudos",      path: :kudos_path,          match: [ "/kudos" ] },
       { label: "Slips",      path: :salary_slips_path,   match: [ "/salary_slips" ] },
@@ -71,6 +77,21 @@ module HrLite
       out.html_safe
     end
 
+    # Where an approval row actually leads. Each subject type has its own
+    # decision screen; the inbox only gathers them.
+    APPROVAL_PATHS = {
+      "HrLite::LeaveRequest" => :admin_leave_request_path,
+      "HrLite::CompOffRequest" => :admin_comp_off_request_path,
+      "HrLite::RegularizationRequest" => :admin_regularization_request_path
+    }.freeze
+
+    def hrl_approval_path(approval)
+      helper = APPROVAL_PATHS[approval.subject_type]
+      return nil unless helper && hr_lite_route?(helper)
+
+      hr_lite.public_send(helper, approval.subject_id)
+    end
+
     def hrl_pagination
       render "hr_lite/shared/pagination"
     end

data/app/jobs/hr_lite/approval_escalation_job.rb

@@ -0,0 +1,39 @@
+module HrLite
+  # Nudges approvals that have sat past their step's SLA. Escalation here
+  # means TELLING SOMEBODY, not reassigning: silently moving a decision to
+  # another person is how an approval ends up made by somebody who never saw
+  # the request.
+  #
+  # Each row is stamped once, so a daily run does not re-nag every day.
+  class ApprovalEscalationJob < ApplicationJob
+    def perform(now: Time.current)
+      overdue = Approval.pending.where(escalated_at: nil).includes(:step, :approver)
+                        .select { |approval| approval.overdue?(now) }
+      return if overdue.empty?
+
+      overdue.group_by(&:approver_id).each do |approver_id, rows|
+        approver = rows.first.approver
+        next if approver.nil?
+
+        Notifications.publish(
+          "approval.escalated",
+          title: "#{rows.size} approval#{'s' unless rows.size == 1} waiting on you past its deadline",
+          lines: rows.map { |row| "#{row.label} — waiting #{waited(row, now)}" },
+          path: "/approvals",
+          bell_to: [ approver ],
+          email_to: [ approver ],
+          leadership: { title: "#{HrLite.display_name(approver)} has #{rows.size} overdue approval#{'s' unless rows.size == 1}" }
+        )
+      end
+
+      Approval.where(id: overdue.map(&:id)).update_all(escalated_at: now) # rubocop:disable Rails/SkipsModelValidations
+    end
+
+    private
+
+    def waited(approval, now)
+      hours = ((now - approval.created_at) / 1.hour).floor
+      hours < 48 ? "#{hours}h" : "#{(hours / 24)} days"
+    end
+  end
+end

data/app/models/concerns/hr_lite/approvable.rb

@@ -0,0 +1,48 @@
+module HrLite
+  # Opts a model into the routed, multi-step approval flow — WITHOUT taking
+  # over what its decisions mean.
+  #
+  # The model keeps its own `approve!` / `reject!`: those are the domain
+  # actions, and for leave one of them credits a balance inside a row lock.
+  # This concern only asks "is it this person's turn, and does their answer
+  # settle it?" and hands back an outcome for the model to act on.
+  #
+  # A subject type with no active flow behaves exactly as it did before —
+  # single decision, whoever holds the permission. That is what lets the four
+  # existing modules migrate one at a time instead of all at once.
+  module Approvable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :approvals, as: :subject, class_name: "HrLite::Approval", dependent: :destroy
+      after_create_commit :open_approval_route
+    end
+
+    def approval_route = @approval_route ||= ApprovalRoute.new(self)
+
+    def routed_for_approval? = approval_route.routed?
+
+    # The rows still waiting, newest rung first — what the show screen lists.
+    def pending_approvals = approvals.pending.order(:position)
+
+    def approval_for(user)
+      return nil if user.nil?
+
+      pending_approvals.detect { |approval| approval.answerable_by?(user) }
+    end
+
+    # Whether this person is the one being waited on. Unrouted subjects fall
+    # back to the permission check the module already used.
+    def awaiting?(user) = approval_for(user).present?
+
+    # The whole story, for the approval screen: who decided what, in order,
+    # including the rungs that were skipped and why.
+    def approval_history = approvals.order(:position, :id)
+
+    private
+
+    def open_approval_route
+      approval_route.open! if approval_route.routed?
+    end
+  end
+end

data/app/models/hr_lite/approval.rb

@@ -0,0 +1,46 @@
+module HrLite
+  # One person's outstanding decision on one record. The row is the unit the
+  # inbox lists and the escalation job reads.
+  class Approval < ApplicationRecord
+    STATUSES = %w[pending approved rejected returned skipped cancelled].freeze
+
+    belongs_to :step, class_name: "HrLite::ApprovalStep"
+    belongs_to :subject, polymorphic: true
+    belongs_to :approver, class_name: HrLite.config.user_class
+    belongs_to :decided_by, class_name: HrLite.config.user_class, optional: true
+
+    validates :status, inclusion: { in: STATUSES }
+
+    scope :pending, -> { where(status: "pending") }
+    scope :at_position, ->(position) { where(position: position) }
+    scope :recent_first, -> { order(created_at: :desc) }
+
+    STATUSES.each { |s| define_method("#{s}?") { status == s } }
+
+    # Whether `user` may answer this — the approver themselves, or somebody
+    # they have delegated to while they are away.
+    def answerable_by?(user)
+      return false if user.nil? || !pending?
+
+      approver_id == user.id ||
+        ApprovalDelegation.stand_ins_for(approver_id).include?(user.id)
+    end
+
+    def decide!(status:, actor:, note: nil)
+      raise ArgumentError, "unknown decision #{status}" unless STATUSES.include?(status.to_s)
+
+      update!(status: status.to_s, note: note.presence, decided_at: Time.current,
+              decided_by_id: actor&.id)
+    end
+
+    # True once this row's SLA has run out. Computed rather than stored so
+    # editing a step's SLA takes effect on the rows already waiting.
+    def overdue?(now = Time.current)
+      return false unless pending? && step.sla_hours
+
+      created_at + step.sla_hours.hours <= now
+    end
+
+    def label = "#{subject_type.demodulize.underscore.humanize} ##{subject_id}"
+  end
+end

data/app/models/hr_lite/approval_delegation.rb

@@ -0,0 +1,38 @@
+module HrLite
+  # "I am away until the 14th — Priya decides for me." Delegation does not
+  # move the approval; it lets somebody else answer it, and the row records
+  # who actually did.
+  class ApprovalDelegation < ApplicationRecord
+    include Audited
+
+    belongs_to :from_user, class_name: HrLite.config.user_class
+    belongs_to :to_user, class_name: HrLite.config.user_class
+
+    validates :starts_on, :ends_on, presence: true
+    validate :ends_after_it_starts
+    validate :not_to_themselves
+
+    scope :live_on, ->(date) { where(starts_on: ..date).where(ends_on: date..) }
+
+    # Who may answer on `user`'s behalf today, including a chain of two —
+    # A delegates to B, B is also away and delegates to C. Capped at two
+    # hops: past that it is quicker to reassign the flow than to follow it.
+    def self.stand_ins_for(user_id, on: Date.current)
+      first = live_on(on).where(from_user_id: user_id).pluck(:to_user_id)
+      second = live_on(on).where(from_user_id: first).pluck(:to_user_id)
+      (first + second - [ user_id ]).uniq
+    end
+
+    private
+
+    def ends_after_it_starts
+      return unless starts_on && ends_on
+
+      errors.add(:ends_on, "must be on or after the start date") if ends_on < starts_on
+    end
+
+    def not_to_themselves
+      errors.add(:to_user_id, "cannot be the person delegating") if from_user_id == to_user_id
+    end
+  end
+end

data/app/models/hr_lite/approval_flow.rb

@@ -0,0 +1,39 @@
+module HrLite
+  # "Leave needs the manager, then HR." One active flow per subject type;
+  # a type with no flow keeps whatever single-decision behaviour it had.
+  class ApprovalFlow < ApplicationRecord
+    include Audited
+
+    has_many :approval_steps, -> { order(:position) },
+             class_name: "HrLite::ApprovalStep", foreign_key: :flow_id, dependent: :destroy
+    accepts_nested_attributes_for :approval_steps, allow_destroy: true
+
+    validates :subject_type, :name, presence: true
+    validate :subject_type_is_approvable
+
+    scope :active, -> { where(active: true) }
+
+    def self.for(subject_type)
+      active.find_by(subject_type: subject_type.to_s)
+    end
+
+    # Subject types that have opted in. Declared rather than derived so a
+    # flow cannot be pointed at a model that has no idea it is approvable.
+    def self.approvable_types
+      %w[
+        HrLite::LeaveRequest HrLite::CompOffRequest
+        HrLite::RegularizationRequest HrLite::Resignation
+      ].freeze
+    end
+
+    def subject_label = subject_type.demodulize.underscore.humanize
+
+    private
+
+    def subject_type_is_approvable
+      return if self.class.approvable_types.include?(subject_type)
+
+      errors.add(:subject_type, "is not a type this engine can route for approval")
+    end
+  end
+end

data/app/models/hr_lite/approval_step.rb

@@ -0,0 +1,62 @@
+module HrLite
+  # One rung. The approver is named by RULE, not by person, so a flow
+  # survives somebody leaving the company — the rule is resolved against the
+  # subject at the moment the request is raised.
+  class ApprovalStep < ApplicationRecord
+    RULES = %w[manager manager_of_manager permission user].freeze
+
+    belongs_to :flow, class_name: "HrLite::ApprovalFlow"
+
+    validates :position, presence: true, uniqueness: { scope: :flow_id }
+    validates :approver_rule, inclusion: { in: RULES }
+    validates :sla_hours, numericality: { greater_than: 0 }, allow_nil: true
+    validate :approver_key_matches_the_rule
+
+    scope :ordered, -> { order(:position) }
+
+    # Everybody who must (or may) decide this rung for `subject`. Empty means
+    # nobody fits — `ApprovalRoute` treats that as a rung to skip rather than
+    # a request nobody can ever answer.
+    # Array(...) rather than an `else` arm: `approver_rule` is held to the
+    # four RULES by a validation AND a database check constraint, so an
+    # unmatched `case` cannot happen — and a defensive branch nothing can
+    # reach is a line that never gets tested and quietly rots.
+    def approvers_for(subject)
+      Array(
+        case approver_rule
+        when "manager" then manager_of(subject.user_id)
+        when "manager_of_manager" then manager_of(manager_of(subject.user_id)&.id)
+        when "permission" then HrLite.users_holding(approver_key, scope: :all).to_a
+        when "user" then HrLite.user_klass.find_by(id: approver_key)
+        end
+      )
+    end
+
+    def label
+      case approver_rule
+      when "manager" then "Their manager"
+      when "manager_of_manager" then "Their manager's manager"
+      when "permission" then "Anyone who can #{Permissions.description(approver_key).downcase}"
+      when "user" then HrLite.display_name(HrLite.user_klass.find_by(id: approver_key))
+      end
+    end
+
+    private
+
+    def manager_of(user_id)
+      return nil if user_id.nil?
+
+      manager_id = EmployeeProfile.where(user_id: user_id).pick(:manager_id)
+      manager_id && HrLite.user_klass.find_by(id: manager_id)
+    end
+
+    def approver_key_matches_the_rule
+      case approver_rule
+      when "permission"
+        errors.add(:approver_key, "must be a known permission") unless Permissions.valid?(approver_key.to_s)
+      when "user"
+        errors.add(:approver_key, "must name a user") if approver_key.blank?
+      end
+    end
+  end
+end

data/app/models/hr_lite/leave_request.rb

@@ -1,5 +1,7 @@
 module HrLite
   class LeaveRequest < ApplicationRecord
+    include Approvable
+
     STATUSES = %w[pending approved rejected cancelled].freeze
 
     belongs_to :user, class_name: HrLite.config.user_class
@@ -38,30 +40,23 @@ module HrLite
 
     # --- transitions -------------------------------------------------------
 
+    # With a flow configured this is ONE RUNG: the request becomes `approved`
+    # only once the last rung is satisfied. With no flow — or from somebody
+    # the flow is not waiting on, such as HR overriding — the first approval
+    # settles it, exactly as before.
+    #
     # Returns false (leaving the request pending) when the balance no longer
-    # covers it — the re-check runs inside the row lock so two concurrent
+    # covers it; the re-check runs inside the row lock so two concurrent
     # approvals cannot overdraw one balance.
     def approve!(actor:, note: nil)
-      insufficient = false
-      transition!("approved", actor, note) do
-        # Serialize on the BALANCE row. `transition!`'s own lock is on this
-        # request, and two pending requests are two different rows — so both
-        # approvals could read the same untouched balance and overdraw it.
-        LeaveBalance.lock_for(user, leave_type, LeaveYear.key_for(start_date)) unless leave_type.unlimited?
-
-        if insufficient_balance_now?
-          insufficient = true
-          raise ActiveRecord::Rollback
-        end
-      end
-      return false if insufficient
+      return record_routed_decision!(actor, note, :approved) if awaiting?(actor)
 
-      notify_decision("Leave approved")
-      notify_team
-      true
+      approve_outright!(actor: actor, note: note)
     end
 
     def reject!(actor:, note:)
+      return record_routed_decision!(actor, note, :rejected) if awaiting?(actor)
+
       transition!("rejected", actor, note)
       notify_decision("Leave rejected")
       true
@@ -86,6 +81,9 @@ module HrLite
         # Cancelling an APPROVED leave hands the days back to the balance, so
         # it is a quota change as much as a status change.
         audit!("cancelled", actor, was_approved ? "was approved" : nil)
+        # And nobody should still be asked to decide a request that has been
+        # called off — it would sit in their inbox for ever.
+        approval_route.cancel_all!
       end
 
       Notifications.publish(
@@ -112,6 +110,63 @@ module HrLite
 
     private
 
+    # One rung answered. The route says whether that settles the request; if
+    # it does, the ordinary transition runs and does the real work — crediting
+    # or releasing balance, notifying, auditing — so routing never becomes a
+    # second path that can drift from the first.
+    def record_routed_decision!(actor, note, intent)
+      approval = approval_for(actor)
+      result = approval_route.decide!(approval, status: intent.to_s, actor: actor, note: note)
+
+      case result.outcome
+      when :approved then approve_outright!(actor: actor, note: note)
+      when :rejected then reject_outright!(actor: actor, note: note.presence || "Rejected")
+      else
+        notify_pending_approvers
+        true
+      end
+    end
+
+    def approve_outright!(actor:, note:)
+      insufficient = false
+      transition!("approved", actor, note) do
+        # Serialize on the BALANCE row. `transition!`'s own lock is on this
+        # request, and two pending requests are two different rows — so both
+        # approvals could read the same untouched balance and overdraw it.
+        LeaveBalance.lock_for(user, leave_type, LeaveYear.key_for(start_date)) unless leave_type.unlimited?
+
+        if insufficient_balance_now?
+          insufficient = true
+          raise ActiveRecord::Rollback
+        end
+      end
+      return false if insufficient
+
+      notify_decision("Leave approved")
+      notify_team
+      true
+    end
+
+    def reject_outright!(actor:, note:)
+      transition!("rejected", actor, note)
+      notify_decision("Leave rejected")
+      true
+    end
+
+    # The next rung has just opened; tell the people it opened on.
+    def notify_pending_approvers
+      approvers = pending_approvals.map(&:approver).compact.uniq
+      return if approvers.empty?
+
+      Notifications.publish(
+        "leave.requested",
+        title: "#{HrLite.display_name(user)} — #{leave_type.name} (#{date_range_label}) needs your approval",
+        body: reason.presence,
+        path: "/admin/leave_requests/#{id}",
+        bell_to: approvers
+      )
+    end
+
     def transition!(new_status, actor, note)
       with_lock do
         raise ActiveRecord::RecordInvalid.new(self), "not pending" unless pending?

data/app/services/hr_lite/approval_route.rb

@@ -0,0 +1,109 @@
+module HrLite
+  # Drives one record through its flow: opens the first rung, advances when a
+  # rung is satisfied, and reports when the whole thing is settled.
+  #
+  # It decides NOTHING about the subject itself. `Approvable` owns what
+  # "approved" means for a leave request; this class only knows whose turn it
+  # is. That split is why adding expenses later needs no change here.
+  class ApprovalRoute
+    Result = Struct.new(:outcome, :approval, keyword_init: true)
+
+    def initialize(subject)
+      @subject = subject
+    end
+
+    attr_reader :subject
+
+    def flow = @flow ||= ApprovalFlow.for(subject.class.name)
+
+    def routed? = flow.present?
+
+    # Opens the first rung that has anybody on it. A rung whose rule resolves
+    # to nobody — no manager recorded, say — is SKIPPED rather than left
+    # waiting for a person who does not exist.
+    def open!
+      return Result.new(outcome: :unrouted) unless routed?
+
+      flow.approval_steps.ordered.each do |step|
+        approvers = step.approvers_for(subject)
+        next skip!(step) if approvers.empty?
+
+        create_rows(step, approvers)
+        return Result.new(outcome: :pending)
+      end
+
+      # Every rung skipped: nobody in the flow can decide, so the request
+      # carries itself. Better than a request that can never be answered.
+      Result.new(outcome: :approved)
+    end
+
+    def pending_rows = Approval.pending.where(subject: subject)
+
+    def current_position = pending_rows.minimum(:position)
+
+    # Records one decision and works out what it means for the record.
+    #
+    #   :pending  — the rung still needs somebody
+    #   :approved — every rung is satisfied
+    #   :rejected — one refusal ends it
+    #   :returned — sent back to the requester for correction
+    def decide!(approval, status:, actor:, note: nil)
+      approval.decide!(status: status, actor: actor, note: note)
+
+      case status.to_s
+      when "rejected", "returned"
+        cancel_remaining!(approval.position)
+        Result.new(outcome: status.to_sym, approval: approval)
+      else
+        advance_from(approval)
+      end
+    end
+
+    def cancel_all!
+      pending_rows.update_all(status: "cancelled", decided_at: Time.current) # rubocop:disable Rails/SkipsModelValidations
+    end
+
+    private
+
+    def advance_from(approval)
+      rung = Approval.where(subject: subject).at_position(approval.position)
+      # A unanimous rung waits for everybody; otherwise the first answer
+      # settles it and the rest are stood down.
+      if approval.step.unanimous && rung.pending.exists?
+        return Result.new(outcome: :pending, approval: approval)
+      end
+
+      rung.pending.each { |other| other.decide!(status: "skipped", actor: nil) }
+      open_next_after(approval.position) || Result.new(outcome: :approved, approval: approval)
+    end
+
+    def open_next_after(position)
+      flow.approval_steps.ordered.each do |step|
+        next if step.position <= position
+
+        approvers = step.approvers_for(subject)
+        next skip!(step) if approvers.empty?
+
+        create_rows(step, approvers)
+        return Result.new(outcome: :pending)
+      end
+      nil
+    end
+
+    def create_rows(step, approvers)
+      approvers.uniq.each do |approver|
+        Approval.create!(subject: subject, step: step, position: step.position,
+                         approver_id: approver.id)
+      end
+    end
+
+    # Nothing to record: a rung nobody occupies never happened. Returning nil
+    # keeps `each`'s `next` readable at the call sites.
+    def skip!(_step) = nil
+
+    def cancel_remaining!(position)
+      Approval.pending.where(subject: subject).where("position >= ?", position)
+              .each { |row| row.decide!(status: "cancelled", actor: nil) }
+    end
+  end
+end

data/app/views/hr_lite/approvals/index.html.erb

@@ -0,0 +1,66 @@
+<% content_for(:page_title) { "Waiting on you" } %>
+<div class="hrl-page__head">
+  <h1 class="hrl-page__title">Waiting on you</h1>
+</div>
+
+<% if @covering_for.any? %>
+  <section class="hrl-card">
+    <p class="hrl-small hrl-muted">
+      You are covering for
+      <%= @covering_for.map { |d| hr_display_name(d.from_user) }.to_sentence %>.
+      Their approvals appear below alongside your own.
+    </p>
+  </section>
+<% end %>
+
+<section class="hrl-card">
+  <% if @approvals.empty? %>
+    <p class="hrl-muted">Nothing is waiting on you.</p>
+  <% else %>
+    <div class="hrl-table-wrap">
+      <table class="hrl-table hrl-table--stack">
+        <thead><tr><th>Request</th><th>From</th><th>Waiting</th><th></th></tr></thead>
+        <tbody>
+          <% @approvals.each do |approval| %>
+            <% subject = approval.subject %>
+            <tr>
+              <td data-label="Request">
+                <strong><%= approval.label %></strong>
+                <% if approval.overdue? %>
+                  <span class="hrl-badge hrl-badge--bad">Overdue</span>
+                <% end %>
+                <% if approval.approver_id != hr_current_user.id %>
+                  <span class="hrl-badge hrl-badge--muted">
+                    for <%= hr_display_name(approval.approver) %>
+                  </span>
+                <% end %>
+              </td>
+              <td data-label="From"><%= hr_display_name(subject&.user) %></td>
+              <td data-label="Waiting"><%= time_ago_in_words(approval.created_at) %></td>
+              <td data-label="">
+                <% if (path = hrl_approval_path(approval)) %>
+                  <a class="hrl-small" href="<%= path %>">Open</a>
+                <% end %>
+              </td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+    <%= hrl_pagination %>
+  <% end %>
+</section>
+
+<% if @delegations.any? %>
+  <section class="hrl-card">
+    <h2 class="hrl-card__title">While you are away</h2>
+    <ul>
+      <% @delegations.each do |delegation| %>
+        <li class="hrl-small">
+          <%= hr_display_name(delegation.to_user) %> decides for you,
+          <%= delegation.starts_on.strftime("%d %b") %> – <%= delegation.ends_on.strftime("%d %b %Y") %>
+        </li>
+      <% end %>
+    </ul>
+  </section>
+<% end %>

data/config/routes.rb

@@ -19,6 +19,7 @@ HrLite::Engine.routes.draw do
   resources :regularization_requests, only: %i[index new create] do
     member { post :cancel }
   end
+  resources :approvals, only: :index
   get "team", to: "team#show"
   get "org", to: "org#show"
   resources :holidays, only: :index

data/db/migrate/20260818001151_create_hr_lite_approvals.rb

@@ -0,0 +1,79 @@
+class CreateHrLiteApprovals < ActiveRecord::Migration[8.1]
+  # Leave, comp-off, regularization and resignation each grew their own
+  # approve/reject/cancel, with their own transition guard and their own
+  # notification. Four copies of one idea, and every module still to come
+  # (expenses, loans, salary revisions, document verification) would have
+  # been a fifth.
+  #
+  # A FLOW is the definition — "leave needs the manager, then HR". A STEP is
+  # one rung of it, naming an approver by RULE rather than by person, so the
+  # flow survives somebody leaving. An APPROVAL is one live decision on one
+  # record.
+  def change
+    create_table :hr_lite_approval_flows do |t|
+      # The model this flow decides on, e.g. "HrLite::LeaveRequest".
+      t.string :subject_type, null: false
+      t.string :name, null: false
+      t.boolean :active, null: false, default: true
+      t.timestamps
+    end
+    add_index :hr_lite_approval_flows, :subject_type,
+              unique: true, where: "active", name: "index_hr_lite_approval_flows_one_active_per_type"
+
+    create_table :hr_lite_approval_steps do |t|
+      t.references :flow, null: false, index: false,
+                   foreign_key: { to_table: :hr_lite_approval_flows, on_delete: :cascade }
+      t.integer :position, null: false
+      # manager | manager_of_manager | permission | user
+      t.string :approver_rule, null: false
+      # permission key for `permission`, user id for `user`, unused otherwise
+      t.string :approver_key
+      # Everybody on this rung must decide, rather than the first to answer.
+      t.boolean :unanimous, null: false, default: false
+      # Hours before the step is escalated. Null = never.
+      t.integer :sla_hours
+      t.timestamps
+    end
+    add_index :hr_lite_approval_steps, %i[flow_id position], unique: true
+    add_check_constraint :hr_lite_approval_steps,
+                         "approver_rule IN ('manager', 'manager_of_manager', 'permission', 'user')",
+                         name: "hr_lite_approval_steps_rule_check"
+
+    create_table :hr_lite_approvals do |t|
+      t.string :subject_type, null: false
+      t.bigint :subject_id, null: false
+      t.references :step, null: false, index: false,
+                   foreign_key: { to_table: :hr_lite_approval_steps, on_delete: :cascade }
+      t.integer :position, null: false
+      t.bigint :approver_id, null: false
+      # pending | approved | rejected | returned | skipped | cancelled
+      t.string :status, null: false, default: "pending"
+      t.text :note
+      t.datetime :decided_at
+      # Who decided in the approver's place, when they had delegated.
+      t.bigint :decided_by_id
+      t.datetime :escalated_at
+      t.timestamps
+    end
+    add_index :hr_lite_approvals, %i[subject_type subject_id position]
+    # One live row per approver per rung: two would let the same person
+    # decide twice, or a retry double-count a unanimous step.
+    add_index :hr_lite_approvals, %i[subject_type subject_id position approver_id],
+              unique: true, name: "index_hr_lite_approvals_one_per_approver_per_step"
+    add_index :hr_lite_approvals, :approver_id
+    add_check_constraint :hr_lite_approvals,
+                         "status IN ('pending', 'approved', 'rejected', 'returned', 'skipped', 'cancelled')",
+                         name: "hr_lite_approvals_status_check"
+
+    create_table :hr_lite_approval_delegations do |t|
+      t.bigint :from_user_id, null: false
+      t.bigint :to_user_id, null: false
+      t.date :starts_on, null: false
+      t.date :ends_on, null: false
+      t.string :reason
+      t.timestamps
+    end
+    add_index :hr_lite_approval_delegations, %i[from_user_id starts_on ends_on],
+              name: "index_hr_lite_delegations_on_from_and_dates"
+  end
+end

data/lib/hr_lite/notifications.rb

@@ -24,6 +24,9 @@ module HrLite
       "appraisal.shared"      => { bell: true,  email: true,  leadership_email: true,  leadership_bell: false },
       "promotion.recorded"    => { bell: true,  email: true,  leadership_email: true,  leadership_bell: true  },
       "policy.changed"        => { bell: false, email: false, leadership_email: true,  leadership_bell: true  },
+      # An approval past its deadline. Leadership hears too — a decision
+      # nobody is making is a process problem, not just one person's inbox.
+      "approval.escalated"    => { bell: true,  email: true,  leadership_email: true,  leadership_bell: false },
       "digest.daily"          => { bell: false, email: false, leadership_email: true,  leadership_bell: false },
       "resignation.submitted" => { bell: true,  email: false, leadership_email: true,  leadership_bell: true  },
       "resignation.accepted"  => { bell: true,  email: true,  leadership_email: true,  leadership_bell: false },

data/lib/hr_lite/version.rb

@@ -1,3 +1,3 @@
 module HrLite
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hr_lite
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - kshitiz sinha
@@ -81,6 +81,7 @@ files:
 - app/controllers/hr_lite/admin/superadmin_controller.rb
 - app/controllers/hr_lite/application_controller.rb
 - app/controllers/hr_lite/appraisals_controller.rb
+- app/controllers/hr_lite/approvals_controller.rb
 - app/controllers/hr_lite/attendance_controller.rb
 - app/controllers/hr_lite/calendar_controller.rb
 - app/controllers/hr_lite/career_controller.rb
@@ -99,15 +100,21 @@ files:
 - app/controllers/hr_lite/users_controller.rb
 - app/helpers/hr_lite/application_helper.rb
 - app/jobs/hr_lite/application_job.rb
+- app/jobs/hr_lite/approval_escalation_job.rb
 - app/jobs/hr_lite/daily_digest_job.rb
 - app/jobs/hr_lite/leave_year_rollover_job.rb
 - app/jobs/hr_lite/payroll_auto_draft_job.rb
 - app/mailers/hr_lite/application_mailer.rb
 - app/mailers/hr_lite/event_mailer.rb
+- app/models/concerns/hr_lite/approvable.rb
 - app/models/concerns/hr_lite/audited.rb
 - app/models/concerns/hr_lite/encrypted_money.rb
 - app/models/hr_lite/application_record.rb
 - app/models/hr_lite/appraisal.rb
+- app/models/hr_lite/approval.rb
+- app/models/hr_lite/approval_delegation.rb
+- app/models/hr_lite/approval_flow.rb
+- app/models/hr_lite/approval_step.rb
 - app/models/hr_lite/attendance_record.rb
 - app/models/hr_lite/audit_log.rb
 - app/models/hr_lite/comp_off_request.rb
@@ -132,6 +139,7 @@ files:
 - app/models/hr_lite/setting.rb
 - app/models/hr_lite/statutory_rate_card_record.rb
 - app/services/hr_lite/access.rb
+- app/services/hr_lite/approval_route.rb
 - app/services/hr_lite/attendance_puncher.rb
 - app/services/hr_lite/attendance_summary.rb
 - app/services/hr_lite/calculators/esi.rb
@@ -195,6 +203,7 @@ files:
 - app/views/hr_lite/admin/statutory_rate_cards/new.html.erb
 - app/views/hr_lite/appraisals/index.html.erb
 - app/views/hr_lite/appraisals/show.html.erb
+- app/views/hr_lite/approvals/index.html.erb
 - app/views/hr_lite/attendance/_month_grid.html.erb
 - app/views/hr_lite/attendance/_punch_card.html.erb
 - app/views/hr_lite/attendance/show.html.erb
@@ -263,6 +272,7 @@ files:
 - db/migrate/20260817183347_create_hr_lite_roles_and_grants.rb
 - db/migrate/20260817183629_seed_hr_lite_roles_from_email_tiers.rb
 - db/migrate/20260817190159_create_hr_lite_statutory_rate_cards.rb
+- db/migrate/20260818001151_create_hr_lite_approvals.rb
 - lib/generators/hr_lite/install/install_generator.rb
 - lib/generators/hr_lite/install/templates/AFTER_INSTALL
 - lib/generators/hr_lite/install/templates/initializer.rb