azcodr 1.3.0 → 1.4.0

package/docs/rules/database_operations.md

@@ -1,27 +1,69 @@
-# Database Operations, PITR & Least-Privilege Roles
+# Database Operations, Migrations & Performance Engineering
 
-> **Core Mandate:** Enforce continuous Point-In-Time Recovery (PITR), causal read-after-write routing, non-blocking table maintenance, connection pooling, and least-privilege role separation.
+> **Core Mandate:** Enforce zero-downtime expand-contract migrations via declarative tools, systematic N+1 query elimination via DataLoader/batching, composite tenant indexing, connection pooling, and continuous point-in-time recovery (PITR).
 
 ---
 
-## 1. High Availability, Backups & Disaster Recovery (DR)
+## 1. Zero-Downtime Expand-Contract Migrations
 
-- **Continuous Point-In-Time Recovery (PITR)**: Utilize continuous write-ahead logging (WAL) archiving and periodic base backups (**WAL-G**, **pgBackRest**, or engine-native tooling) to guarantee restoration to any specific second.
-- **Causal Read-After-Write Consistency**: Read replicas experience asynchronous replication lag. Immediately following a state-mutating command (`POST`, `PUT`, `DELETE`), pin client sessions to the primary database instance for a bounded window (e.g. 2 seconds) before resuming read-replica routing.
+Database schema migrations must never require maintenance windows or downtime. Follow the **3-Phase Expand-Contract Pattern**:
+
+```mermaid
+flowchart LR
+    P1["Phase 1: EXPAND<br/>(Zero-Downtime DDL)<br/>Add new column as NULLABLE/DEFAULT<br/>Zero breaking locks"]
+    P2["Phase 2: DUAL-RUN & BACKFILL<br/>(Application Rolling Update)<br/>Deploy app writing both columns<br/>Backfill historical rows<br/>Read fallback to old column"]
+    P3["Phase 3: CONTRACT<br/>(Cleanup DDL)<br/>Drop old column<br/>after 100% traffic migrates"]
+    P1 --> P2 --> P3
+```
+
+### Invariants:
+1. **Never Rename Columns in a Single Step**: Renaming a column causes running application instances to crash. Always expand with a new column, dual-write, backfill, and drop the old column in a subsequent release.
+2. **Concurrent Index Creation**: In PostgreSQL, never create indexes with standard blocking DDL. Always use `CREATE INDEX CONCURRENTLY` to prevent locking table writes.
+3. **Declarative Migration Tooling**: Standardize on open-source declarative migration tools (e.g. **Atlas**, **Flyway**, or **Liquibase**) that compute deterministic migration plans against production schemas.
+
+---
+
+## 2. Performance Engineering & N+1 Query Defense
+
+A catastrophic database performance bottleneck is the **N+1 Query Problem**, where an application executes 1 query for a list and $N$ additional queries for related records in a loop.
+
+### Invariants:
+1. **Mandatory DataLoader / Batch Fetching**: In GraphQL resolvers, ORM mappers, or loop iterations, always batch entity queries via a DataLoader or SQL `IN (...)` batch queries:
+   ```typescript
+   // Correct: Single batched query for all tenant users
+   const users = await userLoader.loadMany(userIds);
+   ```
+2. **Composite Tenant Indexes**: In multi-tenant systems, every primary lookup index must include `tenant_id` as the leading column:
+   ```sql
+   -- Correct: Optimized for tenant-scoped date range filtering
+   CREATE INDEX idx_orders_tenant_created 
+     ON orders (tenant_id, created_at DESC);
+   ```
+3. **Index Hygiene & Covering Indexes**: Use `EXPLAIN (ANALYZE, BUFFERS)` to verify index scans. For high-frequency queries, use covering indexes (`INCLUDE (...)`) to satisfy queries directly from index pages without heap fetches.
 
 ---
 
-## 2. Table Maintenance & Bloat Defragmentation
+## 3. Connection Pooling & Resource Limits
+
+Database connections are expensive resources requiring thread stacks and memory allocation. An uncapped connection pool will exhaust database memory and crash the server under load spikes.
 
-- **Online Maintenance**: Table and index space must be reclaimed using non-blocking online utilities (**`pg_repack`**, `gh-ost`, or `pt-online-schema-change`), strictly prohibiting locking full table rewrites during online hours.
-- **Background Autovacuum / Optimization**: Configure proactive background vacuuming and compaction thresholds to prevent transaction ID wraparound and table bloat on high-throughput tables.
+### Invariants:
+1. **Dedicated Connection Pooling**: In production, deploy a dedicated connection pooler (e.g. **PgBouncer** in transaction pooling mode for PostgreSQL, or **HikariCP** in JVM runtimes).
+2. **Connection Sizing Formula**: Size application pools conservatively using the standard Postgres sizing formula:
+   $$\text{connections} = ((\text{core\_count} \times 2) + \text{effective\_disk\_count})$$
+   Over-allocating connections (e.g., 500 connections on an 8-core server) causes severe CPU thrashing and context-switch latency.
+3. **Connection Lifecycle Limits**: Configure `max_lifetime` (e.g. 30 minutes) and `idle_timeout` (e.g. 10 minutes) to cycle stale connections and prevent socket leaks.
 
 ---
 
-## 3. Least-Privilege Role Partitioning & Audit Trails
+## 4. Operational Resilience & Backup Baselines
 
-Enforce strict separation of database credentials across execution environments:
-- **`migration_deployer`**: DDL privileges (`CREATE`, `ALTER`, `DROP`) restricted to CI/CD automated migration pipelines.
-- **`app_runtime`**: DML privileges only (`SELECT`, `INSERT`, `UPDATE`, `DELETE`) with zero DDL or schema alteration rights.
-- **`analytics_readonly`**: Read-only access to sanitized views and replica nodes.
-- **Tamper-Proof Audit Logging**: Export schema changes, privilege grants, and sensitive queries to immutable external log sinks.
+1. **Continuous Point-In-Time Recovery (PITR)**: Production databases must configure continuous WAL (Write-Ahead Log) archiving to object storage (e.g. via `pgBackRest` or `wal-g`), enabling recovery to any arbitrary second within the retention window.
+2. **Autovacuum Tuning (PostgreSQL)**: For high-throughput transactional tables, tune autovacuum parameters to prevent table bloat and transaction ID wraparound:
+   ```sql
+   ALTER TABLE orders SET (
+     autovacuum_vacuum_scale_factor = 0.05,
+     autovacuum_vacuum_cost_limit = 1000
+   );
+   ```
+3. **Database Role Separation**: The application connection user must never connect as `postgres` or `superuser`. Create a dedicated least-privilege `app_user` granted only `DML` (`SELECT`, `INSERT`, `UPDATE`, `DELETE`) on application tables.

package/docs/rules/design_patterns.md

@@ -19,17 +19,24 @@
 - **Strategy Pattern**: Swap algorithms or execution behavior at runtime without code changes (e.g. tenant-specific pricing algorithms, shipping calculation strategies).
 - **Result / Either Pattern**: Model anticipated domain errors as explicit return values (`Result<T, E>`) rather than throwing untyped exceptions across architectural boundaries:
 
-```
-┌────────────────────────────────────────────────────────┐
-│ Universal Result Pattern Semantics                     │
-├────────────────────────────────────────────────────────┤
-│ Result<T, E> = Ok(T) | Err(E)                          │
-│                                                        │
-│ Rust:       Result<T, DomainError>                     │
-│ Go:         (T, error)                                 │
-│ TypeScript: type Result<T, E> = Ok<T> | Err<E>         │
-│ Python:     Union[Success[T], Failure[E]]              │
-└────────────────────────────────────────────────────────┘
+```mermaid
+classDiagram
+    class Result~T_E~ {
+        <<Universal Semantics>>
+        +isOk() boolean
+        +isErr() boolean
+        +unwrap() T
+        +unwrapErr() E
+    }
+    class Ok~T~ {
+        +value: T
+    }
+    class Err~E~ {
+        +error: E
+    }
+    Result <|-- Ok
+    Result <|-- Err
+    note for Result "Rust: Result~T, DomainError~<br/>Go: (T, error)<br/>TypeScript: type Result~T, E~ = Ok~T~ | Err~E~<br/>Python: Union[Success[T], Failure[E]]"
 ```
 
 Domain services must return explicit Result types, compelling callers to handle failure branches deterministically.

package/docs/rules/devops_ci_cd.md

@@ -0,0 +1,76 @@
+# DevOps, CI/CD, Container Infrastructure & DevSecOps
+
+> **Core Mandate:** Enforce trunk-based continuous integration with shift-left automated gates, minimal distroless OCI container packaging, non-root execution security, software supply chain verification (SBOM & Trivy), and zero-downtime continuous deployment.
+
+---
+
+## 1. Continuous Integration & Trunk-Based Development
+
+CI pipelines must execute fast, deterministic, shift-left quality gates on every commit and pull request:
+
+```
+[Local Commit] ──► [Pre-Commit Hook] ──► [Pull Request] ──► [Automated CI Gate] ──► [Merge to Main]
+                    • Secretlint          • Build Cache      • Lint & Format Check
+                    • Type Check                             • 100.00% Test Coverage
+                                                             • DevSecOps CVE Scan
+```
+
+### Invariants:
+1. **Trunk-Based Development**: Feature branches must be short-lived ($\le 24$ hours) and merged into `main` continuously. Avoid long-lived feature branches that cause painful merge conflicts.
+2. **Shift-Left Automated PR Gates**: Every PR must pass automated CI checks before merge:
+   - Zero linter or syntax errors (`npm run lint` / `cargo clippy`).
+   - Strict type-checking (`tsc --noEmit` / `mypy`).
+   - 100.00% automated test coverage gate.
+3. **Deterministic Build Caching**: Cache dependency directories (`~/.pnpm-store`, `~/.cargo`, `~/.cache/uv`) and Docker layer caches to maintain pipeline execution times under 3 minutes.
+
+---
+
+## 2. Secure OCI Container Infrastructure
+
+All production container images must follow strict security minimization standards:
+
+```dockerfile
+# Multi-Stage Build Pattern
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm build
+
+# Minimal Distroless Runtime Stage
+FROM gcr.io/distroless/nodejs22-debian12:nonroot
+WORKDIR /app
+COPY --from=builder --chown=nonroot:nonroot /app/dist ./dist
+COPY --from=builder --chown=nonroot:nonroot /app/node_modules ./node_modules
+USER nonroot
+EXPOSE 3000
+ENTRYPOINT ["node", "dist/index.js"]
+```
+
+### Invariants:
+1. **Multi-Stage Builds**: Build tools, package managers, and compilers must never leak into final runtime images.
+2. **Minimal Distroless / Scratch Base**: Use Google Distroless or `scratch` images. Never ship package managers (`apt`, `apk`), shells (`bash`, `sh`), or debugging utilities in production images.
+3. **Non-Root Execution**: Containers must never run as UID 0 (`root`). Always specify an unprivileged user (`USER nonroot:nonroot` or `USER 10001:10001`).
+4. **Read-Only Root Filesystem**: Configure container runtimes with `read_only: true`, mounting ephemeral tmpfs only to designated writable directories (`/tmp`).
+
+---
+
+## 3. DevSecOps & Supply Chain Security
+
+Security checks must be embedded directly into developer workflows and automated pipelines:
+
+1. **Pre-Commit Secret Scanning**: Gating tools (e.g. **Secretlint**, **Gitleaks**) must block commits containing private keys, API tokens, passwords, or cloud credentials.
+2. **Software Bill of Materials (SBOM)**: Every release artifact must generate a machine-readable SBOM in **CycloneDX** or **SPDX** format (using `syft` or `cyclonedx-cli`) documenting all direct and transitive dependencies.
+3. **Automated Vulnerability Scanning**: Scan container images and dependencies with **Trivy** or **Grype** in CI. Automatically fail pipelines on unpatched `CRITICAL` or `HIGH` Common Vulnerabilities and Exposures (CVEs).
+
+---
+
+## 4. Continuous Deployment & Zero-Downtime Rollouts
+
+1. **Zero-Downtime Deployment Strategy**: Deployments must utilize rolling updates, canary releases, or blue/green switches. New container instances must pass readiness probes before receiving production traffic.
+2. **Container Health & Lifecycle Probes**:
+   - `readinessProbe`: Validates database connectivity and dependency readiness before routing HTTP traffic.
+   - `livenessProbe`: Detects deadlocks and restarts unresponsive containers.
+   - Graceful Shutdown: Handle `SIGTERM` deterministically by draining in-flight requests within a 30-second termination window.
+3. **Cryptographic Image Signing**: Sign container images with **Cosign** (Sigstore) during CI, and enforce admission controller verification in production clusters.

package/docs/rules/domain_driven_design.md

@@ -8,19 +8,23 @@
 
 Software engineering fails when teams jump directly into the **Solution Space** (choosing languages, frameworks, databases, and microservices) before fully defining the **Problem Space**.
 
-```
-  ┌────────────────────────────────────────────────────────────────────────┐
-  │                           THE PROBLEM SPACE                            │
-  │  Business Problem ➔ Subdomains (Core/Supporting/Generic) ➔ Invariants  │
-  │  Operational Constraints: Execution target, Latency budget, GC limits  │
-  └───────────────────────────────────┬────────────────────────────────────┘
-                                      │ Shapes & Dictates
-                                      ▼
-  ┌────────────────────────────────────────────────────────────────────────┐
-  │                           THE SOLUTION SPACE                           │
-  │  Bounded Contexts ➔ Architectural Style (DOD, Hexagonal, Pipeline)      │
-  │  Emergent Toolchain: Programming Language, Runtime, Persistence        │
-  └────────────────────────────────────────────────────────────────────────┘
+```mermaid
+flowchart TD
+    subgraph ProblemSpace["The Problem Space (The Essence)"]
+        direction TB
+        P1["Business Problem ➔ Subdomains (Core / Supporting / Generic) ➔ Invariants"]
+        P2["Operational Constraints: Execution target, Latency budget, GC limits"]
+        P1 --- P2
+    end
+
+    subgraph SolutionSpace["The Solution Space (The Accidents)"]
+        direction TB
+        S1["Bounded Contexts ➔ Architectural Style (DOD, Hexagonal, Pipeline)"]
+        S2["Emergent Toolchain: Programming Language, Runtime, Persistence"]
+        S1 --- S2
+    end
+
+    ProblemSpace -->|Shapes & Dictates| SolutionSpace
 ```
 
 - **The Problem Space (The Essence - Fred Brooks):** Concerns *what* problem is being solved, the entities, state transitions, and operational constraints (e.g. 16.6ms frame budget for games, zero-install browser sandbox for extensions, or ACID compliance for banking). **Zero technology, stack, or database choices are permitted in the Problem Space.**

package/docs/rules/feature_flags.md

@@ -4,9 +4,26 @@
 
 ---
 
-## 1. OpenFeature Standard Architecture
+## 1. The YAGNI Gate: Environment Variables vs. Dynamic Feature Flags
+
+Dynamic feature flag platforms (Flipt, Unleash) introduce network I/O, external infrastructure dependencies, and branching code complexity. **Never deploy a feature flag server when an environment variable or static config satisfies the requirement.**
+
+```mermaid
+flowchart TD
+    subgraph FlagGate["Feature Flag YAGNI Gate"]
+        B1["1. Simple Baseline (Day 1)<br/>• Static environment variable (ENABLE_NEW_CHECKOUT=true)<br/>• Compile-time or build-time feature toggling<br/>• Zero external flag servers (no Flipt, Unleash, LaunchDarkly)"]
+        B2["2. Anti-Triggers (Forbidden)<br/>• Flags that only change during scheduled code deployments<br/>• Low-risk internal refactors covered by automated test suites<br/>• Local CLI tools, browser extensions, or single-tenant utilities"]
+        B3["3. The Tipping Point (Graduation)<br/>• Percentage-based canary rollouts (5% -> 25% -> 100%)<br/>• Non-engineering product/business teams require runtime toggling without deployment<br/>• Contextual tenant targeting (per subscription tier or tenant ID)<br/>• High-blast-radius integrations requiring instant kill-switches"]
+        B1 -->|Forbidden if static or low-risk| B2
+        B1 -->|Triggered by canaries or runtime targeting| B3
+    end
+```
+
+---
+
+## 2. OpenFeature Standard Architecture
 
-Utilize open-source `@openfeature/server-sdk` with open-source providers (Flipt or Unleash):
+When the tipping point is reached, utilize open-source `@openfeature/server-sdk` with open-source providers (Flipt or Unleash):
 
 ```typescript
 import { OpenFeature, Client } from '@openfeature/server-sdk';
@@ -18,7 +35,7 @@ export const featureClient: Client = OpenFeature.getClient();
 
 ---
 
-## 2. Contextual Tenant Targeting
+## 3. Contextual Tenant Targeting
 
 Pass tenant identity and contextual attributes during evaluation:
 
@@ -36,7 +53,7 @@ const isEnabled = await featureClient.getBooleanValue(
 
 ---
 
-## 3. Flag Lifecycle Governance
+## 4. Flag Lifecycle Governance
 
 - **Emergency Kill Switches**: Every high-risk feature or third-party integration must be wrapped in a flag that can immediately disable functionality without code redeployment.
 - **Retirement Mandate**: When a feature is 100% rolled out for > 30 days, author a task to purge the flag and its dead code branches.

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