hr_lite 0.5.2 → 0.6.0

data/app/views/hr_lite/admin/roles/edit.html.erb

@@ -0,0 +1,53 @@
+<% content_for(:page_title) { @role.name } %>
+<div class="hrl-page__head">
+  <h1 class="hrl-page__title"><%= @role.name %></h1>
+  <% unless @role.system? %>
+    <div class="hrl-page__actions">
+      <%= button_to "Delete role", hr_lite.admin_role_path(@role), method: :delete,
+            class: "hrl-btn hrl-btn--danger",
+            form: { data: { turbo_confirm: "Delete #{@role.name}? Everyone holding it loses that access." } } %>
+    </div>
+  <% end %>
+</div>
+
+<%= render "form", role: @role, url: hr_lite.admin_role_path(@role), method: :patch %>
+
+<section class="hrl-card">
+  <h2 class="hrl-card__title">Who holds this role</h2>
+  <% assignments = @role.role_assignments.includes(:user).sort_by { |a| hr_display_name(a.user).downcase } %>
+  <% if assignments.empty? %>
+    <p class="hrl-muted">Nobody yet.</p>
+  <% else %>
+    <div class="hrl-table-wrap">
+      <table class="hrl-table hrl-table--stack">
+        <thead><tr><th>Person</th><th>Added</th><th></th></tr></thead>
+        <tbody>
+          <% assignments.each do |assignment| %>
+            <tr>
+              <td data-label="Person"><%= hr_display_name(assignment.user) %></td>
+              <td data-label="Added"><%= assignment.created_at.to_date.strftime("%d %b %Y") %></td>
+              <td data-label="">
+                <%= button_to "Remove", hr_lite.admin_role_assignment_path(@role, assignment),
+                      method: :delete, class: "hrl-btn",
+                      form: { data: { turbo_confirm: "Remove #{hr_display_name(assignment.user)} from #{@role.name}?" } } %>
+              </td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+  <% end %>
+
+  <%= form_with url: hr_lite.admin_role_assignments_path(@role), method: :post, local: true do %>
+    <div class="hrl-field">
+      <%= label_tag :user_id, "Add somebody to this role" %>
+      <% held = @role.role_assignments.map(&:user_id) %>
+      <%= select_tag :user_id,
+            options_for_select(HrLite.employees.reject { |u| held.include?(u.id) }
+                                     .map { |u| [ hr_display_name(u), u.id ] }) %>
+    </div>
+    <div class="hrl-form-actions">
+      <%= submit_tag "Add", class: "hrl-btn hrl-btn--primary" %>
+    </div>
+  <% end %>
+</section>

data/app/views/hr_lite/admin/roles/index.html.erb

@@ -0,0 +1,49 @@
+<% content_for(:page_title) { "Roles" } %>
+<div class="hrl-page__head">
+  <h1 class="hrl-page__title">Roles &amp; permissions</h1>
+  <div class="hrl-page__actions">
+    <a class="hrl-btn hrl-btn--primary" href="<%= hr_lite.new_admin_role_path %>">Add role</a>
+  </div>
+</div>
+
+<section class="hrl-card">
+  <p class="hrl-muted hrl-small">
+    A permission is what somebody may do; its scope is whose records they may
+    do it to — only their own, their reports', or everyone's.
+  </p>
+  <div class="hrl-table-wrap">
+    <table class="hrl-table hrl-table--stack">
+      <thead><tr><th>Role</th><th>People</th><th>Reaches</th><th></th></tr></thead>
+      <tbody>
+        <% @roles.each do |role| %>
+          <tr>
+            <td data-label="Role">
+              <strong><%= role.name %></strong>
+              <% if role.system? %><span class="hrl-badge hrl-badge--muted">Built-in</span><% end %>
+              <% if role.description.present? %>
+                <div class="hrl-small hrl-muted"><%= role.description %></div>
+              <% end %>
+            </td>
+            <td data-label="People" class="hrl-num"><%= role.role_assignments.size %></td>
+            <td data-label="Reaches">
+              <% company_wide = role.role_grants.count { |g| g.scope == "all" } %>
+              <% team = role.role_grants.count { |g| g.scope == "team" } %>
+              <%= role.role_grants.size %> permission<%= "s" unless role.role_grants.size == 1 %>
+              <%# Joined rather than concatenated: a role with team grants and
+                  no company-wide ones rendered a leading "·" with nothing
+                  in front of it. %>
+              <% reach = [ ("#{company_wide} company-wide" if company_wide.positive?),
+                           ("#{team} own team" if team.positive?) ].compact %>
+              <% if reach.any? %>
+                <span class="hrl-small hrl-muted"><%= reach.join(" · ") %></span>
+              <% end %>
+            </td>
+            <td data-label="">
+              <a class="hrl-small" href="<%= hr_lite.edit_admin_role_path(role) %>">Edit</a>
+            </td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+</section>

data/app/views/hr_lite/admin/roles/new.html.erb

@@ -0,0 +1,3 @@
+<% content_for(:page_title) { "New role" } %>
+<div class="hrl-page__head"><h1 class="hrl-page__title">New role</h1></div>
+<%= render "form", role: @role, url: hr_lite.admin_roles_path, method: :post %>

data/config/routes.rb

@@ -46,6 +46,9 @@ HrLite::Engine.routes.draw do
     resources :regularization_requests, only: %i[index show] do
       member { post :approve; post :reject }
     end
+    resources :roles, except: :show do
+      resources :assignments, only: %i[create destroy], controller: "role_assignments"
+    end
     resources :leave_types, except: :show
     resources :office_locations, except: :show
     resources :holidays, only: %i[index create update destroy] do

data/db/migrate/20260817182124_add_status_constraints_and_appraisal_fk_to_hr_lite.rb

@@ -0,0 +1,63 @@
+class AddStatusConstraintsAndAppraisalFkToHrLite < ActiveRecord::Migration[8.1]
+  # Every status column in the engine is a plain string validated only in
+  # Ruby, so anything that skips validations — update_column, update_all,
+  # insert_all, a console fix, a future migration — can write a value no
+  # screen renders and no transition accepts. These constraints put the
+  # allowed set somewhere it cannot be bypassed.
+  #
+  # Deliberately in step with each model's own STATUSES array: adding a
+  # status now means writing a migration, which is the point.
+  STATUSES = {
+    hr_lite_attendance_records: %w[present half_day],
+    hr_lite_leave_requests: %w[pending approved rejected cancelled],
+    hr_lite_comp_off_requests: %w[pending approved rejected cancelled],
+    hr_lite_regularization_requests: %w[pending approved rejected cancelled],
+    hr_lite_resignations: %w[pending accepted withdrawn],
+    hr_lite_appraisals: %w[draft shared],
+    hr_lite_payroll_runs: %w[draft processing review finalized published]
+  }.freeze
+
+  def up
+    # On an install that already holds an off-list value the constraint build
+    # fails with a bare integrity error naming neither the row nor the value.
+    # Say what is actually in the way instead — this runs on live data.
+    offenders = STATUSES.filter_map do |table, statuses|
+      found = select_values(
+        "SELECT DISTINCT status FROM #{table} WHERE status NOT IN (#{quoted(statuses)})"
+      )
+      "#{table}: #{found.join(', ')}" if found.any?
+    end
+
+    if offenders.any?
+      raise ActiveRecord::IrreversibleMigration,
+            "Cannot constrain status columns — these rows hold values no model " \
+            "declares. Correct them first:\n  #{offenders.join("\n  ")}"
+    end
+
+    STATUSES.each do |table, statuses|
+      add_check_constraint table, status_sql(statuses), name: constraint_name(table)
+    end
+
+    # has_one :designation_change, dependent: :nullify — with neither an index
+    # nor a foreign key. Destroying an appraisal scanned the whole table to
+    # find its promotion row, and nothing stopped that row from being left
+    # pointing at an appraisal that no longer exists.
+    add_index :hr_lite_designation_changes, :appraisal_id
+    add_foreign_key :hr_lite_designation_changes, :hr_lite_appraisals,
+                    column: :appraisal_id, on_delete: :nullify
+  end
+
+  def down
+    remove_foreign_key :hr_lite_designation_changes, column: :appraisal_id
+    remove_index :hr_lite_designation_changes, :appraisal_id
+    STATUSES.each_key { |table| remove_check_constraint table, name: constraint_name(table) }
+  end
+
+  private
+
+  def status_sql(statuses) = "status IN (#{quoted(statuses)})"
+
+  def quoted(statuses) = statuses.map { |s| connection.quote(s) }.join(", ")
+
+  def constraint_name(table) = "#{table}_status_check"
+end

data/db/migrate/20260817183347_create_hr_lite_roles_and_grants.rb

@@ -0,0 +1,49 @@
+class CreateHrLiteRolesAndGrants < ActiveRecord::Migration[8.1]
+  # Roles replace the three configured lambdas (admin_check, leadership_emails,
+  # superadmin_emails). Two of those matched a MUTABLE email string — a
+  # permission stored in a column the host lets people edit.
+  #
+  # Permissions themselves are not a table: the vocabulary is declared in
+  # HrLite::Permissions::REGISTRY, so a grant is a (role, key, scope) row and
+  # an unknown key cannot be stored. That keeps seeding idempotent, and makes
+  # retiring a permission a code change with a spec rather than silent data.
+  def change
+    create_table :hr_lite_roles do |t|
+      t.string :name, null: false
+      t.string :description
+      # Roles the engine seeds and refers to by name. Renaming or deleting one
+      # is refused by the model — the upgrade path off the email lists lands
+      # people in these, and the roles screen has to keep meaning something.
+      t.boolean :system, null: false, default: false
+      t.timestamps
+    end
+    add_index :hr_lite_roles, :name, unique: true
+
+    create_table :hr_lite_role_grants do |t|
+      t.references :role, null: false, index: false,
+                   foreign_key: { to_table: :hr_lite_roles, on_delete: :cascade }
+      t.string :permission_key, null: false
+      # self | team | all — see HrLite::Permissions. Stored per grant so one
+      # key covers "own leave", "my reports' leave" and "everyone's leave".
+      t.string :scope, null: false, default: "self"
+      t.timestamps
+    end
+    # One scope per (role, permission): a role either reaches a set of rows or
+    # it does not, and two rows for one key would make that a lookup race.
+    add_index :hr_lite_role_grants, %i[role_id permission_key], unique: true
+    add_check_constraint :hr_lite_role_grants, "scope IN ('self', 'team', 'all')",
+                         name: "hr_lite_role_grants_scope_check"
+
+    create_table :hr_lite_role_assignments do |t|
+      # No FK to the host user table — its name is host-specific, the same
+      # reason every other user_id in this engine is a bare bigint.
+      t.bigint :user_id, null: false
+      t.references :role, null: false, index: false,
+                   foreign_key: { to_table: :hr_lite_roles, on_delete: :cascade }
+      t.bigint :granted_by_id
+      t.timestamps
+    end
+    add_index :hr_lite_role_assignments, %i[user_id role_id], unique: true
+    add_index :hr_lite_role_assignments, :role_id
+  end
+end

data/db/migrate/20260817183629_seed_hr_lite_roles_from_email_tiers.rb

@@ -0,0 +1,82 @@
+class SeedHrLiteRolesFromEmailTiers < ActiveRecord::Migration[8.1]
+  # The upgrade path off the email lists. On an install that is already
+  # running, this is the migration that decides whether anyone loses access,
+  # so it is deliberately generous: everybody who could reach something
+  # before can reach at least as much afterwards.
+  #
+  #   config.superadmin_emails  -> Super Admin
+  #   config.leadership_emails  -> Leadership
+  #   admin_check == true       -> HR
+  #   everybody else            -> Employee
+  #
+  # It reads the host's OWN configuration, so nothing has to be typed twice,
+  # and it says out loud what it did — an upgrade that silently grants the
+  # money tier to the wrong person is the failure worth being loud about.
+  def up
+    require "hr_lite/role_seeds"
+    created = HrLite::RoleSeeds.call
+    say "Seeded roles: #{created.join(', ')}" if created.any?
+
+    # A host that has already assigned roles by hand is not re-derived from
+    # email lists — that would undo their work.
+    if HrLite::RoleAssignment.exists?
+      say "Role assignments already exist — leaving them alone."
+      return
+    end
+
+    roles = HrLite::Role.where(name: [
+      HrLite::Role::EMPLOYEE, HrLite::Role::HR,
+      HrLite::Role::LEADERSHIP, HrLite::Role::SUPER_ADMIN
+    ]).index_by(&:name)
+
+    # The legacy predicates, read directly rather than through HrLite.admin?
+    # — which by now answers off roles, and would say no to everyone.
+    superadmins = HrLite.normalize_email_list(HrLite.config.superadmin_emails)
+    leaders = HrLite.normalize_email_list(HrLite.config.leadership_emails)
+    # Pre-0.5.0 behaviour, still live on hosts that never set the money list:
+    # an empty superadmin list meant "the same people as leadership".
+    superadmins = leaders if superadmins.empty?
+
+    assigned = Hash.new { |hash, key| hash[key] = [] }
+
+    HrLite.config.employees_scope.call.find_each do |user|
+      address = user.respond_to?(:email) ? user.email.to_s.downcase.strip : ""
+      names = [ HrLite::Role::EMPLOYEE ]
+      names << HrLite::Role::SUPER_ADMIN if address.present? && superadmins.include?(address)
+      names << HrLite::Role::LEADERSHIP if address.present? && leaders.include?(address)
+      names << HrLite::Role::HR if legacy_admin?(user)
+
+      names.uniq.each do |name|
+        role = roles[name] or next
+
+        HrLite::RoleAssignment.create!(user_id: user.id, role: role)
+        assigned[name] << HrLite.display_name(user)
+      end
+    end
+
+    if assigned.empty?
+      say "No users matched employees_scope — assign roles from the Roles screen."
+    else
+      assigned.each { |name, people| say "#{name}: #{people.sort.join(', ')}" }
+    end
+    say "Set `config.legacy_tier_checks = true` to keep the old email lists in " \
+        "charge for now; it is honoured until 0.7.0."
+  end
+
+  # Assignments only — the roles themselves stay, because dropping them would
+  # take every hand-made grant with them.
+  def down
+    HrLite::RoleAssignment.delete_all
+  end
+
+  private
+
+  # admin_check is a host lambda over the host's own user model; a host whose
+  # users do not answer it must not break the whole upgrade.
+  def legacy_admin?(user)
+    !!HrLite.config.admin_check.call(user)
+  rescue StandardError => e
+    say "admin_check raised for #{HrLite.display_name(user)} (#{e.class}) — treated as not HR."
+    false
+  end
+end

data/lib/generators/hr_lite/install/templates/initializer.rb

@@ -7,13 +7,19 @@ HrLite.configure do |c|
   c.current_user_method = :current_user
   c.authenticate_method = :authenticate_user!
 
-  # Operations tier (team attendance, leave decisions, overview board).
-  c.admin_check = ->(user) { user.respond_to?(:admin?) && user.admin? }
-
-  # Governing tier — ONLY these people change policy, employee profiles,
-  # salary structures, payroll and appraisals. Keep it in an env var so
-  # changing leadership never needs a deploy.
-  c.leadership_emails = ENV.fetch("HR_LEADERSHIP_EMAILS", "").split(",").map(&:strip)
+  # Access is a role table, not configuration — `rake hr_lite:seed` creates
+  # the built-in roles and you assign people from /admin/roles. The first
+  # person needs Super Admin, which the upgrade migration grants on an
+  # existing install; on a fresh one, from a console:
+  #
+  #   HrLite::RoleAssignment.create!(
+  #     user_id: User.find_by!(email: "you@example.com").id,
+  #     role: HrLite::Role.find_by!(name: HrLite::Role::SUPER_ADMIN))
+  #
+  # Upgrading from pre-0.6.0 and not ready to move? Uncomment this and keep
+  # your leadership_emails / superadmin_emails / admin_check as they were.
+  # It is honoured until 0.7.0.
+  # c.legacy_tier_checks = true
 
   # Where the portal is reachable (subdomain or path). Enables email link
   # buttons and HrLite.public_url / HrLite.public_url? for deep links.

data/lib/hr_lite/configuration.rb

@@ -10,7 +10,8 @@ module HrLite
                   :leadership_emails, :leadership_check, :extra_stylesheets,
                   :superadmin_emails, :superadmin_check,
                   :mailer_from, :public_url_base, :notification_matrix, :back_link,
-                  :onboard_user, :offboard_user, :invite_url_for
+                  :onboard_user, :offboard_user, :invite_url_for,
+                  :legacy_tier_checks
 
     attr_reader :leave_year_start_month
 
@@ -45,17 +46,20 @@ module HrLite
       @time_zone             = "Asia/Kolkata"
       @currency_symbol      = "₹"
       @on_designation_change = ->(user, designation) { }
+      # Access came from three lambdas before 0.6.0, two of which matched the
+      # user's EMAIL — a mutable, host-owned, unverified column that a host
+      # then had to remember never to let anyone edit. Roles replace them.
+      # This flag hands authority back to the old lambdas for a host that has
+      # not finished migrating; honoured for one minor version, gone in 0.7.0.
+      @legacy_tier_checks    = false
       @leadership_emails     = []
-      @leadership_check      = ->(user) do
-        emails = HrLite.config.leadership_emails.map { |e| e.to_s.downcase.strip }
-        emails.include?(user.email.to_s.downcase)
-      end
+      @leadership_check      = ->(user) { HrLite.email_listed?(user, HrLite.config.leadership_emails) }
       # Money tier: salary structures, payroll, slips, appraisals. Empty
       # list means "same as leadership" (pre-0.5.0 behaviour).
       @superadmin_emails     = []
       @superadmin_check      = ->(user) do
-        emails = HrLite.config.superadmin_emails.map { |e| e.to_s.downcase.strip }.reject(&:empty?)
-        emails.empty? ? HrLite.leadership?(user) : emails.include?(user.email.to_s.downcase)
+        list = HrLite.normalize_email_list(HrLite.config.superadmin_emails)
+        list.empty? ? HrLite.leadership?(user) : HrLite.email_listed?(user, list)
       end
       @extra_stylesheets     = [] # host stylesheets linked AFTER hr_lite.css (CSS-var overrides)
       @mailer_from           = "hr@example.com"

data/lib/hr_lite/current.rb

@@ -3,5 +3,9 @@ module HrLite
   # readable from any model callback without threading it through.
   class Current < ActiveSupport::CurrentAttributes
     attribute :actor
+    # Resolved permissions, keyed by user id. Every screen asks several times
+    # per request and resolution joins three tables; CurrentAttributes is
+    # reset between requests, so a role change takes effect on the next one.
+    attribute :access_cache
   end
 end

data/lib/hr_lite/financial_year.rb

@@ -0,0 +1,26 @@
+module HrLite
+  # The Indian financial year runs 1 April – 31 March. Three places worked
+  # this out for themselves (the slip's year-to-date sums, the TDS projector
+  # and the rate card); it lives here once so they cannot drift apart.
+  module FinancialYear
+    START_MONTH = 4
+
+    # First day of the FY containing `date`. March 2027 belongs to the year
+    # that opened on 1 April 2026.
+    def self.start_for(date)
+      year = date.month >= START_MONTH ? date.year : date.year - 1
+      Date.new(year, START_MONTH, 1)
+    end
+
+    # "2026-27" — for warnings and screens, never for arithmetic.
+    def self.label(date)
+      start = start_for(date)
+      "#{start.year}-#{format('%02d', (start.year + 1) % 100)}"
+    end
+
+    # True when `date` falls in an earlier FY than `other`.
+    def self.before?(date, other)
+      start_for(date) < start_for(other)
+    end
+  end
+end

data/lib/hr_lite/permissions.rb

@@ -0,0 +1,79 @@
+module HrLite
+  # The whole vocabulary of the engine's authorization, in one place.
+  #
+  # A permission is a KEY plus a SCOPE. The key says what the action is
+  # ("approve leave"); the scope says whose rows it reaches:
+  #
+  #   self  — only this person's own records
+  #   team  — the people who report to them (EmployeeProfile#manager_id)
+  #   all   — everyone in the company
+  #
+  # That is why there is no `leave.approve_own` / `leave.approve_team` /
+  # `leave.approve_all` triple: one key with three possible scopes says the
+  # same thing without three times the surface to get wrong.
+  #
+  # Keys are DATA — a role grants them from the database. They are declared
+  # here so that a typo in a controller is a boot-time failure rather than a
+  # permission that silently never matches.
+  module Permissions
+    SCOPES = %i[self team all].freeze
+
+    # Ordered weakest to strongest. `all` satisfies a `team` requirement,
+    # `team` satisfies `self`; never the other way round.
+    SCOPE_RANK = { self: 0, team: 1, all: 2 }.freeze
+
+    # key => [ group, description ]. The group is what the roles screen
+    # renders as a heading; the description is the sentence beside the
+    # checkbox, so it is written for the person granting it.
+    REGISTRY = {
+      "profile.view" => [ "People", "See employee profiles" ],
+      "profile.manage" => [ "People", "Create and edit employee profiles, onboard and offboard" ],
+      "attendance.view" => [ "Attendance", "See attendance records" ],
+      "attendance.manage" => [ "Attendance", "Correct punches and decide regularization tickets" ],
+      "leave.request" => [ "Leave", "Apply for leave and comp-off" ],
+      "leave.view" => [ "Leave", "See leave requests and balances" ],
+      "leave.approve" => [ "Leave", "Approve, reject and cancel leave and comp-off" ],
+      "leave.manage" => [ "Leave", "Adjust balances, configure leave types and holidays" ],
+      "payroll.view" => [ "Payroll", "See payroll runs and salary slips" ],
+      "payroll.manage" => [ "Payroll", "Create, compute, finalize, unlock and publish payroll" ],
+      "payroll.export" => [ "Payroll", "Download the payout register, including bank details" ],
+      "salary.view" => [ "Payroll", "See salary structures" ],
+      "salary.manage" => [ "Payroll", "Set and revise salary structures" ],
+      "appraisal.view" => [ "Growth", "See appraisals" ],
+      "appraisal.manage" => [ "Growth", "Write, share and act on appraisals and promotions" ],
+      "resignation.view" => [ "Lifecycle", "See resignations" ],
+      "resignation.manage" => [ "Lifecycle", "Accept resignations and set the last working day" ],
+      "settings.manage" => [ "Administration", "Change company settings, offices and policy" ],
+      "audit.view" => [ "Administration", "Read the audit trail" ],
+      "audit.view_money" => [ "Administration", "Read audit rows about pay, appraisals and promotions" ],
+      "role.manage" => [ "Administration", "Create roles and grant permissions" ]
+    }.freeze
+
+    KEYS = REGISTRY.keys.freeze
+
+    def self.valid?(key) = REGISTRY.key?(key.to_s)
+
+    # Raises rather than returning false: an unknown key in a controller is a
+    # typo that would otherwise read as "nobody may do this", which fails in
+    # the safe direction but silently, and is then very hard to find.
+    def self.validate!(key)
+      return key.to_s if valid?(key)
+
+      raise ArgumentError, "Unknown HrLite permission #{key.inspect}. " \
+                           "Declare it in HrLite::Permissions::REGISTRY first."
+    end
+
+    def self.group(key) = REGISTRY.fetch(key.to_s).first
+    def self.description(key) = REGISTRY.fetch(key.to_s).last
+
+    def self.grouped
+      REGISTRY.group_by { |_key, (group, _)| group }
+              .transform_values { |pairs| pairs.map(&:first) }
+    end
+
+    # Does `held` satisfy a requirement for `needed`?
+    def self.scope_covers?(held, needed)
+      SCOPE_RANK.fetch(held.to_sym) >= SCOPE_RANK.fetch(needed.to_sym)
+    end
+  end
+end

data/lib/hr_lite/role_seeds.rb

@@ -0,0 +1,81 @@
+module HrLite
+  # The six roles an install starts with. They are a STARTING POINT, not a
+  # ladder in code: an install is expected to edit the grants, and `roles:seed`
+  # never overwrites a role that already exists.
+  #
+  # Read the scopes as the interesting part. Manager and HR hold the same
+  # leave.approve key — the difference between them is `team` and `all`, which
+  # is the whole reason scope lives on the grant.
+  module RoleSeeds
+    # A method, not a constant: the keys are Role constants, and this file is
+    # required while the gem loads, long before Active Record models exist.
+    def self.definitions
+      {
+      Role::EMPLOYEE => {
+        description: "Self-service only: own attendance, leave, documents and payslips.",
+        grants: {
+          "leave.request" => "self", "leave.view" => "self",
+          "attendance.view" => "self", "payroll.view" => "self",
+          "profile.view" => "self", "appraisal.view" => "self",
+          "resignation.view" => "self"
+        }
+      },
+      Role::MANAGER => {
+        description: "Everything an employee has, plus their reports' attendance and leave.",
+        grants: {
+          "leave.request" => "self", "leave.view" => "team", "leave.approve" => "team",
+          "attendance.view" => "team", "attendance.manage" => "team",
+          "payroll.view" => "self", "profile.view" => "team",
+          "appraisal.view" => "self", "resignation.view" => "self"
+        }
+      },
+      Role::HR => {
+        description: "Day-to-day operations for everyone: attendance, leave, holidays, tickets.",
+        grants: {
+          "leave.request" => "self", "leave.view" => "all", "leave.approve" => "all",
+          "leave.manage" => "all", "attendance.view" => "all", "attendance.manage" => "all",
+          "profile.view" => "all", "payroll.view" => "self",
+          "appraisal.view" => "self", "resignation.view" => "all"
+        }
+      },
+      Role::FINANCE => {
+        description: "Payroll and pay data. No authority over people or policy.",
+        grants: {
+          "leave.request" => "self", "leave.view" => "self",
+          "attendance.view" => "all", "profile.view" => "all",
+          "payroll.view" => "all", "payroll.manage" => "all", "payroll.export" => "all",
+          "salary.view" => "all", "salary.manage" => "all",
+          "audit.view" => "all", "audit.view_money" => "all"
+        }
+      },
+      Role::LEADERSHIP => {
+        description: "People and policy for everyone — deliberately NOT pay.",
+        grants: {
+          "leave.request" => "self", "leave.view" => "all", "leave.approve" => "all",
+          "leave.manage" => "all", "attendance.view" => "all", "attendance.manage" => "all",
+          "profile.view" => "all", "profile.manage" => "all",
+          "resignation.view" => "all", "resignation.manage" => "all",
+          "settings.manage" => "all", "audit.view" => "all", "payroll.view" => "self"
+        }
+      },
+      Role::SUPER_ADMIN => {
+        description: "Everything, including pay, appraisals and who holds which role.",
+        grants: Permissions::KEYS.to_h { |key| [ key, "all" ] }
+      }
+      }.freeze
+    end
+
+    # Creates any role that does not exist yet and leaves every existing one
+    # exactly as the install has tuned it — the same contract as the leave-type
+    # seed. Returns the names it created.
+    def self.call
+      definitions.filter_map do |name, definition|
+        next if Role.exists?(name: name)
+
+        role = Role.create!(name: name, description: definition[:description], system: true)
+        role.replace_grants!(definition[:grants])
+        name
+      end
+    end
+  end
+end

data/lib/hr_lite/statutory_rate_card.rb

@@ -3,9 +3,13 @@ module HrLite
   # is a one-hash edit that gets code review and a spec diff, never an
   # inline-constant hunt.
   #
-  # VERIFY WITH A CA before the first run of any new financial year; the
-  # FY 2026-27 card ships with FY 2025-26 figures pending confirmation of
-  # the Feb 2026 Finance Act.
+  # VERIFY WITH A CA before the first run of any new financial year. Adding
+  # a year is one new dated entry in CARDS; nothing else changes.
+  #
+  # When no card exists for a run's financial year the lookup falls back to
+  # the newest one it has — payroll cannot simply stop every April — but
+  # `warning_for` says so on the run, and `PayrollRunProcessor` puts that
+  # sentence in front of every other warning until a card is added.
   module StatutoryRateCard
     def self.r(value) = BigDecimal(value.to_s)
     private_class_method :r
@@ -58,8 +62,44 @@ module HrLite
     }.freeze
 
     def self.for(period_month)
-      effective = CARDS.keys.sort.reverse.find { |date| date <= period_month }
-      effective ? CARDS[effective] : CARDS[CARDS.keys.min]
+      CARDS[effective_date_for(period_month)]
+    end
+
+    # Which card a run will actually use. A month older than every card
+    # borrows the earliest one — see `predates_cards?`, which says so.
+    def self.effective_date_for(period_month)
+      CARDS.keys.sort.reverse.find { |date| date <= period_month } || CARDS.keys.min
+    end
+
+    # The card in force is from an EARLIER financial year than the run. The
+    # lookup still returns figures — it has to, or payroll would stop dead
+    # every April — so the run carries the warning instead.
+    def self.stale_for?(period_month)
+      FinancialYear.before?(effective_date_for(period_month), period_month)
+    end
+
+    # The run is older than every card we ship, so it is being computed on
+    # rates that had not been announced yet.
+    def self.predates_cards?(period_month)
+      period_month < CARDS.keys.min
+    end
+
+    # One sentence naming both the run's FY and the card's, or nil when they
+    # match. Rendered verbatim in the run's warnings list.
+    def self.warning_for(period_month)
+      card_fy = FinancialYear.label(effective_date_for(period_month))
+      run_fy  = FinancialYear.label(period_month)
+
+      if predates_cards?(period_month)
+        "Payroll for FY #{run_fy} is being computed on the FY #{card_fy} " \
+        "statutory card — no card ships for a year that early. PF, ESI, PT " \
+        "and TDS on this run are not the rates that applied. Verify with your CA."
+      elsif stale_for?(period_month)
+        "Payroll for FY #{run_fy} is being computed on the FY #{card_fy} " \
+        "statutory card — no card ships for FY #{run_fy} yet. PF, ESI, PT and " \
+        "TDS on this run use last year's rates. Add a CA-verified card for " \
+        "FY #{run_fy} before publishing."
+      end
     end
   end
 end

data/lib/hr_lite/version.rb

@@ -1,3 +1,3 @@
 module HrLite
-  VERSION = "0.5.2"
+  VERSION = "0.6.0"
 end