@jmruthers/pace-core 0.6.5 → 0.6.7

package/cursor-rules/{08-markup-quality.mdc → 05-styling.mdc}

@@ -7,6 +7,61 @@ rulesVersion: "2025-01-28"
 ---
 # Markup Quality Guide
 
+**📚 Human-Readable Standard**: See [5-styling-standards.md](../../packages/core/docs/standards/5-styling-standards.md) for complete documentation including **CRITICAL CSS configuration requirements**.
+
+**⚠️ IMPORTANT**: This rule is ALWAYS APPLIED. The standard includes required CSS setup that MUST be followed for pace-core components to render correctly.
+
+## AI Agent Instructions
+
+**When writing or modifying code, ALWAYS:**
+1. **Use pace-core components** - Never use native HTML elements when pace-core provides components
+2. **Use semantic HTML** - Always use semantic elements (`<main>`, `<section>`, `<article>`, etc.) instead of `<div>` wrappers
+3. **Never use inline styles** - Never use `style={{...}}`, always use pace-core components or Tailwind classes
+4. **Use Grid for layout** - Prefer CSS Grid over Flexbox for centering, two-dimensional layouts, and full-page layouts
+5. **Minimize elements** - Use the fewest elements possible, prefer React Fragments over wrapper divs
+6. **Check CSS setup** - Before using pace-core components, verify CSS is configured correctly (see checklist below)
+
+**Decision Tree: Markup & Styling**
+```
+1. What element should I use?
+   ├─ Button → <Button> from pace-core (not <button>)
+   ├─ Input → <Input> from pace-core (not <input>)
+   ├─ Page wrapper → <main> (not <div>)
+   ├─ Section → <section> (not <div>)
+   ├─ Article → <article> (not <div>)
+   └─ Navigation → <nav> (not <div>)
+
+2. Do I need a wrapper?
+   ├─ For React single root → Use Fragment (<>...</>)
+   ├─ For styling only → Apply to existing semantic parent
+   └─ For layout → Use Grid (grid place-items-center, grid grid-cols-*)
+
+3. How do I center content?
+   ├─ Both axes → grid place-items-center
+   └─ Single axis → flex (but prefer grid)
+
+4. Am I using inline styles?
+   ├─ YES → WRONG - Use pace-core component or Tailwind class
+   └─ NO → Continue
+```
+
+## ⚠️ CRITICAL: CSS Configuration Required
+
+**Before using pace-core components, you MUST configure CSS correctly.** Without proper configuration, pace-core components will appear unstyled or with incorrect styling.
+
+**MUST read the standard for complete CSS setup instructions**: [5-styling-standards.md](../../packages/core/docs/standards/5-styling-standards.md)
+
+**Quick checklist:**
+- [ ] `src/app.css` exists with `@import "tailwindcss";`
+- [ ] `@source` directives configured correctly (relative to CSS file location)
+- [ ] `@import "@jmruthers/pace-core/styles/core.css";` in `app.css`
+- [ ] All three color palettes defined (main, sec, acc) with all shades (50-950)
+- [ ] `app.css` imported in `main.tsx` (NOT `core.css` directly)
+
+**See the standard for detailed setup instructions and troubleshooting.**
+
+---
+
 This guide enforces clean markup standards, semantic HTML usage, and proper pace-core component patterns to ensure maintainable, accessible, and consistent code.
 
 ## pace-core First
@@ -17,18 +72,29 @@ This guide enforces clean markup standards, semantic HTML usage, and proper pace
 
 ```tsx
 // ❌ WRONG: Custom button or native HTML element
-<button className="btn-primary">Click me</button>
-<input type="text" className="form-input" />
+<button className="btn-primary" onClick={handleClick}>
+  Click me
+</button>
+<input 
+  type="text" 
+  className="form-input" 
+  value={value}
+  onChange={handleChange}
+/>
 
 // ✅ CORRECT: Use pace-core components
 import { Button, Input } from '@jmruthers/pace-core';
-<Button>Click me</Button>
-<Input type="text" />
+<Button onClick={handleClick}>Click me</Button>
+<Input 
+  type="text" 
+  value={value}
+  onChange={handleChange}
+/>
 ```
 
 ### MUST NOT: Add Custom Styles to pace-core Components
 
-**MUST NOT add custom styles when pace-core components already provide styling:**
+**NEVER add custom styles when pace-core components already provide styling. Use component variants/props instead.**
 
 ```tsx
 // ❌ WRONG: Overriding pace-core component styles
@@ -88,41 +154,45 @@ import { Button, Input } from '@jmruthers/pace-core';
 <footer>Footer</footer>
 ```
 
-### MUST NOT: Use `<div>` Elements
+### MUST: Prefer Semantic HTML (Limit `<div>`)
+
+**ALWAYS prefer semantic HTML elements** (`<main>`, `<section>`, `<article>`, `<header>`, `<footer>`, `<nav>`, lists, etc.).
+Using semantic elements improves accessibility, maintainability, and consistency.
 
-**MUST NOT use `<div>` elements (except for the first child of `<body>` in `index.html`, React portals, or when required by third-party libraries that mandate specific DOM structure):**
+#### `<div>` usage policy
+
+- **MUST NOT** use `<div>` when a clear semantic element exists.
+- `<div>` is **allowed only** for:
+  - purely presentational layout wrappers (flex/grid grouping) when no semantic element fits, OR
+  - React portal roots / app shell roots, OR
+  - third-party libraries that require specific DOM structure (document the reason in a short comment).
+
+#### Severity guidance (for audits)
+
+- **HIGH/BLOCKER**: `<div>` used in place of landmark/semantic structure (e.g., main page wrapper that should be `<main>`, navigation that should be `<nav>`, lists that should be `<ul>/<ol>`).
+- **MEDIUM**: `<div>` used as a generic wrapper inside semantic structure where it could be a fragment or semantic element.
+- **LOW**: `<div>` used for unavoidable third-party structure with a comment justifying it.
+
+**Examples:**
 
 ```tsx
-// ❌ WRONG: Using div elements
-<div className="container">
-  <div className="content">Content</div>
+// ❌ WRONG: Non-semantic page structure
+<div className="page">
+  <div className="nav">...</div>
+  <div className="content">...</div>
 </div>
 
-// ✅ CORRECT: Use semantic elements or React Fragments
+// ✅ CORRECT: Semantic structure
 <main>
-  <section>Content</section>
+  <nav>...</nav>
+  <section>...</section>
 </main>
-// Or for grouping without semantic meaning:
-<>
-  <Component1 />
-  <Component2 />
-</>
-```
-
-### MUST: Choose Most Semantic Element
 
-**MUST choose the most semantically accurate element for the content:**
-
-```tsx
-// ✅ CORRECT: Choose appropriate semantic elements
-<main>Main content</main>
-<section>Section of content</section>
-<article>Article content</article>
-<header>Header content</header>
-<footer>Footer content</footer>
-<nav>Navigation</nav>
-<ul><li>List items</li></ul>
-<p>Paragraph text</p>
+// ✅ ACCEPTABLE: Layout-only wrapper (no semantic fit)
+// (Prefer fragments where possible)
+<section>
+  <div className="flex gap-2">...</div>
+</section>
 ```
 
 ## Typography & Styling
@@ -445,8 +515,8 @@ Before committing code, verify:
 
 ## Reference
 
-- **pace-core Components**: See `00-pace-core-compliance.mdc` for component usage
+- **pace-core Components**: See [01-pace-core-compliance.mdc](./01-pace-core-compliance.mdc) for component usage
 - **Semantic HTML**: https://developer.mozilla.org/en-US/docs/Glossary/Semantics
 - **React Fragments**: https://react.dev/reference/react/Fragment
-- **Accessibility**: See `06-code-quality.mdc` for accessibility requirements
+- **Accessibility**: See [04-code-quality.mdc](./04-code-quality.mdc) for accessibility requirements
 - **When in doubt**: Remove the element, remove the style, and rely on pace-core or semantic HTML

package/cursor-rules/06-security-rbac.mdc

@@ -0,0 +1,518 @@
+---
+description: Enforce RBAC contract compliance, RLS policy patterns, and security requirements
+globs: ["src/**/*.{ts,tsx,js,jsx}", "supabase/migrations/**/*.sql"]
+alwaysApply: false
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
+---
+# Security & RBAC Standards Guide
+
+**📚 Human-Readable Standard**: See [6-security-rbac-standards.md](../../packages/core/docs/standards/6-security-rbac-standards.md) for complete documentation including RLS policy patterns, helper functions, and security requirements.
+
+This guide enforces the **mandatory RBAC contract** and security patterns between pace-core and consuming apps.
+
+**⚠️ CRITICAL**: This contract is **non-negotiable**. See [RBAC Contract](../../packages/core/docs/rbac/RBAC_CONTRACT.md) for complete documentation.
+
+## AI Agent Instructions
+
+**When writing or modifying code, ALWAYS:**
+1. **Protect all pages** - Wrap every protected page with `PagePermissionGuard` (no exceptions)
+2. **Use pace-core hooks directly** - Never create wrapper functions around `useCan` or `useResourcePermissions`
+3. **Use RESOURCE_NAMES constants** - Never use string literals in `useResourcePermissions` calls
+4. **Validate all inputs** - Always validate user input with Zod schemas before processing
+5. **Never expose internals** - Never show SQL errors, stack traces, or internal details to users
+6. **Use helper functions in RLS** - Always use STABLE SECURITY DEFINER helper functions, never subqueries
+7. **Sanitize logs** - Never log passwords, tokens, or sensitive data
+
+**Decision Tree: Security & Permissions**
+```
+1. Is this a protected page?
+   ├─ YES → Wrap with PagePermissionGuard (no exceptions)
+   └─ NO → Continue
+
+2. Do I need to check permissions?
+   ├─ YES → Use pace-core hooks directly (useCan, useResourcePermissions)
+   └─ NO → Continue
+
+3. Am I handling user input?
+   ├─ YES → Validate with Zod schema
+   └─ NO → Continue
+
+4. Am I logging or showing errors?
+   ├─ YES → Never expose internals, sanitize sensitive data
+   └─ NO → Continue
+```
+
+## MUST: Use PagePermissionGuard for All Protected Pages
+
+**MUST wrap all protected pages with `PagePermissionGuard`:**
+
+```tsx
+// ✅ CORRECT
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
+
+function DashboardPage() {
+  return (
+    <PagePermissionGuard pageName="dashboard" operation="read">
+      <DashboardContent />
+    </PagePermissionGuard>
+  );
+}
+```
+
+**MUST NOT:**
+- Render protected content without `PagePermissionGuard`
+- Create wrapper components around `PagePermissionGuard`
+- Bypass page-level permission checks
+
+```tsx
+// ❌ FORBIDDEN - No guard
+function DashboardPage() {
+  return <DashboardContent />;  // ERROR: Unprotected page
+}
+
+// ❌ FORBIDDEN - Wrapper component
+function EventPageGuard({ pageName, children }) {
+  return <PagePermissionGuard pageName={pageName}>{children}</PagePermissionGuard>;
+}
+```
+
+## MUST: Use pace-core Permission Hooks Directly
+
+**MUST use pace-core hooks directly without wrappers:**
+
+```tsx
+// ✅ CORRECT
+import { useCan, useResourcePermissions } from '@jmruthers/pace-core/rbac';
+import { RESOURCE_NAMES } from '@/config/resource-names';
+
+function MyComponent() {
+  const { canUpdate, canDelete } = useResourcePermissions(RESOURCE_NAMES.JOURNAL);
+  const canEdit = useCan(userId, scope, 'update:users');
+  // Use canUpdate, canDelete, canEdit directly
+}
+```
+
+**MUST NOT:**
+- Create wrapper functions around permission hooks
+- Create custom permission utility functions
+- Use string literals in `useResourcePermissions` calls
+
+```tsx
+// ❌ FORBIDDEN - Wrapper function
+const canEdit = (postId: string) => {
+  const hasPermission = canUpdate('journal');
+  const post = posts.find(p => p.id === postId);
+  return hasPermission && !!post;
+};
+
+// ❌ FORBIDDEN - Custom utility
+function checkPermission(permission: string) {
+  // Custom logic...
+}
+
+// ❌ FORBIDDEN - String literal
+const { canUpdate } = useResourcePermissions('journal');
+```
+
+## MUST: Use RESOURCE_NAMES Constants
+
+**MUST use `RESOURCE_NAMES` constant object for all resource permission checks:**
+
+```tsx
+// ✅ CORRECT
+import { RESOURCE_NAMES } from '@/config/resource-names';
+const { canCreate, canUpdate, canDelete } = useResourcePermissions(RESOURCE_NAMES.JOURNAL);
+```
+
+**MUST NOT:**
+- Use string literals in `useResourcePermissions` calls
+- Hardcode resource names
+
+```tsx
+// ❌ FORBIDDEN - String literal
+const { canUpdate } = useResourcePermissions('journal');
+```
+
+## MUST: Use Standard AccessDenied Component
+
+**MUST use `AccessDenied` from pace-core for all access denied scenarios:**
+
+```tsx
+// ✅ CORRECT
+import { AccessDenied } from '@jmruthers/pace-core/rbac';
+
+<PagePermissionGuard 
+  pageName="dashboard" 
+  operation="read"
+  fallback={<AccessDenied />}
+>
+  <DashboardContent />
+</PagePermissionGuard>
+```
+
+**MUST NOT:**
+- Create custom access denied components
+- Use custom permission denied components
+
+```tsx
+// ❌ FORBIDDEN - Custom component
+function CustomAccessDenied() {
+  return <div>Access Denied</div>;
+}
+```
+
+## MUST: Use pace-core API for Permission Checks
+
+**MUST use pace-core API functions for programmatic permission checks:**
+
+```tsx
+// ✅ CORRECT
+import { isPermitted, isPermittedCached } from '@jmruthers/pace-core/rbac';
+
+const hasAccess = await isPermitted({
+  userId: 'user-123',
+  scope: { organisationId: 'org-456' },
+  permission: 'read:dashboard',
+  pageId: 'dashboard'
+});
+```
+
+**MUST NOT:**
+- Call RBAC RPC functions directly
+- Query RBAC tables directly (without `useSecureSupabase`)
+- Create custom RBAC helper functions
+
+```tsx
+// ❌ FORBIDDEN - Direct RPC call
+const { data } = await supabase.rpc('rbac_check_permission_simplified', {
+  p_user_id: userId,
+  p_permission: 'read:dashboard'
+});
+
+// ❌ FORBIDDEN - Direct table query
+const { data } = await supabase
+  .from('rbac_user_profiles')
+  .select('*');
+
+// ❌ FORBIDDEN - Custom RBAC helper
+function checkPermission(userId: string, permission: string) {
+  // Custom logic that bypasses pace-core
+}
+```
+
+## MUST: Use pace-core API in Edge Functions (No Exceptions)
+
+**Edge Functions (Deno serverless functions) MUST use pace-core's `isPermitted()` API function.** Edge Functions cannot use React hooks, but pace-core provides programmatic APIs that work outside React.
+
+**✅ CORRECT - Edge Function Pattern:**
+
+```typescript
+// supabase/functions/my-function/index.ts
+import { createClient } from 'jsr:@supabase/supabase-js@2';
+import { setupRBAC, isPermitted } from 'npm:@jmruthers/pace-core@^0.6.0/rbac';
+
+Deno.serve(async (req: Request) => {
+  // 1. Create Supabase client from request headers
+  const authHeader = req.headers.get('Authorization');
+  if (!authHeader) {
+    return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 });
+  }
+
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL') ?? '',
+    Deno.env.get('SUPABASE_ANON_KEY') ?? '',
+    {
+      global: {
+        headers: { Authorization: authHeader },
+      },
+    }
+  );
+
+  // 2. Get user from session
+  const { data: { user } } = await supabase.auth.getUser();
+  if (!user) {
+    return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 });
+  }
+
+  // 3. Setup RBAC (required before using isPermitted)
+  setupRBAC(supabase);
+
+  // 4. Extract organisation context from request (headers, body, or query params)
+  const organisationId = req.headers.get('x-organisation-id') || 
+                         (await req.json()).organisationId;
+
+  if (!organisationId) {
+    return new Response(JSON.stringify({ error: 'Organisation context required' }), { status: 400 });
+  }
+
+  // 5. Check permission using pace-core API
+  const hasPermission = await isPermitted({
+    userId: user.id,
+    scope: { organisationId },
+    permission: 'read:dashboard',
+    pageId: 'dashboard'
+  });
+
+  if (!hasPermission) {
+    return new Response(JSON.stringify({ error: 'Permission denied' }), { status: 403 });
+  }
+
+  // 6. Proceed with function logic
+  return new Response(JSON.stringify({ success: true }));
+});
+```
+
+**❌ FORBIDDEN - Custom RBAC Helper in Edge Functions:**
+
+```typescript
+// ❌ FORBIDDEN - Creating custom RBAC helper
+// supabase/functions/_shared/rbac.ts
+export async function checkPermission(userId: string, permission: string) {
+  // Custom logic that bypasses pace-core
+  const { data } = await supabase.rpc('rbac_check_permission_simplified', {
+    p_user_id: userId,
+    p_permission: permission
+  });
+  return data;
+}
+```
+
+**Why No Exceptions:**
+- pace-core provides `isPermitted()` API that works outside React
+- `setupRBAC()` initializes the engine with a Supabase client
+- No custom helpers needed - use pace-core APIs directly
+- Custom helpers bypass security validation, caching, and audit logging
+
+**Edge Function Requirements:**
+1. **MUST** call `setupRBAC(supabase)` before using `isPermitted()`
+2. **MUST** extract `userId` from Supabase auth session
+3. **MUST** extract `organisationId` from request (headers, body, or query params)
+4. **MUST** use `isPermitted()` with complete `PermissionCheck` input
+5. **MUST NOT** create custom RBAC helper functions
+6. **MUST NOT** call `rbac_check_permission_simplified` RPC directly
+
+## MUST: Use useSecureSupabase for RBAC Table Queries
+
+**If you must query RBAC tables (rare), MUST use `useSecureSupabase`:**
+
+```tsx
+// ✅ CORRECT
+import { useSecureSupabase } from '@jmruthers/pace-core/rbac';
+
+function MyComponent() {
+  const secureSupabase = useSecureSupabase();
+  // If your hook signature requires a client argument, pass ONLY the pace-core-provided client (never a local createClient()).
+  const { data } = await secureSupabase
+    .from('rbac_user_profiles')  // Allowed through secure client
+    .select('*');
+}
+```
+
+**MUST NOT query these tables directly:**
+- `rbac_organisation_roles`
+- `rbac_event_app_roles`
+- `rbac_global_roles`
+- `rbac_apps`
+- `rbac_app_pages`
+- `rbac_page_permissions`
+- `rbac_user_profiles`
+
+## MUST NOT: Use Hardcoded Role Checks
+
+**MUST NOT compare roles directly:**
+
+```tsx
+// ❌ FORBIDDEN - Hardcoded role check
+if (user.role === 'admin') {
+  // ...
+}
+```
+
+**MUST use pace-core APIs:**
+
+```tsx
+// ✅ CORRECT
+import { useAccessLevel, getRoleContext } from '@jmruthers/pace-core/rbac';
+
+const { accessLevel } = useAccessLevel(userId, scope);
+const roleContext = await getRoleContext({ userId, scope });
+```
+
+## MUST: Configure enforcePermissions Correctly
+
+**For event-based apps (where pages handle their own checks):**
+
+```tsx
+// ✅ CORRECT - Event-based app pattern
+<PaceAppLayout 
+  appName="MyApp"
+  enforcePermissions={false}  // Pages handle checks via PagePermissionGuard
+  // ...
+>
+```
+
+**For organisation-based apps (where layout handles checks):**
+
+```tsx
+// ✅ CORRECT - Organisation-based app pattern
+<PaceAppLayout 
+  appName="MyApp"
+  enforcePermissions={true}  // Layout handles checks
+  defaultPermission="read"
+  // ...
+>
+```
+
+## MUST: Setup RBAC Before Use
+
+**MUST call `setupRBAC()` before any RBAC usage:**
+
+```tsx
+// main.tsx - MUST be first
+import { setupRBAC } from '@jmruthers/pace-core/rbac';
+setupRBAC(supabase);
+// Then render app
+```
+
+## Enforcement
+
+These rules are enforced by ESLint rules (all ERROR severity):
+
+1. **`no-direct-rbac-rpc`** - Detects direct calls to `rbac_check_permission_simplified`
+2. **`no-direct-rbac-tables`** - Detects direct queries to RBAC tables
+3. **`no-bypass-page-guard`** - Detects routes without `PagePermissionGuard`
+4. **`no-custom-access-denied`** - Detects custom access denied components
+5. **`no-hardcoded-role-checks`** - Detects hardcoded role comparisons
+6. **`no-custom-permission-utilities`** - Detects custom permission utility functions
+7. **`no-resource-permission-string-literals`** - Detects string literals in `useResourcePermissions` calls
+8. **`no-permission-wrapper-functions`** - Detects wrapper functions around pace-core permission hooks
+
+## Common Mistakes to Avoid
+
+**When writing code, NEVER:**
+1. **Skip PagePermissionGuard** - Every protected page must be wrapped
+   ```tsx
+   // ❌ WRONG
+   function DashboardPage() {
+     return <DashboardContent />;
+   }
+   
+   // ✅ CORRECT
+   function DashboardPage() {
+     return (
+       <PagePermissionGuard pageName="dashboard" operation="read">
+         <DashboardContent />
+       </PagePermissionGuard>
+     );
+   }
+   ```
+
+2. **Create wrapper functions around permission hooks** - Use hooks directly
+3. **Use string literals in useResourcePermissions** - Always use RESOURCE_NAMES constants
+4. **Bypass input validation** - Always validate with Zod schemas
+5. **Expose internal errors** - Never show SQL, stack traces, or file paths to users
+6. **Log sensitive data** - Never log passwords, tokens, or PII
+
+## Compliance Checklist
+
+Before committing RBAC-related code, verify:
+
+- [ ] All protected pages use `PagePermissionGuard`
+- [ ] No wrapper components around `PagePermissionGuard`
+- [ ] No wrapper functions around permission hooks
+- [ ] All `useResourcePermissions` calls use `RESOURCE_NAMES` constants
+- [ ] No direct RPC calls to `rbac_check_permission_simplified`
+- [ ] No direct queries to RBAC tables (use `useSecureSupabase` if needed)
+- [ ] No hardcoded role checks (use `useAccessLevel` or `getRoleContext`)
+- [ ] No custom permission utility functions
+- [ ] All access denied scenarios use `AccessDenied` from pace-core
+- [ ] `enforcePermissions` configured correctly for app type
+- [ ] `setupRBAC()` called before any RBAC usage
+- [ ] Edge Functions use `isPermitted()` API (no custom RBAC helpers)
+- [ ] All RLS policies for authenticated users include super-admin checks
+- [ ] All `is_super_admin()` calls use explicit parameter (`safe_get_user_id_for_rls()`)
+- [ ] No security-critical functions use fallback strategies
+- [ ] ESLint rules pass without errors
+
+## MUST: Include Super-Admin Checks in RLS Policies
+
+**MUST include super-admin bypass in all RLS policies for authenticated users:**
+
+```sql
+-- ✅ CORRECT: Super-admin check included
+CREATE POLICY "rbac_select_table_name" ON table_name
+FOR SELECT TO authenticated
+USING (
+  organisation_id IS NOT NULL
+  AND (
+    is_super_admin(safe_get_user_id_for_rls())
+    OR check_user_organisation_access(organisation_id)
+  )
+);
+```
+
+**MUST NOT:**
+- Create RLS policies without super-admin checks (except for public/anonymous policies)
+- Use `is_super_admin()` without a parameter (relies on fallback strategies)
+- Create security-critical functions with fallback strategies
+
+```sql
+-- ❌ FORBIDDEN: Missing super-admin check
+CREATE POLICY "rbac_select_table_name" ON table_name
+FOR SELECT TO authenticated
+USING (
+  check_user_organisation_access(organisation_id)
+);
+
+-- ❌ FORBIDDEN: is_super_admin() without parameter
+CREATE POLICY "rbac_select_table_name" ON table_name
+FOR SELECT TO authenticated
+USING (
+  is_super_admin()  -- Missing parameter, uses fallback strategies
+  OR check_user_organisation_access(organisation_id)
+);
+```
+
+**MUST use explicit parameter passing:**
+
+```sql
+-- ✅ CORRECT: Explicit user ID parameter
+is_super_admin(safe_get_user_id_for_rls())
+```
+
+**MUST NOT create security-critical functions with fallback strategies:**
+
+```sql
+-- ❌ FORBIDDEN: Multiple fallback strategies
+CREATE FUNCTION is_super_admin(p_user_id UUID DEFAULT NULL)
+RETURNS boolean AS $$
+BEGIN
+  IF p_user_id IS NOT NULL THEN
+    v_user_id := p_user_id;
+  ELSE
+    v_user_id := auth.uid();  -- Fallback 1
+  END IF;
+  -- More fallbacks...
+END;
+$$;
+
+-- ✅ CORRECT: Required parameter, no fallbacks
+CREATE FUNCTION is_super_admin(p_user_id UUID)
+RETURNS boolean AS $$
+BEGIN
+  IF p_user_id IS NULL THEN
+    RETURN false;  -- Fail secure
+  END IF;
+  -- Check super-admin status
+END;
+$$;
+```
+
+## Reference
+
+- **RBAC Contract**: `packages/core/docs/rbac/RBAC_CONTRACT.md` - Complete contract documentation
+- **Migration Guide**: `packages/core/docs/rbac/MIGRATION_GUIDE.md` - Migrating to RBAC Contract v2.0.0
+- **Quick Start**: `packages/core/docs/rbac/quick-start.md` - Getting started guide
+- **API Reference**: `packages/core/docs/rbac/api-reference.md` - Complete API documentation
+- **RLS Standards**: [6-security-rbac-standards.md](../../packages/core/docs/standards/6-security-rbac-standards.md) - RLS policy patterns and super-admin requirements