azcodr 1.2.2 → 1.4.0

package/docs/rules/frontend_architecture.md

@@ -0,0 +1,157 @@
+# Frontend Architecture & Client State Management
+
+> **Core Mandate:** Enforce production-grade client architecture: accessible headless component primitives, WCAG 2.2 Level AA compliance, asynchronous server-state cache synchronization and deduplication, declarative contract schema form validation, bidirectional URL navigation synchronization, explicit 5-tier state separation, and symmetrical design tokens.
+
+---
+
+## 1. The YAGNI Gate: Semantic Markup & Headless Primitives vs. Premature Sprawl
+
+Frontend engineering is frequently derailed by two opposing anti-patterns: **reinventing the wheel** (hand-rolling custom dialogs and bespoke CSS architectures) or **premature framework sprawl** (installing heavy global state machines for simple data flows).
+
+```mermaid
+flowchart TD
+    subgraph Gate ["Frontend Architecture YAGNI Gate"]
+        B1["1. SIMPLE BASELINE (Day 1)"]
+        B1_D["• Semantic HTML/markup styled with utility classes.<br/>• Battle-tested accessible headless primitives (Radix, Melt, Kobalte, PrimeVue).<br/>• Zero bespoke CSS architectures, unstyled div modals, or Redux."]
+        
+        B2["2. ANTI-TRIGGERS (Strictly Forbidden)"]
+        B2_D["• Headless backends, REST/gRPC microservices, or cloud workers.<br/>• Terminal CLI utilities, embedded libraries, or game engines.<br/>• Monolithic global state stores (Redux, MobX, Pinia) before separating server cache."]
+        
+        B3["3. THE TIPPING POINT (Graduation Threshold)"]
+        B3_D["• Dynamic client interfaces with asynchronous server data fetching.<br/>• Multi-step declarative form submissions and complex workflows.<br/>• Strict WCAG 2.2 AA accessibility, focus trapping, and keyboard navigation."]
+        
+        B1 --- B1_D
+        B2 --- B2_D
+        B3 --- B3_D
+    end
+```
+
+---
+
+## 2. The Asymmetry Law: Outside-In Discovery vs. Inside-Out Execution
+
+A fundamental architectural question is: **Does the User Interface dictate Business Logic, or does Business Logic dictate the UI?**
+
+The answer is governed by the **Outside-In Discovery vs. Inside-Out Execution Asymmetry**:
+
+```mermaid
+flowchart LR
+    subgraph Discovery ["Outside-In Discovery (Phase 1 & 2)"]
+        UI["User Interface & Interaction Model<br/>(Web GUI, Mobile, or Terminal CLI)"]
+        UC["Inbound Driving Port<br/>(Use Case / Command DTO)"]
+        UI -->|"Discovers Required Capabilities"| UC
+    end
+
+    subgraph Execution ["Inside-Out Execution (Phase 3 & 4)"]
+        DM["Domain Core & Invariants<br/>(100% UI-Agnostic Rules & State Machines)"]
+        AD["Outbound Driven Adapters<br/>(Database, Email, External Services)"]
+        UC -->|"Executes Isolated Logic"| DM
+        DM -->|"Persists / Notifies"| AD
+    end
+```
+
+### 1. Outside-In Discovery (Why Interaction Must Be Refined Early)
+- The user's operational mental model, workflow steps, and interaction touchpoints (whether Web forms, CLI flags, or API endpoints) **guide the discovery of system capabilities**.
+- If business logic is authored in a vacuum without interaction analysis, engineers build speculative methods and database models that do not align with user journeys (**The Anemic Core Antipattern**).
+- *Mandate:* In Phase 1 (Requirements) and Phase 2 (Domain Analysis), interaction models and wireframe workflows must be refined early via [`product-analyst`](../../.agents/skills/product-analyst/SKILL.md) and [`ui_ux_architecture.md`](./ui_ux_architecture.md).
+
+### 2. Inside-Out Execution (Why Domain Logic Remains Pure)
+- Once discovered, **business invariants are 100% decoupled from the UI**.
+- A business rule (e.g. *"An invoice cannot be paid twice"*, *"Discount cannot exceed 50%"*) must never live in a React `onClick` handler, a component hook, or a CLI flag parser (**The Smart UI Antipattern**).
+- The presentation layer merely parses user interaction into a plain **Command DTO** and calls an **Application Use Case** (Driving Port).
+- If the Web UI is replaced with a CLI or a background job, the core domain logic requires **zero modifications**.
+
+### 3. What If a Project Has No UI? (Headless Topologies)
+- For Headless Backends, Daemon Workers, and Embedded Systems:
+  - The **API Schema (OpenAPI / gRPC Protobuf) or Function Signature IS the UI**.
+  - For a CLI Utility, the **Command Pipeline (flags, stdin/stdout, exit codes)** IS the UI.
+  - The principle remains identical: the external interface defines the boundary contract, while the internal engine enforces pure invariants.
+
+---
+
+## 3. Component Primitives, Headless Accessibility & WCAG 2.2 Standards
+
+- **Accessible Headless Primitives**: All interactive UI components (dialogs, dropdowns, selects, tabs, tooltips, popovers) must decouple behavioral accessibility (focus trapping, keyboard navigation, ARIA states) from visual presentation using headless primitives:
+  - *React:* `@radix-ui` / `shadcn/ui` in `@/components/ui/`
+  - *Vue:* `radix-vue` / `shadcn-vue` or `primevue`
+  - *Svelte:* `melt-ui` / `bits-ui`
+  - *Solid:* `@kobalte/core`
+  - *Angular:* `@angular/cdk/a11y`
+- **Zero Unstyled Raw Elements**: Never create unstyled raw HTML modals, dropdowns, or custom select tags using raw `<div>` tags and ad-hoc mouse-only click handlers.
+- **Focus Management & Trapping**:
+  - Modal dialogs must trap keyboard focus within the dialog container while open.
+  - Closing a dialog must return keyboard focus deterministically to the triggering element.
+- **Visible Focus Indicators**: Never remove default outline rings (`outline: none`) without providing an explicit, high-contrast replacement (`focus-visible:ring-2 focus-visible:ring-offset-2`).
+- **Dynamic Content & ARIA Live Regions**:
+  - Asynchronous notifications, toast alerts, and status updates must use `role="status"` or `aria-live="polite"` so screen readers announce changes without interrupting the user.
+  - Critical error alerts must use `role="alert"` or `aria-live="assertive"`.
+- **Strict Prohibition of Native Dialogs**: Browser-native `window.alert()` and `window.confirm()` are strictly forbidden. Use accessible headless dialogs (`<ConfirmDialog />`).
+- **Utility Styling & Class Merging (`cn` helper)**: Combine utility classes using deterministic class merging (e.g., `clsx` and `tailwind-merge` via `cn(...)`) to allow clean prop overrides and consistent theming.
+
+---
+
+## 4. Server-State Cache Synchronization & Invalidation
+
+- **Decoupling Remote Cache from Local State**: Server state (owned remotely, asynchronous, shared across clients) must never be treated as local synchronous client state.
+- **Mandatory Cache Synchronization Engine**: Asynchronous data fetching, caching, deduplication, and background revalidation must use a dedicated cache synchronization manager (e.g., TanStack Query, SWR, or RTK Query in React; Pinia Colada or VueUse `useFetch` in Vue; Superforms or SvelteKit load functions in Svelte; Angular Signals with HttpClient).
+- **Elimination of Raw Lifecycle Fetch Loops**:
+  - *Anti-Pattern:* Uncoordinated manual fetching in component lifecycles (`useEffect(() => { fetch().then(...) })`, `onMounted`, `ngOnInit`) with hand-rolled `isLoading` and `error` boolean states.
+  - *Standard Pattern (Query Hook / Cache Invalidation):*
+    ```tsx
+    const { data: resources, isLoading, error } = useQuery({
+      queryKey: ['resources', tenantId],
+      queryFn: () => api.getResources(tenantId),
+    });
+    ```
+- **Declarative Mutations & Cache Invalidation**:
+  - Mutations must declare side-effects that explicitly invalidate affected cache keys rather than imperatively splicing local component state arrays:
+    ```tsx
+    const queryClient = useQueryClient();
+    const createResourceMutation = useMutation({
+      mutationFn: (newResource: CreateResourceInput) => api.createResource(newResource),
+      onSuccess: () => {
+        queryClient.invalidateQueries({ queryKey: ['resources'] });
+      },
+    });
+    ```
+- **Hierarchical Query Keys**: Format query keys hierarchically as structured tuples: `['entity', id, ...filters]`, e.g., `['orders', orderId]`, `['users', tenantId]`.
+
+---
+
+## 5. Form State Management & Fail-Fast Schema Validation
+
+- **Mandatory Schema Validation**: Every form submission must be validated against a formal declarative schema (Zod, Valibot, standard-schema, or framework validator) that mirrors shared DTO/input contracts.
+- **Dedicated Form State Engines**: Use dedicated form engines (React Hook Form, TanStack Form, VeeValidate, Superforms, Angular Reactive Forms) that track field dirty states, touched states, and asynchronous validation without triggering full component tree re-renders.
+- **Zero Unvalidated Multi-Field Objects**:
+  - *Anti-Pattern:* Unvalidated ad-hoc dictionary state (`useState({ name: '', email: '' })`) with manual string checking in submit handlers.
+  - *Standard Pattern:*
+    ```tsx
+    const form = useForm<CreateUserInput>({
+      resolver: zodResolver(createUserSchema),
+      defaultValues: { name: '', email: '' },
+    });
+    ```
+- **Accessible Error Linking**: Form inputs must bind validation errors to `aria-invalid="true"` and `aria-describedby="<field>-error"`. Every input must have an associated semantic `<label>`.
+
+---
+
+## 6. The 5-Tier State Hierarchy & Bidirectional URL Navigation
+
+Never dump all application state into a single global state container. Enforce strict categorical separation across 5 distinct lifecycles:
+
+1. **Server State (Remote Cache)**: Managed exclusively by the query cache engine; invalidated by resource keys.
+2. **URL State (Navigation / Search / Pagination / Filters)**:
+   - Must synchronize bidirectionally with URL search parameters (`useSearchParams`) to ensure deep linkability, bookmarkability, and seamless browser history (back/forward) navigation.
+   - Standard format: `?tab=security&page=2&limit=25&sort=createdAt&order=desc&status=ACTIVE`.
+   - Modals and drawers representing actionable entities must synchronize with the URL (e.g. `?modal=edit-user&userId=123`).
+3. **Form State (Transient Edits)**: Managed by form validation engines; discarded after submission or reset.
+4. **Local Component State (Ephemeral UI)**: Managed by primitive local component state (`useState`, `ref`, `$state`) strictly for local UI toggles (dropdown open, accordion expanded, hover).
+5. **Global Application State (Session / Context)**: Managed by lightweight client stores (Zustand, Pinia, Context, Signals) strictly for cross-cutting session data (current user, tenant context, active feature flags).
+6. **Data Grids & Large Tables**: When building sortable, paginated, or virtualized tables, standardize on headless table engines (TanStack Table, AG Grid) with row virtualization for datasets exceeding 100 rows.
+
+---
+
+## 7. Theme Architecture & Symmetrical Design Tokens
+
+- **Symmetric Design Tokens**: Ensure foundational CSS variables (`--background`, `--foreground`, `--card`, `--border`, `--popover`) are symmetrically declared across `:root` and `.dark`. Omitted root tokens in `.dark` result in unstyled backgrounds and illegible text when switching themes.
+- **System Preference Detection & Reactive Synchronization**: `ThemeProvider` implementations must listen to `window.matchMedia('(prefers-color-scheme: dark)')` with dynamic event listeners so OS appearance toggles seamlessly propagate in real-time, and synchronize `document.documentElement.style.colorScheme = resolvedTheme` to ensure browser-native elements (scrollbars, input widgets) match the active theme.

package/docs/rules/multitenancy_architecture.md

@@ -0,0 +1,98 @@
+# Multi-Tenancy Architecture, Isolation & Extensibility
+
+> **Core Mandate:** Enforce tenant context resolution from trusted cryptographic tokens, strict data isolation across the 4 tenancy models, leak-proof PostgreSQL Row-Level Security (RLS), and YAGNI-gated tenant extensibility (dynamic JSON schemas and sandboxed pluggable logic).
+
+---
+
+## 1. The Multi-Tenancy YAGNI Gate: Single-Tenant vs. Shared SaaS
+
+Multi-tenancy introduces significant operational complexity: tenant routing, cross-tenant data leak risks, noisy neighbor resource starvation, and complex database migrations. **Never force multi-tenant abstractions onto applications that execute in single-tenant boundaries.**
+
+```mermaid
+flowchart TD
+    subgraph MultiTenancyGate["Multi-Tenancy YAGNI Gate"]
+        B1["1. Simple Baseline (Day 1)<br/>• Single-tenant application architecture<br/>• Standard database tables without tenant foreign keys<br/>• Zero RLS policies, tenant interceptors, or dynamic schemas"]
+        B2["2. Anti-Triggers (Forbidden)<br/>• Single-tenant on-premise deployments or dedicated instances<br/>• Internal employee enterprise tools, developer CLIs, or games<br/>• Early-stage prototypes validating core domain logic"]
+        B3["3. The Tipping Point (Graduation)<br/>• Multi-tenant B2B SaaS where independent organizations share infrastructure<br/>• Strict legal, SOC 2, and regulatory mandates prohibiting cross-tenant data leakage"]
+        B1 -->|Forbidden if single-tenant| B2
+        B1 -->|Triggered by B2B SaaS requirements| B3
+    end
+```
+
+---
+
+## 2. Tenant Context Resolution
+
+Tenant identity must be resolved at the edge/gateway from **cryptographically verified session context**, never from spoofable client input:
+
+```mermaid
+flowchart LR
+    Req["Incoming Request"] --> Auth["Auth Middleware<br/>Extract Verified tenantId from JWT"]
+    Auth --> Ctx["AsyncLocalStorage / Context"]
+    Ctx --> DB["Database Connection<br/>SET LOCAL app.current_tenant_id"]
+    Ctx --> Audit["Audit / Event Log<br/>Tagged with tenantId"]
+```
+
+### Invariants:
+1. **Never Trust Raw Query/Body Parameters**: Never accept `?tenantId=...` or `{ tenantId: "..." }` on public mutations without validating that the authenticated session owns that tenant.
+2. **Ambient Context Propagation**: Bind the resolved `tenantId` to an ambient request context (e.g. `AsyncLocalStorage` in Node, `ThreadLocal` in Java, `context.Context` in Go) to prevent passing tenant IDs manually through every service layer.
+
+---
+
+## 3. The 4 Universal Data Isolation Models
+
+Choose the isolation model matching your security classification and cost profile:
+
+| Model | Isolation Mechanism | Operational Trade-off | Compliance Target |
+|---|---|---|---|
+| **1. Pooled with RLS** | Shared DB, shared schema; tables partitioned by `tenant_id` + Postgres RLS. | Lowest infrastructure cost, highest engineering rigor required. | Standard B2B SaaS, SOC 2 Type II. |
+| **2. Silo Schema** | Shared DB, separate database schema per tenant (`tenant_acme.*`). | High isolation; complex schema migrations across hundreds of schemas. | Regulated SaaS, HIPAA, FinTech. |
+| **3. Silo Database** | Separate physical or logical database instance per tenant. | Highest cost and isolation; zero cross-tenant blast radius. | Enterprise Dedicated, PCI-DSS Level 1. |
+| **4. App-Level Interceptor** | Shared DB, ORM/query builder automatically appends `WHERE tenant_id = :id`. | Brittle; human error in ad-hoc raw SQL queries bypasses isolation. | Forbidden for high-security applications. |
+
+---
+
+## 4. PostgreSQL Row-Level Security (RLS) Invariants
+
+When using **Model 1 (Pooled with RLS)**, enforce data isolation at the database engine level so that even a buggy or malicious application query cannot access another tenant's rows:
+
+### 1. Dual-Lock Table Setup
+Every table containing tenant-scoped data must enable and force RLS:
+```sql
+ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
+ALTER TABLE orders FORCE ROW LEVEL SECURITY;
+```
+*(The `FORCE` clause ensures that table owners and superusers are also bound by the policy).*
+
+### 2. Session Context Binding
+The application connection pool must initialize the tenant session variable inside every transactional checkout:
+```sql
+-- Executed inside transaction before running queries
+SELECT set_config('app.current_tenant_id', :tenantId, true);
+```
+
+### 3. Declarative Tenant Isolation Policy
+```sql
+CREATE POLICY tenant_isolation_policy ON orders
+  AS RESTRICTIVE
+  FOR ALL
+  TO application_user
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant_id', true), '')::UUID)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant_id', true), '')::UUID);
+```
+
+---
+
+## 5. Advanced Tenant Extensibility (YAGNI Gated)
+
+### 5.1. Dynamic Schemas (Runtime Custom Fields)
+- **Tipping Point:** External enterprise tenants require self-service custom fields without engineering running relational DDL migrations.
+- **Hybrid Storage Pattern:** Core relational columns for shared invariants + `custom_attributes JSONB` validated against **JSON Schema Draft 2020-12** stored per tenant.
+- **Fail-Fast Schema Validation:** Custom field inputs must be validated against the tenant's compiled JSON schema before database persistence.
+
+### 5.2. Pluggable Tenant Logic (Sandboxed Scripting)
+- **Tipping Point:** Enterprise tenants require custom business logic (tax calculation, approval routing) executed at runtime.
+- **Zero Raw `eval()`**: Never execute tenant code via raw `eval()`, Python `exec()`, or NodeJS VM isolates.
+- **Safe Sandboxing**:
+  - *Simple Expressions:* Use **Common Expression Language (CEL)** (Google) for safe, deterministic boolean and mathematical evaluation.
+  - *Complex Logic:* Compile tenant extension plugins to **WebAssembly (Wasm)** executed via Wasmer or Wasmtime with strict CPU time and memory quotas.

package/docs/rules/product_ownership.md

@@ -41,20 +41,12 @@ The only vehicle through which a team delivers actual product value is a usable,
 
 The OKR framework connects overarching strategic vision to sprint execution and product backlog ordering.
 
-```
-Company Vision & Strategy
-       │
-       ▼
-Strategic OKRs (Annual / Quarterly)
-       │
-       ▼
-  Product Goal (Long-Term Commitment)
-       │
-       ▼
-Product Backlog (Emergent, Ordered PBIs)
-       │
-       ▼
-  Sprint Goal (Tactical Increment)
+```mermaid
+flowchart TD
+    V["Company Vision & Strategy"] --> OKR["Strategic OKRs (Annual / Quarterly)"]
+    OKR --> PG["Product Goal (Long-Term Commitment)"]
+    PG --> PB["Product Backlog (Emergent, Ordered PBIs)"]
+    PB --> SG["Sprint Goal (Tactical Increment)"]
 ```
 
 ### Anatomy of an OKR
@@ -111,19 +103,22 @@ A collaborative prioritization exercise where stakeholders are allocated a const
 
 Following Gunther Verheyen's backlog topology, the Product Backlog serves as an **emergent, living roadmap**:
 
-```
-▲ Finer Granularity (Top)
-│   [ PBI 1: Sprintable, vertically sliced, clear DoD & Gherkin ]
-│   [ PBI 2: High priority, well-understood, estimated ]
-│   [ PBI 3: Actionable, small, customer value clear ]
-│
-│ Medium Granularity (Middle)
-│   [ PBI 4: Candidate for next period, coarse slice ]
-│   [ PBI 5: Alternative approach under evaluation ]
-│
-▼ Coarser Granularity (Bottom)
-    [ PBI 6: Long-term idea, future capability ]
-    [ PBI 7: Raw thought, exploratory concept ]
+```mermaid
+flowchart TD
+    subgraph Top["Finer Granularity (Top of Backlog)"]
+        P1["PBI 1: Sprintable, vertically sliced, clear DoD & Gherkin"]
+        P2["PBI 2: High priority, well-understood, estimated"]
+        P3["PBI 3: Actionable, small, customer value clear"]
+    end
+    subgraph Middle["Medium Granularity (Middle)"]
+        P4["PBI 4: Candidate for next period, coarse slice"]
+        P5["PBI 5: Alternative approach under evaluation"]
+    end
+    subgraph Bottom["Coarser Granularity (Bottom)"]
+        P6["PBI 6: Long-term idea, future capability"]
+        P7["PBI 7: Raw thought, exploratory concept"]
+    end
+    Top --> Middle --> Bottom
 ```
 
 ### Rules of Progressive Elaboration

package/docs/rules/requirements_engineering.md

@@ -40,20 +40,22 @@ Ensure every user story satisfies Bill Wake's **INVEST** criteria:
 
 ### The Multi-Layer Cake Metaphor (Vertical Slicing)
 Think of a complete feature as a multi-layer cake:
-```
-┌──────────────────────────────────────┐
-│ Presentation / UI Layer              │
-├──────────────────────────────────────┤
-│ Business Logic & Application Use Case│
-├──────────────────────────────────────┤
-│ Domain Invariants & Entities         │
-├──────────────────────────────────────┤
-│ Persistence & Database Layer         │
-└──────────────────────────────────────┘
-                   ▲
-                   │
-           Vertical Cake Slice
-   (Customer gets a taste of every layer)
+```mermaid
+flowchart TD
+    subgraph Cake["The Multi-Layer Cake (Vertical Slicing)"]
+        direction TB
+        L1["Presentation / UI Layer"]
+        L2["Business Logic & Application Use Case"]
+        L3["Domain Invariants & Entities"]
+        L4["Persistence & Database Layer"]
+        L1 --- L2 --- L3 --- L4
+    end
+
+    Slice["Vertical Cake Slice<br/>(Customer gets a taste of every layer)"]
+    Slice --> L1
+    Slice --> L2
+    Slice --> L3
+    Slice --> L4
 ```
 - **Horizontal Slicing (Anti-Pattern):** Implementing only the database schema or only the UI mock. A full database table has zero observable value to the customer without presentation and logic layers.
 - **Vertical Slicing (Golden Standard):** Slicing thin through all layers (UI ➔ API ➔ Domain ➔ DB). Even a minimal vertical slice provides working functionality that can be deployed, tested, and validated empirically.

package/docs/rules/security_compliance.md

@@ -0,0 +1,53 @@
+# Application Security, Cryptography & Regulatory Compliance
+
+> **Core Mandate:** Enforce OWASP Top 10 security defenses, cryptographic rigor, token bucket rate limiting, SOC 2 Type II security controls, ISO/IEC 27001 standards, and GDPR data erasure rights.
+
+---
+
+## 1. OWASP Top 10 Application Security Defenses
+
+Production software must systematically eliminate OWASP Top 10 attack vectors:
+
+1. **Injection Defense (SQL / Command / LDAP)**:
+   - Always use parameterized queries and prepared statements. Never concatenate untrusted strings into database queries or shell command strings.
+2. **Cross-Site Scripting (XSS)**:
+   - Standardize on modern framework auto-escaping (React, Vue, Svelte). Strictly forbid `dangerouslySetInnerHTML` or `v-html` unless sanitized by a verified sanitizer (e.g. DOMPurify).
+3. **Server-Side Request Forgery (SSRF)**:
+   - When fetching URLs provided by users, validate hostnames against an explicit domain allowlist. Never make outbound requests to private RFC 1918 subnets (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) or cloud metadata endpoints (`169.254.169.254`).
+4. **Security Misconfiguration & Headers**:
+   - Enforce secure HTTP response headers:
+     ```http
+     Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
+     X-Content-Type-Options: nosniff
+     X-Frame-Options: DENY
+     Content-Security-Policy: default-src 'self'; script-src 'self';
+     ```
+
+---
+
+## 2. Cryptographic Standards & Rate Limiting
+
+### Cryptographic Rigor
+- **Password Hashing**: Use **Argon2id** (minimum 64MB memory, 3 iterations) or **bcrypt** (work factor $\ge 12$). Never use SHA-256, SHA-1, or MD5 for password storage.
+- **Data Encryption at Rest**: Encrypt sensitive PII, access tokens, and secrets using **AES-256-GCM** or **ChaCha20-Poly1305** with authenticated encryption.
+- **Data in Transit**: Mandate **TLS 1.3** across all external and internal microservice communication.
+
+### Distributed Rate Limiting
+Protect APIs against brute force, scraping, and denial-of-service (DoS) attacks using a distributed Token Bucket or Leaky Bucket algorithm backed by Redis:
+- **Authentication Endpoints (`/login`, `/signup`)**: Strict limit of 5 requests per minute per IP.
+- **Public API Endpoints**: Default limit of 100 requests per minute per IP/API token.
+- **Response Headers**: Return RFC 6585 headers: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, and `429 Too Many Requests` when exceeded.
+
+---
+
+## 3. Regulatory Compliance: SOC 2, ISO 27001 & GDPR
+
+All systems handling sensitive, customer, or enterprise data must satisfy fundamental compliance controls:
+
+1. **Immutable Audit Trails (SOC 2 CC6.8 / ISO 27001 A.12.4)**:
+   - All state mutations, privilege changes, and authentication events must write to an immutable audit log recording: `timestamp`, `actorId`, `tenantId`, `action`, `resourceId`, `clientIp`, and `userAgent`.
+   - Audit logs must be retained in append-only storage and protected from tampering or deletion.
+2. **GDPR Data Erasure Rights (Article 17 "Right to be Forgotten")**:
+   - Systems must provide an automated data erasure pipeline capable of permanently deleting or cryptographically pseudonymizing user PII across all databases and backups within 30 days of a verified request.
+3. **Least Privilege Access (SOC 2 CC6.1)**:
+   - Developers and runtime services must operate under strict principle of least privilege. Production database credentials and encryption keys must never be accessible in local development environments.

package/docs/rules/server_driven_ui.md

@@ -4,7 +4,24 @@
 
 ---
 
-## 1. Declarative Client-Agnostic SDUI Schema
+## 1. The YAGNI Gate: Static Client Components vs. Server-Driven UI
+
+Server-Driven UI requires building and maintaining a JSON schema specification, schema versioning, validation, and multi-platform component interpreters. **Never build a Server-Driven UI when standard client-side components and modern web deployments solve the problem.**
+
+```mermaid
+flowchart TD
+    subgraph SDUIGate["Server-Driven UI YAGNI Gate"]
+        B1["1. Simple Baseline (Day 1)<br/>• Standard React/JSX components styled with Tailwind CSS<br/>• Instant web deployments via continuous delivery<br/>• Zero dynamic layout interpreters or backend schema JSONs"]
+        B2["2. Anti-Triggers (Forbidden)<br/>• Web-only SaaS dashboards, internal admin tools, or landing pages<br/>• Early-stage products iterating on UI layouts<br/>• Teams without multi-platform client parity requirements"]
+        B3["3. The Tipping Point (Graduation)<br/>• Native mobile apps (iOS/Android) where app store review cycles delay urgent UI/flow mutations<br/>• Multi-tenant white-label products where customers dynamically construct custom form layouts<br/>• Cross-platform parity: 1 backend drives layout across Web, iOS SwiftUI, and Android Jetpack Compose"]
+        B1 -->|Forbidden if web-only or early| B2
+        B1 -->|Triggered by multi-platform or white-label| B3
+    end
+```
+
+---
+
+## 2. Declarative Client-Agnostic SDUI Schema
 
 The backend provides a declarative UI layout schema describing fields, layouts, dynamic visibility rules (via Common Expression Language or JSON expressions), and allowed actions (`_actions`):
 
@@ -38,7 +55,7 @@ The backend provides a declarative UI layout schema describing fields, layouts,
 
 ---
 
-## 2. Multi-Platform Component Registries
+## 3. Multi-Platform Component Registries
 
 Frontend clients (Web, Mobile, Desktop) never contain hardcoded tenant branching. Each platform implements a local **Component Registry** mapping backend descriptors to native platform primitives:
 
@@ -48,7 +65,7 @@ Frontend clients (Web, Mobile, Desktop) never contain hardcoded tenant branching
 
 ---
 
-## 3. Universal Design Tokens (W3C DTCG Standard)
+## 4. Universal Design Tokens (W3C DTCG Standard)
 
 Manage tenant white-label branding and design systems via the **W3C Design Tokens Community Group (DTCG)** specification: