hr_lite 0.5.3 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdcc58ee5fdba440b0f70b9f22b85d85d20ef02f16c92481d4aad89a2395489f
-  data.tar.gz: f705fe091062bbe92246fd19fb1615c9fd9e0f2c6ed34ece293d155cc81879b1
+  metadata.gz: 7dd5723f67a89de78893c7ef752581da400b8703fb60876ad7d283e280308d31
+  data.tar.gz: d8e517a4a80bb2026de50a9f30b7837b37b785d02a5aea79802ad72b78fcc630
 SHA512:
-  metadata.gz: c674e21d22c69a6b2ff5e51cbbb329f166140054212d81a2582c5d0b421350a732c94ae2b8074e4da15f4b510f9a0fa5bfceda84c633b57def295c2066276370
-  data.tar.gz: 514bf9fa94450d2ccdd4a7443125ec355dd4d68e99c264eac62fe3b5b3be2034a17a64c94571ef51580b97a8ebd59ba85e0a05a55474e3ec80dd9a4ebf798a7d
+  metadata.gz: ea7291efd85233dfabf368fdc2355f8050920a22e324ea9f0ac083ba10040aaacaf125f93ed2d89b94e3ab05ed496375d69a6499af66372a974498677a30a18b
+  data.tar.gz: 1c1ad921b96ae6d778711b61b62501b5a8fa2e6cfd08cb8fd2c162bc01d37c7f048bc9637a617f1eebcac2f51a01e669cff89d94adf3bd48724b7cb9c7959a05

data/CHANGELOG.md

@@ -7,6 +7,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-08-18
+
+Access stops being three lambdas and becomes a role table. **Breaking**, with
+an upgrade path that is designed not to be: the migration reads your own
+configuration and lands everybody where they already were.
+
+**Adds two migrations.** The first creates the role tables; the second seeds
+the built-in roles and derives assignments from your existing email lists,
+printing who it put where.
+
+### Fixed
+
+- **Any admin could approve anybody's leave.** Every admin screen gated on a
+  tier and then acted on `Model.find(params[:id])`, so whoever could decide
+  leave could decide everyone's. `manager_id` sat on the profile driving
+  nothing but the org chart. There is now a Manager role at `team` scope,
+  every list is narrowed through the relation, and every member action
+  re-checks the row.
+- **Two of the three tiers were a string match on `user.email`** — a mutable,
+  host-owned, unverified column that each host had to remember never to let
+  anybody edit. Roles are rows now.
+
+### Added
+
+- `HrLite::Permissions` — the declared vocabulary. A grant is a (role, key,
+  scope) row, so an unknown key cannot be stored, and asking about one raises
+  rather than quietly answering "no".
+- `HrLite::Access` — resolves what somebody may do and whose rows it reaches,
+  memoized per request. `can?`, `reaches?`, `visible_user_ids`,
+  `scope_relation`.
+- Controller helpers `hr_can?`, `hr_reaches?`, `hr_require_permission!`,
+  `hr_require_reach!`, `hr_scope`.
+- `HrLite.can?`, `HrLite.reaches?`, `HrLite.users_holding` for host code.
+- A Roles screen (`/admin/roles`, behind `role.manage`) for grants and
+  assignments. Built-in roles cannot be renamed or deleted, and the last
+  person able to manage roles cannot be removed from the role that lets them.
+- `rake hr_lite:roles`, and `hr_lite:seed` now seeds roles too.
+
+### Changed
+
+- `HrLite.admin?`, `.leadership?` and `.superadmin?` read off roles. They
+  still exist because views, hosts and the notification fan-out call them.
+- `config.legacy_tier_checks` (default `false`) hands authority back to the
+  pre-0.6.0 lambdas for a host mid-migration. Honoured for one minor version;
+  **removed in 0.7.0**.
+- `HrLite.admin_users` is one query over the grant tables rather than
+  instantiating every employee and asking.
+- Branch-coverage floor 90% -> 90.5%.
+
 ## [0.5.3] - 2026-08-17
 
 Correctness and traceability pass, ahead of the permissions work in 0.6.0.
@@ -409,7 +458,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.5.3...HEAD
+[Unreleased]: https://github.com/kshtzkr/hr_lite/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/kshtzkr/hr_lite/compare/v0.5.3...v0.6.0
 [0.5.3]: https://github.com/kshtzkr/hr_lite/compare/v0.5.2...v0.5.3
 [0.5.2]: https://github.com/kshtzkr/hr_lite/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/kshtzkr/hr_lite/compare/v0.5.0...v0.5.1

data/README.md

@@ -14,8 +14,8 @@ auth, it does the HR.
 
 - Mountable engine, isolated namespace (`HrLite`), tables prefixed `hr_lite_`.
 - Bring your own users: any user model and auth (Devise or otherwise) via config hooks.
-- Access tiers: employee (self-service), admin (day-to-day operations),
-  leadership (policy and people), and an optional superadmin tier for money.
+- Roles and permissions: a seeded role table you re-cut, where each grant
+  carries the scope it reaches — their own records, their team's, or everyone's.
 - One event bus routes every HR event to in-app bells, employee emails and a
   leadership fan-out, with an append-only audit trail of governing changes.
 - Self-contained UI: mobile-first, dependency-free JS, theming through CSS
@@ -28,7 +28,7 @@ auth, it does the HR.
 - [Installation](#installation)
 - [Quick start (sandbox)](#quick-start-sandbox)
 - [Configuration](#configuration)
-- [Access tiers](#access-tiers)
+- [Roles and permissions](#roles-and-permissions)
 - [Features](#features)
   - [Attendance and geolocation](#attendance-and-geolocation)
   - [Leave, comp-off and regularization](#leave-comp-off-and-regularization)
@@ -148,34 +148,70 @@ end
 override it, plus the full event/notification matrix. `parent_controller` is
 resolved once at boot — restart after changing it.
 
-## Access tiers
-
-Authorization is layered on top of the checks you provide. There is no separate
-role table; a user's tier is derived per request.
-
-- **Employee** — every signed-in user. All self-service screens are scoped to
-  `current_user` (asking for someone else's record 404s), so a new hire is
-  never locked out.
-- **Admin** (`admin_check`, or anyone in leadership) — day-to-day operations:
-  team attendance, leave and regularization decisions, the overview board.
-- **Leadership** (`leadership_check` only — admin is not enough) — policy and
-  people: leave types, offices, holidays, the weekend rule, employee profiles,
-  onboarding/offboarding, the audit trail. Every leadership mutation writes an
-  append-only `hr_lite_audit_logs` row and emails leadership with the diff.
-- **Superadmin (money)** (`superadmin_check`) — salary structures, payroll
-  runs, salary-slip administration, appraisals and promotions. Set
-  `superadmin_emails` to a subset of leadership to separate money from policy.
-  Left empty (the default), the money tier is the leadership tier.
-
-Leadership is a list you control, not code. The generated initializer reads it
-from `HR_LEADERSHIP_EMAILS` (a comma-separated list) so you can change who
-governs without a deploy — that env var is a convention in the initializer the
-generator writes, not something the gem reads on its own. You can drop the env
-var and assign `c.leadership_emails` directly, or replace `c.leadership_check`
-to derive leadership some other way.
-
-`HrLite.admin?(user)`, `HrLite.leadership?(user)` and `HrLite.superadmin?(user)`
-are available if you need the same checks in host code.
+## Roles and permissions
+
+Authorization is a **role table**, seeded and then yours to re-cut. A
+permission is a KEY plus a SCOPE:
+
+| | |
+|---|---|
+| key | what the action is — `leave.approve`, `payroll.manage`, `attendance.view` |
+| scope | whose records it reaches — `self`, `team` (their reports) or `all` |
+
+That is why there is no `leave.approve_own` / `_team` / `_all` triple. One key
+with three possible scopes says the same thing with a third of the surface,
+and it is what makes a **Manager** expressible: `leave.approve` at `team`.
+
+Six roles ship. They are a starting point, not a ladder — `hr_lite:seed`
+creates any that are missing and never touches one you have tuned.
+
+| Role | Reaches |
+|---|---|
+| Employee | their own leave, attendance, profile and payslips |
+| Manager | the above, plus their reports' leave and attendance |
+| HR | leave, attendance, holidays and tickets for everyone |
+| Finance | payroll, salary structures, the payout register, the money audit |
+| Leadership | people and policy for everyone — deliberately **not** pay |
+| Super Admin | everything, including who holds which role |
+
+Grants are edited on the Roles screen (`/admin/roles`, behind `role.manage`).
+Built-in roles cannot be renamed or deleted — the seed and the upgrade path
+identify them by name — but every permission inside them can change. The last
+person who can manage roles cannot be removed from the role that lets them;
+there is no way back from that without a console.
+
+### In your own code
+
+```ruby
+HrLite.can?(user, "leave.approve", scope: :team)  # may they, at all?
+HrLite.reaches?(user, "leave.approve", employee)  # may they, for THIS person?
+HrLite.users_holding("payroll.manage")            # everyone who can
+```
+
+Controllers get `hr_can?`, `hr_reaches?`, `hr_require_permission!`,
+`hr_require_reach!` and `hr_scope(relation, key)`. Reaching a screen and
+reaching a particular person's row are separate questions — an index is
+narrowed with `hr_scope` and each member action re-checks with
+`hr_require_reach!`, which 404s rather than 403s so a stranger does not learn
+that the other person exists.
+
+`HrLite.admin?`, `HrLite.leadership?` and `HrLite.superadmin?` still work and
+are read off roles.
+
+### Upgrading from the email lists (pre-0.6.0)
+
+Access used to come from three lambdas, two of which matched the user's
+`email` — a mutable, host-owned, unverified column that every host then had to
+remember never to let anybody edit.
+
+The upgrade migration reads your existing configuration and lands everybody
+where they already were: `superadmin_emails` to Super Admin,
+`leadership_emails` to Leadership, `admin_check` to HR, everyone to Employee.
+It prints who it put where, and it leaves a host that has already assigned
+roles by hand alone.
+
+Set `config.legacy_tier_checks = true` to keep the old lambdas in charge while
+you migrate. It is honoured for one minor version and removed in 0.7.0.
 
 ## Features
 

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

@@ -4,14 +4,18 @@ module HrLite
       # Team day view: everyone × their punch/status for one date.
       def index
         @date = parse_date_param(params[:date])
+        # A manager's board is their reports; HR's is the company. Both read
+        # the same screen — the difference is one permission scope.
+        visible = hr_access.visible_user_ids("attendance.view")
         @employees = HrLite.employees
+        @employees = @employees.select { |user| visible.include?(user.id) } if visible
         @records = AttendanceRecord.for_date(@date).where(user_id: @employees.map(&:id)).index_by(&:user_id)
         @flagged_count = @records.values.count(&:flagged?)
       end
 
       # One employee's month + the regularization form for ?date=.
       def show
-        @employee = HrLite.user_klass.find(params[:user_id])
+        @employee = find_visible_employee
         @month = parse_month_param(params[:month])
         @day_status = DayStatus.new(user: @employee, range: @month.beginning_of_month..@month.end_of_month)
         @counts = @day_status.counts
@@ -23,7 +27,7 @@ module HrLite
       # Clearing both punch times deletes the record (that is how an
       # erroneous punch is removed).
       def update
-        @employee = HrLite.user_klass.find(params[:user_id])
+        @employee = find_manageable_employee
         date = parse_date_param(params[:date])
         record = AttendanceRecord.find_or_initialize_by(user_id: @employee.id, date: date)
 
@@ -74,6 +78,18 @@ module HrLite
 
       private
 
+      # Viewing somebody's month and rewriting their punches are different
+      # authorities, so they resolve through different permissions — a role
+      # can be given the board without being given the pencil.
+      def find_visible_employee = employee_within("attendance.view")
+      def find_manageable_employee = employee_within("attendance.manage")
+
+      def employee_within(permission)
+        employee = HrLite.user_klass.find(params[:user_id])
+        hr_require_reach!(permission, employee)
+        employee
+      end
+
       def log_regularization(record, note, removed:)
         AuditLog.record!(
           action: removed ? "destroy" : "regularize", subject: record, actor: hr_current_user,

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

@@ -1,15 +1,25 @@
 module HrLite
   module Admin
-    # Day-to-day operations tier: overview board, team attendance,
-    # leave decisions, balance adjustments. Leadership members are
-    # allowed too — governing implies at least operational visibility.
+    # Day-to-day operations: the overview board, team attendance, leave
+    # decisions, balance adjustments.
+    #
+    # The gate is now "can you decide somebody's leave, or fix somebody's
+    # attendance" rather than "are you an admin". That is what admits a
+    # MANAGER to these screens for the first time — at `team` scope, which
+    # every controller below then enforces row by row. Reaching the screen
+    # and reaching a particular person's row are two separate questions, and
+    # conflating them is precisely the bug this replaces.
     class BaseController < ApplicationController
-      before_action :require_hr_admin!
+      before_action :require_operations_access!
 
       private
 
-      def require_hr_admin!
-        hr_access_denied unless hr_admin? || hr_leadership?
+      def require_operations_access!
+        return if hr_can?("leave.approve", scope: :team) ||
+                  hr_can?("attendance.manage", scope: :team) ||
+                  hr_can?("leave.view", scope: :team)
+
+        hr_access_denied
       end
     end
   end

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

@@ -3,15 +3,16 @@ module HrLite
     class CompOffRequestsController < BaseController
       def index
         @status = params[:status].presence_in(CompOffRequest::STATUSES) || "pending"
-        @requests = paginate(CompOffRequest.includes(:user).where(status: @status).recent_first)
+        @requests = paginate(hr_scope(CompOffRequest.includes(:user).where(status: @status).recent_first,
+                                      "leave.view"))
       end
 
       def show
-        @request = CompOffRequest.find(params[:id])
+        @request = find_decidable
       end
 
       def approve
-        request = CompOffRequest.find(params[:id])
+        request = find_decidable
         request.approve!(actor: hr_current_user, note: params[:decision_note].presence)
         redirect_to admin_comp_off_requests_path,
                     notice: "Approved — #{request.credit_days.to_f} day credited."
@@ -22,7 +23,7 @@ module HrLite
       end
 
       def reject
-        request = CompOffRequest.find(params[:id])
+        request = find_decidable
         note = params[:decision_note].to_s.strip
         if note.blank?
           return redirect_to admin_comp_off_request_path(request), alert: "A note is required to reject."
@@ -33,6 +34,17 @@ module HrLite
       rescue ActiveRecord::RecordInvalid
         redirect_to admin_comp_off_request_path(request), alert: "Only pending requests can be decided."
       end
+
+      private
+
+      # A manager decides for their own reports; HR decides for everyone.
+      # Scoped through the relation, so reaching for somebody else's report
+      # is a 404 rather than a 403 that confirms the person exists.
+      def decidable
+        hr_scope(CompOffRequest.all, "leave.approve")
+      end
+
+      def find_decidable = decidable.find(params[:id])
     end
   end
 end

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

@@ -1,17 +1,20 @@
 module HrLite
   module Admin
-    # Governing tier: anything that changes policy or money — leave types,
-    # settings, office locations, holidays, employee profiles, salary
-    # structures, payroll, appraisals, audit trail. Leadership ONLY;
-    # being a host-app admin is not enough.
+    # Governing screens: policy and people for the whole company — leave
+    # types, settings, office locations, holidays, employee profiles,
+    # resignations, the audit trail.
+    #
+    # `profile.manage` at `all` is the key, because governing is exactly the
+    # authority to change somebody else's record. Reaching an operations
+    # screen is not enough, and neither is managing a team.
     class LeadershipController < BaseController
-      skip_before_action :require_hr_admin!
-      before_action :require_hr_leadership!
+      skip_before_action :require_operations_access!
+      before_action :require_governing_access!
 
       private
 
-      def require_hr_leadership!
-        hr_access_denied unless hr_leadership?
+      def require_governing_access!
+        hr_require_permission!("profile.manage", scope: :all)
       end
     end
   end

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

@@ -4,16 +4,20 @@ module HrLite
       def index
         scope = LeaveRequest.includes(:leave_type, :user).recent_first
         @status = params[:status].presence_in(LeaveRequest::STATUSES) || "pending"
-        @requests = paginate(scope.where(status: @status))
+        # A manager's queue is their own reports. HR's is everybody's. Scoping
+        # the LIST as well as the decision matters: an index that shows a row
+        # the member action then refuses is a worse screen than one that never
+        # showed it.
+        @requests = paginate(hr_scope(scope.where(status: @status), "leave.view"))
       end
 
       def show
-        @request = LeaveRequest.includes(:leave_type).find(params[:id])
+        @request = decidable.includes(:leave_type).find(params[:id])
         @balance = @request.balance
       end
 
       def approve
-        request = LeaveRequest.find(params[:id])
+        request = find_decidable
         if request.approve!(actor: hr_current_user, note: params[:decision_note].presence)
           redirect_to admin_leave_requests_path, notice: "Leave approved."
         else
@@ -30,7 +34,7 @@ module HrLite
       # while the person was unreachable, or after they were offboarded, could
       # not be released at all, and the quota stayed spent.
       def cancel
-        request = LeaveRequest.find(params[:id])
+        request = find_decidable
         if request.cancellable_by?(hr_current_user)
           request.cancel!(actor: hr_current_user)
           redirect_to admin_leave_requests_path, notice: "Leave cancelled — the balance is released."
@@ -41,7 +45,7 @@ module HrLite
       end
 
       def reject
-        request = LeaveRequest.find(params[:id])
+        request = find_decidable
         note = params[:decision_note].to_s.strip
         if note.blank?
           return redirect_to admin_leave_request_path(request), alert: "A note is required to reject."
@@ -52,6 +56,18 @@ module HrLite
       rescue ActiveRecord::RecordInvalid
         redirect_to admin_leave_request_path(request), alert: "Only pending requests can be decided."
       end
+
+      private
+
+      # Requests this person may actually decide. A manager reaching for
+      # somebody else's report gets a 404 through the scoped relation rather
+      # than a 403 — the same shape every employee-tier screen already uses,
+      # and it does not confirm that the other person exists.
+      def decidable
+        hr_scope(LeaveRequest.all, "leave.approve")
+      end
+
+      def find_decidable = decidable.find(params[:id])
     end
   end
 end

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

@@ -3,15 +3,16 @@ module HrLite
     class RegularizationRequestsController < BaseController
       def index
         @status = params[:status].presence_in(RegularizationRequest::STATUSES) || "pending"
-        @requests = paginate(RegularizationRequest.includes(:user).where(status: @status).recent_first)
+        @requests = paginate(hr_scope(RegularizationRequest.includes(:user).where(status: @status).recent_first,
+                                      "attendance.view"))
       end
 
       def show
-        @request = RegularizationRequest.find(params[:id])
+        @request = find_decidable
       end
 
       def approve
-        request = RegularizationRequest.find(params[:id])
+        request = find_decidable
         request.approve!(actor: hr_current_user, note: params[:decision_note].presence)
         redirect_to admin_regularization_requests_path, notice: "Ticket approved — attendance fixed."
       rescue RegularizationRequest::InvalidMerge => e
@@ -22,7 +23,7 @@ module HrLite
       end
 
       def reject
-        request = RegularizationRequest.find(params[:id])
+        request = find_decidable
         note = params[:decision_note].to_s.strip
         if note.blank?
           return redirect_to admin_regularization_request_path(request), alert: "A note is required to reject."
@@ -33,6 +34,17 @@ module HrLite
       rescue ActiveRecord::RecordInvalid
         redirect_to admin_regularization_request_path(request), alert: "Only pending tickets can be decided."
       end
+
+      private
+
+      # A manager decides for their own reports; HR decides for everyone.
+      # Scoped through the relation, so reaching for somebody else's report
+      # is a 404 rather than a 403 that confirms the person exists.
+      def decidable
+        hr_scope(RegularizationRequest.all, "attendance.manage")
+      end
+
+      def find_decidable = decidable.find(params[:id])
     end
   end
 end

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

@@ -0,0 +1,63 @@
+module HrLite
+  module Admin
+    # Putting people into a role and taking them out again. Same gate as the
+    # roles themselves: granting somebody payroll is the same act as holding
+    # it, so it sits behind `role.manage`.
+    class RoleAssignmentsController < LeadershipController
+      skip_before_action :require_governing_access!
+      before_action :require_role_management!
+
+      def create
+        role = Role.find(params[:role_id])
+        user = HrLite.user_klass.find(params[:user_id])
+        RoleAssignment.create!(role: role, user_id: user.id, granted_by_id: hr_current_user.id)
+
+        redirect_to edit_admin_role_path(role),
+                    notice: "#{HrLite.display_name(user)} added to #{role.name}."
+      rescue ActiveRecord::RecordInvalid
+        redirect_to edit_admin_role_path(params[:role_id]),
+                    alert: "They already hold that role."
+      end
+
+      def destroy
+        assignment = RoleAssignment.find(params[:id])
+        role = assignment.role
+        name = HrLite.display_name(assignment.user)
+
+        # Locking every last person out of role management is not recoverable
+        # from inside the app — it would need a console. Refuse instead.
+        if last_role_manager?(assignment)
+          return redirect_to edit_admin_role_path(role),
+                             alert: "#{name} is the only person who can manage roles. " \
+                                    "Give somebody else that permission first."
+        end
+
+        assignment.destroy!
+        redirect_to edit_admin_role_path(role), notice: "#{name} removed from #{role.name}.",
+                    status: :see_other
+      end
+
+      private
+
+      def require_role_management!
+        hr_require_permission!("role.manage", scope: :all)
+      end
+
+      def last_role_manager?(assignment)
+        return false unless HrLite.can?(assignment.user, "role.manage", scope: :all)
+
+        others = HrLite.users_holding("role.manage").where.not(id: assignment.user_id)
+        # Another of their OWN roles may still carry it, in which case
+        # removing this one changes nothing.
+        others.empty? && !still_manages_without?(assignment)
+      end
+
+      def still_manages_without?(assignment)
+        RoleGrant.joins(role: :role_assignments)
+                 .where(hr_lite_role_assignments: { user_id: assignment.user_id })
+                 .where.not(hr_lite_role_assignments: { id: assignment.id })
+                 .exists?(permission_key: "role.manage", scope: "all")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+module HrLite
+  module Admin
+    # Who may do what. Gated on `role.manage`, which by default only the
+    # money tier holds — the authority to grant yourself payroll is the
+    # authority to read everyone's pay, so it lives with the pay.
+    class RolesController < LeadershipController
+      skip_before_action :require_governing_access!
+      before_action :require_role_management!
+
+      def index
+        @roles = Role.alphabetical.includes(:role_grants, :role_assignments)
+      end
+
+      def new
+        @role = Role.new
+      end
+
+      def create
+        @role = Role.new(role_params)
+        if @role.save
+          @role.replace_grants!(grant_params)
+          redirect_to admin_roles_path, notice: "#{@role.name} created."
+        else
+          render :new, status: :unprocessable_entity
+        end
+      end
+
+      def edit
+        @role = Role.find(params[:id])
+      end
+
+      def update
+        @role = Role.find(params[:id])
+        if @role.update(role_params)
+          @role.replace_grants!(grant_params)
+          redirect_to admin_roles_path, notice: "#{@role.name} updated."
+        else
+          render :edit, status: :unprocessable_entity
+        end
+      end
+
+      def destroy
+        role = Role.find(params[:id])
+        if role.destroy
+          redirect_to admin_roles_path, notice: "#{role.name} deleted.", status: :see_other
+        else
+          redirect_to admin_roles_path, alert: role.errors.full_messages.to_sentence,
+                      status: :see_other
+        end
+      end
+
+      private
+
+      def require_role_management!
+        hr_require_permission!("role.manage", scope: :all)
+      end
+
+      def role_params
+        permitted = params.require(:role).permit(:name, :description)
+        # A built-in role's NAME is what the seed, the upgrade migration and
+        # the specs all identify it by; the model refuses a rename, and not
+        # sending one keeps the form from failing on an untouched field.
+        @role&.system? ? permitted.except(:name) : permitted
+      end
+
+      # The form posts the COMPLETE picture, so a permission absent from it is
+      # one being taken away. "none" is how the form says "not granted".
+      def grant_params
+        params.fetch(:grants, {}).permit(Permissions::KEYS).to_h
+      end
+    end
+  end
+end

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

@@ -1,20 +1,24 @@
 module HrLite
   module Admin
-    # Money tier: salary structures, payroll, slips, appraisals and
-    # promotions. Only config.superadmin_emails — ordinary leadership can
-    # govern policy and people but never sees another person's pay.
-    # The money tier stands on its own rather than layering on leadership: a
-    # payroll operator does not have to also govern people and policy.
-    # Inheriting the leadership check locked a configured superadmin who was
-    # absent from leadership_emails out of payroll entirely.
+    # Money screens: salary structures, payroll, slips, appraisals and
+    # promotions. Ordinary governing authority reaches none of it — leadership
+    # governs policy and people but never sees another person's pay.
+    #
+    # The money gate stands on its own rather than layering on the governing
+    # one: a payroll operator does not have to also govern people and policy.
+    # Stacking the two locked a configured money-tier user who was absent from
+    # the leadership list out of payroll entirely.
     class SuperadminController < LeadershipController
-      skip_before_action :require_hr_leadership!
-      before_action :require_hr_superadmin!
+      skip_before_action :require_governing_access!
+      before_action :require_money_access!
 
       private
 
-      def require_hr_superadmin!
-        hr_access_denied unless hr_superadmin?
+      # Deliberately payroll.manage rather than a "super admin" role name:
+      # roles are data an install re-cuts, and gating on a NAME would make
+      # renaming one a silent lock-out.
+      def require_money_access!
+        hr_require_permission!("payroll.manage", scope: :all)
       end
     end
   end