@jmruthers/pace-core 0.6.9 → 0.6.11

package/audit-tool/audits/09-operations.cjs

@@ -34,8 +34,8 @@ function checkErrorHandlingPatterns(consumingAppPath) {
       return;
     }
     
-    // Skip test files
-    if (filePath.includes('.test.') || filePath.includes('.spec.')) {
+    // Skip test files and test-utils
+    if (filePath.includes('.test.') || filePath.includes('.spec.') || filePath.includes('test-utils')) {
       return;
     }
     
@@ -72,6 +72,7 @@ function checkErrorHandlingPatterns(consumingAppPath) {
             code: getCodeSnippet(content, functionIndex),
             severity: 'info',
             fix: 'Use ApiResult<T> type: type ApiResult<T> = { ok: true; data: T } | { ok: false; error: ApiError }',
+            standardSection: 'Error Handling Patterns / Result Types (API Errors)',
           });
         }
       }
@@ -98,6 +99,7 @@ function checkCICDConfig(consumingAppPath) {
       message: 'CI/CD workflows directory not found. Consider setting up GitHub Actions for automated testing and deployment.',
       severity: 'info',
       fix: 'Create .github/workflows/ directory and add CI/CD workflow files',
+      standardSection: 'CI/CD Integration (Required CI Checks)',
     });
     return issues;
   }
@@ -115,6 +117,7 @@ function checkCICDConfig(consumingAppPath) {
       message: 'No CI/CD workflow files found. Consider setting up automated testing and deployment.',
       severity: 'info',
       fix: 'Create workflow files in .github/workflows/ (e.g., ci.yml, deploy.yml)',
+      standardSection: 'CI/CD Integration (Required CI Checks)',
     });
   }
   
@@ -172,6 +175,7 @@ function checkErrorBoundaries(consumingAppPath) {
       message: 'ErrorBoundary component exists but is not used in main.tsx or App.tsx. Should wrap the app root to catch React errors.',
       severity: 'warning',
       fix: 'Wrap app root with ErrorBoundary in main.tsx or App.tsx',
+      standardSection: 'Error Handling Patterns (Pattern 3: Error Boundaries)',
     });
   }
   
@@ -181,15 +185,23 @@ function checkErrorBoundaries(consumingAppPath) {
 /**
  * Run audit for Standard 9: Operations
  * @param {string} consumingAppPath - Path to consuming app
+ * @param {{ isPaceCorePackage?: boolean }} [auditContext] - When isPaceCorePackage, skip CICD/errorBoundary and ApiResult noise (package has no main/App)
  * @returns {object} - Audit results with issues array
  */
-function runStandard9Audit(consumingAppPath) {
+function runStandard9Audit(consumingAppPath, auditContext = {}) {
   const issues = [];
-  
+  const isPaceCorePackage = auditContext.isPaceCorePackage === true;
+
   try {
-    issues.push(...checkErrorHandlingPatterns(consumingAppPath));
-    issues.push(...checkCICDConfig(consumingAppPath));
-    issues.push(...checkErrorBoundaries(consumingAppPath));
+    if (!isPaceCorePackage) {
+      issues.push(...checkErrorHandlingPatterns(consumingAppPath));
+    }
+    if (!isPaceCorePackage) {
+      issues.push(...checkCICDConfig(consumingAppPath));
+    }
+    if (!isPaceCorePackage) {
+      issues.push(...checkErrorBoundaries(consumingAppPath));
+    }
   } catch (error) {
     return {
       standard: '09-operations',

package/audit-tool/index.cjs

@@ -16,9 +16,13 @@
  * 
  * Usage:
  *   node packages/core/audit-tool/index.cjs [path-to-consuming-app] [--output report.md]
- *   npm run audit:pace-core [path-to-consuming-app] [--output report.md]
- * 
+ *   npm run validate (runs this tool as the pace-core Audit step)
+ *
  * If no path provided, assumes current directory is consuming app.
+ *
+ * Note: This tool does not scan supabase/migrations. RLS policy and RPC naming
+ * compliance are audited by a separate DB audit tool (to be implemented) that
+ * connects to the database directly.
  */
 
 const fs = require('fs');
@@ -54,8 +58,11 @@ const colors = {
 
 /**
  * Run all standard audits
+ * @param {string} consumingAppPath - Path to the app/package being audited
+ * @param {boolean} showProgress - Whether to log progress
+ * @param {{ consumingAppPath: string, isPaceCorePackage: boolean }} [auditContext] - Optional context (isPaceCorePackage skips app-only checks)
  */
-function runAllAudits(consumingAppPath, showProgress = false) {
+function runAllAudits(consumingAppPath, showProgress = false, auditContext = {}) {
   const results = {};
   
   const standardNames = {
@@ -88,7 +95,7 @@ function runAllAudits(consumingAppPath, showProgress = false) {
     }
     
     try {
-      const result = fn(consumingAppPath);
+      const result = fn(consumingAppPath, auditContext);
       results[key] = result;
       
       if (result.error && showProgress) {
@@ -116,20 +123,22 @@ function main() {
   const args = process.argv.slice(2);
   const outputArg = args.find(arg => arg.startsWith('--output'));
   const outputPath = outputArg ? (outputArg.includes('=') ? outputArg.split('=')[1] : args[args.indexOf(outputArg) + 1] || 'audit-report.md') : null;
-  const consumingAppPath = args.find(arg => !arg.startsWith('--') && arg !== outputPath) || process.cwd();
+  const consumingAppPath = path.resolve(args.find(arg => !arg.startsWith('--') && arg !== outputPath) || process.cwd());
   
   console.log(`${colors.bold}${colors.cyan}pace-core Comprehensive Audit${colors.reset}\n`);
   console.log(`${colors.cyan}${'='.repeat(50)}${colors.reset}\n`);
   
-  // Get project info from package.json
+  // Get project info and detect if we're auditing the pace-core package itself
   const packageJsonPath = path.join(consumingAppPath, 'package.json');
   let projectName = 'unknown';
   let paceCoreVersion = 'unknown';
+  let isPaceCorePackage = false;
   
   if (fs.existsSync(packageJsonPath)) {
     try {
       const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
       projectName = packageJson.name || 'unknown';
+      isPaceCorePackage = projectName === '@jmruthers/pace-core';
       
       // Find pace-core version
       const allDeps = {
@@ -142,15 +151,17 @@ function main() {
     }
   }
   
+  const auditContext = { consumingAppPath, isPaceCorePackage };
+  
   console.log(`Project: ${colors.bold}${projectName}${colors.reset}`);
   console.log(`pace-core: ${colors.bold}${paceCoreVersion}${colors.reset}\n`);
   
   // Run dependency audit
   console.log(`${colors.blue}Running dependency audit...${colors.reset}`);
-  const dependencyResult = runDependencyAudit(consumingAppPath);
+  const dependencyResult = runDependencyAudit(consumingAppPath, auditContext);
   
   // Run all standard audits
-  const standardResults = runAllAudits(consumingAppPath, true);
+  const standardResults = runAllAudits(consumingAppPath, true, auditContext);
   
   // Combine results
   const allResults = {
@@ -231,12 +242,12 @@ function main() {
   const minutes = String(now.getMinutes()).padStart(2, '0');
   const timestamp = `${year}${month}${day}${hours}${minutes}`;
   
-  // Helper function to add timestamp to filename
+  // Helper function to add timestamp at start of filename
   function addTimestampToFilename(filePath) {
     const dir = path.dirname(filePath);
     const ext = path.extname(filePath);
     const name = path.basename(filePath, ext);
-    return path.join(dir, `${name}-${timestamp}${ext}`);
+    return path.join(dir, `${timestamp}-${name}${ext}`);
   }
   
   // Determine report path
@@ -249,7 +260,7 @@ function main() {
     if (!fs.existsSync(auditDir)) {
       fs.mkdirSync(auditDir, { recursive: true });
     }
-    reportPath = path.join(auditDir, `pace-core-audit-${timestamp}.md`);
+      reportPath = path.join(auditDir, `${timestamp}-pace-core-audit.md`);
   }
   
   // Save report

package/audit-tool/utils/report-utils.cjs

@@ -42,6 +42,10 @@ function formatIssue(issue, standard) {
     formatted += `**Details:** ${issue.details}\n\n`;
   }
   
+  if (issue.standardSection) {
+    formatted += `**See standard:** ${issue.standardSection}\n\n`;
+  }
+  
   return formatted;
 }
 

package/cursor-rules/01-pace-core-compliance.mdc

@@ -21,6 +21,7 @@ This guide ensures consuming apps use pace-core components, hooks, and utilities
 5. **Read documentation** - Before using any pace-core component, check its documentation for required props and usage patterns
 6. **Follow provider nesting** - Always nest providers in the correct order (QueryClientProvider → BrowserRouter → UnifiedAuthProvider → OrganisationProvider)
 7. **Configure Vite correctly** - Always exclude `@jmruthers/pace-core` and `react-router-dom` from pre-bundling
+8. **When fixing compliance issues** - Use the **audit report** (`audit/<timestamp>-pace-core-audit.md`) and the **standard doc** section linked from the report; fix the cause, do not silence tools. Re-run **`npm run validate`** to confirm (type-check, lint, build, tests, pace-core audit).
 
 **Decision Tree: Should I create this or use pace-core?**
 ```

package/cursor-rules/02-project-structure.mdc

@@ -14,12 +14,13 @@ This guide defines the standard folder structure and file organization for consu
 ## AI Agent Instructions
 
 **When creating or organizing files, ALWAYS:**
-1. **Organize by feature** - Group components, hooks, and utilities by feature/domain, not by type
+1. **Organize by feature** - Group components, hooks, and utilities by feature, not by type
 2. **Colocate tests** - Place test files next to source files (`Component.test.tsx` next to `Component.tsx`)
 3. **Follow naming conventions** - Components: `PascalCase.tsx`, Hooks: `use*.ts`, Utils: `camelCase.ts`
 4. **Use absolute imports** - Use `@/` path alias for imports, never relative imports for distant files
 5. **Keep root clean** - Only configuration files and documentation in root, never source files
 6. **Place migrations correctly** - All migrations in `supabase/migrations/` with timestamp format
+7. **When fixing project structure issues** - Use the **audit report** (`audit/<timestamp>-pace-core-audit.md`) and the **standard doc** section linked from the report; fix the cause, do not silence tools. Re-run **`npm run validate`** to confirm.
 
 **Decision Tree: File Organization**
 ```
@@ -74,7 +75,7 @@ your-app/
 
 ## MUST: Organize Components by Feature
 
-**ALWAYS organize components by feature/domain, not by type:**
+**ALWAYS organize components by feature, not by type:**
 
 ```
 src/
@@ -136,30 +137,6 @@ src/
   - where migrations/RLS policies are managed
   - whether the app is expected to add migrations in the future
 
-## SHOULD: Organize by Domain
-
-**For larger apps, SHOULD organize by domain/feature:**
-
-```
-src/
-├── domains/
-│   ├── events/
-│   │   ├── components/
-│   │   ├── hooks/
-│   │   ├── services/
-│   │   └── types.ts
-│   └── users/
-│       ├── components/
-│       ├── hooks/
-│       ├── services/
-│       └── types.ts
-├── shared/              # Shared across domains
-│   ├── components/
-│   ├── hooks/
-│   └── utils/
-└── App.tsx
-```
-
 ## MUST: Keep Root Directory Clean
 
 **Root directory SHOULD only contain:**

package/cursor-rules/03-architecture.mdc

@@ -20,6 +20,8 @@ This guide enforces SOLID architecture principles, component design patterns, an
 4. **Use focused interfaces** - Create small, specific interfaces instead of large, generic ones
 5. **Depend on abstractions** - Use interfaces/types, not concrete implementations
 6. **Follow ApiResult pattern** - All RPCs must return ApiResult shape with proper error handling
+7. **When fixing architecture issues** - Use the **audit report** (`audit/<timestamp>-pace-core-audit.md`) and the **standard doc** section linked from the report; fix the cause, do not silence tools. Re-run **`npm run validate`** to confirm.
+8. **When the audit reports componentBoundary** - Fix the cause (e.g. extract data fetching to a hook, move business logic to a hook or utility, split large files or interfaces per SRP/ISP); do not silence or work around the finding. See Standard 3 "Component Design Principles / SOLID" and "How we check SOLID."
 
 **Decision Tree: Where should this logic live?**
 ```
@@ -244,7 +246,7 @@ Before committing code, verify:
      const [user, setUser] = useState(null);
      const [events, setEvents] = useState([]);
      const [organisations, setOrganisations] = useState([]);
-     // 200+ lines of logic...
+     // 400+ lines of logic...
    }
    
    // ✅ CORRECT: Separated concerns

package/cursor-rules/04-code-quality.mdc

@@ -21,6 +21,7 @@ This guide enforces code quality standards to ensure maintainable, performant, a
 5. **Use semantic HTML** - Use semantic elements (`<main>`, `<section>`, `<article>`, etc.) instead of `<div>` wrappers
 6. **Memoize appropriately** - Use `useMemo` and `useCallback` for expensive computations and stable references
 7. **Early returns** - Use early returns to reduce nesting and improve readability
+8. **When fixing code quality issues** - Use the **audit report** (`audit/<timestamp>-pace-core-audit.md`) and the **standard doc** section linked from the report; fix the cause, do not silence tools. Re-run **`npm run validate`** to confirm.
 
 **Decision Tree: Type Safety**
 ```

package/cursor-rules/05-styling.mdc

@@ -20,6 +20,7 @@ rulesVersion: "2025-01-28"
 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)
+7. **When fixing styling or markup issues** - Use the **audit report** (`audit/<timestamp>-pace-core-audit.md`) and the **standard doc** section linked from the report; fix the cause (e.g. app.css, @source, @theme), do not silence tools. Re-run **`npm run validate`** to confirm.
 
 **Decision Tree: Markup & Styling**
 ```
@@ -62,6 +63,39 @@ rulesVersion: "2025-01-28"
 
 ---
 
+## Color Palettes: main, sec, acc Only
+
+**pace-core and all pace apps MUST use only the custom design-system palettes (`main`, `sec`, `acc`). NEVER use standard Tailwind/named colors (e.g. red, blue, gray, green, orange, etc.) in class names, CSS variables, or documentation examples.**
+
+Do not define or reference CSS variables like `--color-red-500`, `--color-blue-200`, `--color-gray-500`; use `--color-main-*`, `--color-sec-*`, `--color-acc-*` only.
+
+### Color mapping (standard Tailwind to design system)
+
+When converting or writing styles, use this mapping:
+
+| Standard / Tailwind | Use palette |
+|--------------------|-------------|
+| red, orange, amber, yellow, lime, pink, rose | **acc-** |
+| green, emerald, teal, cyan, sky, blue | **main-** |
+| indigo, violet, purple, fuchsia, slate, gray, zinc, neutral, stone | **sec-** |
+| white | **main-50** |
+| black | **main-950** |
+
+### Transformation rules
+
+- Replace `bg-{standard}-{shade}` with `bg-{palette}-{shade}` (e.g. `bg-main-500`, `bg-sec-200`, `bg-acc-400`).
+- Same for `text-*`, `border-*`, `ring-*`, `outline-*`, `from-*` / `via-*` / `to-*` (gradients), `fill-*`, `stroke-*`.
+- Preserve shade numbers (50, 100, …, 950).
+- Do not change semantic Tailwind classes (e.g. `bg-background`, `text-foreground`) that are mapped in app CSS.
+- Do not create or reference new CSS variables; use existing theme tokens only.
+
+### Examples
+
+- `bg-main-500`, `text-acc-100`, `border-sec-700`, `ring-acc-400` are correct.
+- Any class using standard Tailwind color names is wrong; use the mapped palette (main/sec/acc) instead.
+
+---
+
 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
@@ -94,18 +128,27 @@ import { Button, Input } from '@jmruthers/pace-core';
 
 ### MUST NOT: Add Custom Styles to pace-core Components
 
-**NEVER add custom styles when pace-core components already provide styling. Use component variants/props instead.**
+**NEVER add custom styles when pace-core components already provide styling. Assume these components already apply the correct layout, structure, and color styles. Use component variants/props instead.**
 
 ```tsx
 // ❌ WRONG: Overriding pace-core component styles
 <Button className="custom-button-style">Click me</Button>
 <Card className="custom-card-layout">Content</Card>
+<Button className="text-acc-500 bg-main-200">Custom styled button</Button>
+<Input className="border-2 border-sec-500" />
 
 // ✅ CORRECT: Use pace-core component variants/props
 <Button variant="default">Click me</Button>
 <Card>Content</Card>
+<Button variant="destructive">Delete</Button>
+<Input type="text" />
 ```
 
+**Exceptions:**
+- Only override styles when absolutely necessary and document why
+- Prefer using component props/variants over className overrides
+- If you must override, do it inside the component file, not at the call site
+
 ### MUST: Rely on pace-core core.css
 
 **MUST rely on pace-core `core.css` for typography, spacing, and visual presentation:**
@@ -113,7 +156,7 @@ import { Button, Input } from '@jmruthers/pace-core';
 ```tsx
 // ❌ WRONG: Custom typography classes
 <h1 className="text-2xl font-bold">Title</h1>
-<p className="text-gray-500 mb-4">Description</p>
+<p className="text-sec-500 mb-4">Description</p>
 
 // ✅ CORRECT: Typography defined in pace-core core.css
 <h1>Title</h1>
@@ -156,7 +199,10 @@ import { Button, Input } from '@jmruthers/pace-core';
 
 ### MUST: Prefer Semantic HTML (Limit `<div>`)
 
-**ALWAYS prefer semantic HTML elements** (`<main>`, `<section>`, `<article>`, `<header>`, `<footer>`, `<nav>`, lists, etc.).
+**ALWAYS prefer semantic HTML elements** (`<main>`, `<section>`, `<article>`, `<header>`, `<footer>`, `<nav>`, `<h1>`, `<h2>`, `<h3>`, `<h4>`, `<h5>`, `<h6>`, `<p>`, `<ul>`, `<ol>`, `<li>`, `<a>`, `<strong>`, `<em>`, `<u>`, `<pre>`, `<code>`, `<blockquote>`, `<hr>`, `<small>`, etc.) instead of styling-focused `<div>` or `<span>` wrappers.
+
+**Note:** `<img>` elements can remain as-is; do not convert to `<figure>` elements. These semantic elements already have their styling defined in `core.css`.
+
 Using semantic elements improves accessibility, maintainability, and consistency.
 
 #### `<div>` usage policy
@@ -169,7 +215,7 @@ Using semantic elements improves accessibility, maintainability, and consistency
 
 #### 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>`).
+- **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>`, headings that should be `<h1>`-`<h6>`, paragraphs that should be `<p>`).
 - **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.
 
@@ -180,12 +226,25 @@ Using semantic elements improves accessibility, maintainability, and consistency
 <div className="page">
   <div className="nav">...</div>
   <div className="content">...</div>
+  <div className="heading">Title</div>
+  <div className="text">Paragraph text</div>
+  <div className="list">
+    <div className="item">Item 1</div>
+    <div className="item">Item 2</div>
+  </div>
 </div>
 
 // ✅ CORRECT: Semantic structure
 <main>
   <nav>...</nav>
-  <section>...</section>
+  <section>
+    <h1>Title</h1>
+    <p>Paragraph text</p>
+    <ul>
+      <li>Item 1</li>
+      <li>Item 2</li>
+    </ul>
+  </section>
 </main>
 
 // ✅ ACCEPTABLE: Layout-only wrapper (no semantic fit)
@@ -199,18 +258,31 @@ Using semantic elements improves accessibility, maintainability, and consistency
 
 ### MUST NOT: Apply Typography Styles Directly
 
-**MUST NOT apply typography styles directly to elements:**
+**MUST NOT apply typography styles directly to elements. All typography for semantic elements (`body`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `p`, `a`, `strong`, `em`, `u`, `pre`, `code`, `blockquote`, `hr`, `small`, `ul`, `ol`, `li`) is defined in `pace-core core.css`.**
+
+**Prohibited typography classes:**
+- `text-*` (e.g., `text-2xl`, `text-sm`, `text-base`)
+- `font-*` (e.g., `font-bold`, `font-semibold`, `font-normal`)
+- `leading-*` (e.g., `leading-relaxed`, `leading-tight`)
+- `tracking-*` (e.g., `tracking-wide`, `tracking-tighter`)
+- `uppercase`, `lowercase`, `capitalize`
+- Color classes on typography elements (use core.css; for layout color use main/sec/acc only, e.g. `text-main-600`)
+- Margin/padding classes used solely for text spacing (e.g., `mb-2`, `mt-4`, `pb-1`, `pt-3`) — unless clearly needed for layout structure
 
 ```tsx
 // ❌ WRONG: Direct typography styling
 <h1 className="text-2xl font-bold">Title</h1>
-<p className="text-gray-500 leading-relaxed">Description</p>
+<p className="text-sec-500 leading-relaxed mb-4">Description</p>
 <label className="text-sm uppercase">Label</label>
+<a className="text-main-500">Link</a>
+<ul className="mb-4">List</ul>
 
 // ✅ CORRECT: Typography defined in pace-core core.css
 <h1>Title</h1>
 <p>Description</p>
 <label>Label</label>
+<a>Link</a>
+<ul>List</ul>
 ```
 
 ### MUST: Use pace-core Typography
@@ -222,7 +294,21 @@ Using semantic elements improves accessibility, maintainability, and consistency
 <h1>Heading 1</h1>
 <h2>Heading 2</h2>
 <h3>Heading 3</h3>
+<h4>Heading 4</h4>
+<h5>Heading 5</h5>
+<h6>Heading 6</h6>
 <p>Paragraph text</p>
+<a>Link text</a>
+<strong>Bold text</strong>
+<em>Italic text</em>
+<u>Underlined text</u>
+<pre>Preformatted text</pre>
+<code>Code text</code>
+<blockquote>Quote text</blockquote>
+<hr />
+<small>Small text</small>
+<ul><li>List item</li></ul>
+<ol><li>Ordered item</li></ol>
 <label>Form label</label>
 ```
 
@@ -233,13 +319,39 @@ Using semantic elements improves accessibility, maintainability, and consistency
 ```tsx
 // ❌ WRONG: Typography utilities or inline styles
 <h1 className="text-3xl font-bold mb-4">Title</h1>
-<p style={{ fontSize: '14px', color: 'gray' }}>Text</p>
+<p style={{ fontSize: '14px', color: '...' }}>Text</p>
 <label className="uppercase tracking-wide">Label</label>
+<a className="text-primary hover:text-primary-600">Link</a>
+<ul className="mb-2 mt-4">List</ul>
 
 // ✅ CORRECT: No typography styling - pace-core handles it
 <h1>Title</h1>
 <p>Text</p>
 <label>Label</label>
+<a>Link</a>
+<ul>List</ul>
+```
+
+### MUST NOT: Use Margin/Padding for Text Spacing
+
+**MUST NOT use margin/padding classes (`mb-*`, `mt-*`, `pb-*`, `pt-*`, `mx-*`, `my-*`, `px-*`, `py-*`) solely for text spacing on typography elements. These are allowed only when clearly needed for layout structure:**
+
+```tsx
+// ❌ WRONG: Margin/padding for text spacing
+<p className="mb-4">Paragraph with bottom margin</p>
+<h2 className="mt-8 mb-2">Heading with margins</h2>
+<ul className="mb-4">List with bottom margin</ul>
+
+// ✅ CORRECT: No spacing classes - pace-core handles typography spacing
+<p>Paragraph</p>
+<h2>Heading</h2>
+<ul>List</ul>
+
+// ✅ ACCEPTABLE: Margin/padding for layout structure (not typography spacing)
+<section className="mb-8">
+  <h2>Section Title</h2>
+  <p>Content</p>
+</section>
 ```
 
 ## React Structure Rules

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

@@ -21,8 +21,10 @@ This guide enforces the **mandatory RBAC contract** and security patterns betwee
 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
+6. **Use helper functions in RLS** - Always use STABLE SECURITY DEFINER helper functions (when querying RLS-protected tables), never subqueries
+7. **Secure SECURITY DEFINER functions** - All SECURITY DEFINER functions must have `SET search_path TO public`, schema-qualified references, and documented rationale
+8. **Sanitize logs** - Never log passwords, tokens, or sensitive data
+9. **When fixing security or RBAC issues** - Use the **audit report** (`audit/<timestamp>-pace-core-audit.md`) and the **standard doc** section linked from the report; fix the cause (e.g. RLS policy, helper attributes, PagePermissionGuard, Edge Function setupRBAC), do not silence tools. Re-run **`npm run validate`** to confirm.
 
 **Decision Tree: Security & Permissions**
 ```
@@ -433,6 +435,9 @@ Before committing RBAC-related code, verify:
 - [ ] 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
+- [ ] All SECURITY DEFINER functions have `SET search_path TO public` (MANDATORY)
+- [ ] All SECURITY DEFINER functions schema-qualify table/function references
+- [ ] All SECURITY DEFINER functions document why SECURITY DEFINER is needed
 - [ ] ESLint rules pass without errors
 
 ## MUST: Include Super-Admin Checks in RLS Policies
@@ -509,6 +514,125 @@ END;
 $$;
 ```
 
+## MUST: Use SECURITY DEFINER Only When Necessary
+
+**SECURITY DEFINER is REQUIRED when helper functions query tables with RLS policies.** Without it, calling these functions from RLS policies creates circular dependencies.
+
+**Decision Tree:**
+```
+1. Does this helper function query tables with RLS policies?
+   ├─ YES → SECURITY DEFINER required (to avoid circular RLS)
+   │         └─ Continue to security requirements
+   └─ NO → Continue to step 2
+
+2. Does this function need elevated privileges?
+   ├─ YES → SECURITY DEFINER may be appropriate (document why)
+   │         └─ Continue to security requirements
+   └─ NO → SECURITY DEFINER not needed
+            └─ Use STABLE or IMMUTABLE only
+
+3. Security requirements (MANDATORY for SECURITY DEFINER):
+   ├─ SET search_path TO public ✅ MANDATORY
+   ├─ Schema-qualify all references ✅ MANDATORY
+   ├─ Use STABLE/IMMUTABLE when possible ✅ REQUIRED
+   ├─ Owned by appropriate role ✅ RECOMMENDED
+   └─ Document why in COMMENT ✅ REQUIRED
+```
+
+**✅ CORRECT: SECURITY DEFINER with all security requirements:**
+
+```sql
+-- ✅ CORRECT: SECURITY DEFINER required (queries RLS-protected table)
+CREATE OR REPLACE FUNCTION check_user_organisation_access(p_organisation_id UUID)
+RETURNS boolean
+LANGUAGE plpgsql
+STABLE                    -- ✅ Performance optimization
+SECURITY DEFINER          -- ✅ Required: queries rbac_organisation_roles (has RLS)
+SET search_path TO public -- ✅ MANDATORY: prevents search path hijacking
+AS $$
+BEGIN
+  -- ✅ Schema-qualified reference
+  RETURN EXISTS (
+    SELECT 1 FROM public.rbac_organisation_roles
+    WHERE user_id = auth.uid()
+    AND organisation_id = p_organisation_id
+  );
+END;
+$$;
+
+-- ✅ Document why SECURITY DEFINER is needed
+COMMENT ON FUNCTION check_user_organisation_access(UUID) IS 
+  'Checks if current user has access to organisation. SECURITY DEFINER required because function queries public.rbac_organisation_roles which has RLS policies. Without SECURITY DEFINER, this would create circular RLS dependency. STABLE for RLS policy performance. SET search_path TO public prevents search path hijacking.';
+```
+
+**✅ CORRECT: No SECURITY DEFINER needed (pure computation):**
+
+```sql
+-- ✅ CORRECT: No SECURITY DEFINER needed (no RLS-protected queries)
+CREATE OR REPLACE FUNCTION calculate_total(p_amount NUMERIC, p_tax_rate NUMERIC)
+RETURNS NUMERIC
+LANGUAGE plpgsql
+STABLE  -- ✅ STABLE for performance, but no SECURITY DEFINER needed
+AS $$
+BEGIN
+  RETURN p_amount * (1 + p_tax_rate);  -- Pure computation, no table queries
+END;
+$$;
+```
+
+**MUST NOT:**
+- Use SECURITY DEFINER without `SET search_path TO public` (security risk)
+- Use unqualified table/function references in SECURITY DEFINER functions (security risk)
+- Use SECURITY DEFINER for functions that don't query RLS-protected tables (unnecessary)
+- Create SECURITY DEFINER functions without documenting why (maintenance risk)
+
+```sql
+-- ❌ FORBIDDEN: Missing SET search_path (security risk)
+CREATE OR REPLACE FUNCTION bad_function()
+RETURNS boolean
+LANGUAGE plpgsql
+STABLE
+SECURITY DEFINER  -- Missing SET search_path TO public!
+AS $$
+BEGIN
+  RETURN EXISTS (SELECT 1 FROM rbac_organisation_roles);
+END;
+$$;
+
+-- ❌ FORBIDDEN: Unqualified reference (security risk)
+CREATE OR REPLACE FUNCTION bad_function()
+RETURNS boolean
+LANGUAGE plpgsql
+STABLE
+SECURITY DEFINER
+SET search_path TO public
+AS $$
+BEGIN
+  RETURN EXISTS (SELECT 1 FROM rbac_organisation_roles);  -- Should be public.rbac_organisation_roles
+END;
+$$;
+
+-- ❌ FORBIDDEN: SECURITY DEFINER without justification
+CREATE OR REPLACE FUNCTION pure_computation(x NUMERIC)
+RETURNS NUMERIC
+LANGUAGE plpgsql
+STABLE
+SECURITY DEFINER  -- Not needed! Function doesn't query RLS-protected tables
+AS $$
+BEGIN
+  RETURN x * 2;  -- Pure computation, no table queries
+END;
+$$;
+```
+
+**Security Checklist for SECURITY DEFINER Functions:**
+- [ ] `SET search_path TO public` is present (MANDATORY)
+- [ ] All table/function references are schema-qualified (e.g., `public.table_name`)
+- [ ] Function is marked `STABLE` or `IMMUTABLE` when possible
+- [ ] Function ownership uses least-privilege role (not superuser unless necessary)
+- [ ] COMMENT documents why SECURITY DEFINER is needed
+- [ ] Function actually queries RLS-protected tables (justification for SECURITY DEFINER)
+
 ## Reference
 
 - **RBAC Contract**: `packages/core/docs/rbac/RBAC_CONTRACT.md` - Complete contract documentation

package/cursor-rules/07-api-tech-stack.mdc

@@ -21,6 +21,7 @@ This guide ensures consuming apps use the correct versions and patterns for all
 5. **Return ApiResult** - All RPCs must return ApiResult shape with proper error handling
 6. **Use TanStack Query** - Always use TanStack Query for server state, never `useState + useEffect`
 7. **Use React Hook Form + Zod** - Always use `useZodForm` from pace-core for forms
+8. **When fixing API or tech stack issues** - Use the **audit report** (`audit/<timestamp>-pace-core-audit.md`) and the **standard doc** section linked from the report; fix the cause (e.g. RPC naming, package versions, Vite config), do not silence tools. Re-run **`npm run validate`** to confirm.
 
 **Decision Tree: RPC Naming**
 ```