RBAC management Akira

Source of truth

RBAC must stay coherent across:

1. docs/security/rbac-matrix.md role-permission matrix.
2. apps/backend/src/akira_backend/core/rbac_loader.py constants.
3. Static frontend permission gates in apps/frontend.

Run drift detection before merging RBAC changes:

scripts/audit_rbac.py

Expected clean result:

[rbac-audit] OK: zero drift

Adding a permission

1. Add the permission row in docs/security/rbac-matrix.md.
2. Add the permission to ALL_PERMISSIONS in rbac_loader.py.
3. Add role grants to ROLE_GRANTS matching the matrix.
4. Protect backend routes with @require_permission("<module>.<action>").
5. Gate frontend flows with the same static permission key when needed.
6. Run scripts/audit_rbac.py.

Removing a permission

1. Audit backend route decorators and frontend gates before removing it.
2. Remove the permission from the matrix and rbac_loader.py in the same change.
3. Remove or replace frontend gates that reference it.
4. Update RBAC seed or migration logic if the database needs cleanup.
5. Run scripts/audit_rbac.py.

Drift categories

• STALE_DOC: permission appears in the matrix but not in the loader.
• MISSING_DOC: permission appears in the loader but not in the matrix.
• ORPHAN_FRONTEND: frontend gate references a permission absent from the loader.
• INCOMPLETE_ROLE: matrix contains a role missing from loader grants.
• STALE_DOC_ROLE_GRANT: matrix grants a role-permission pair absent from loader grants.
• MISSING_DOC_ROLE_GRANT: loader grants a role-permission pair absent from the matrix.

Fix drift in the same pull request that changes RBAC so the role seed and UI gates remain auditable.