azcodr 1.3.0 → 1.5.0

package/docs/rules/database_integrity.md

@@ -1,80 +0,0 @@
-# Database Integrity, Constraints & Defensive Design
-
-> **Core Mandate:** Enforce data integrity via explicit foreign key delete semantics, domain CHECK constraints, interval exclusion constraints, partial unique indexes for soft deletes, and Universal Total Audit accountability.
-
----
-
-## 1. Foreign Key `ON DELETE` Semantics
-
-- **Default to `RESTRICT`**: For critical domain entities, tenant records, and financial ledgers to prevent accidental cascade destruction.
-- **Use `CASCADE` Strictly**: For direct, owned child records (e.g. `OrderItem` owned by `Order`).
-- **Use `SET NULL`**: When foreign relations are optional.
-
----
-
-## 2. Domain CHECK Constraints & Interval Exclusion
-
-- **Domain Invariants**:
-  ```sql
-  ALTER TABLE "Invoice" ADD CONSTRAINT chk_invoice_positive_amount CHECK (amount >= 0);
-  ALTER TABLE "Subscription" ADD CONSTRAINT chk_sub_dates CHECK (end_date >= start_date);
-  ```
-- **Prevent Overlapping Reservations**:
-  ```sql
-  CREATE EXTENSION IF NOT EXISTS btree_gist;
-  ALTER TABLE "RoomReservation" ADD CONSTRAINT no_overlapping_reservations
-    EXCLUDE USING gist (room_id WITH =, reservation_period WITH &&);
-  ```
-
----
-
-## 3. Soft Delete Unique Constraint Trap
-
-A standard `UNIQUE(email)` constraint fails when an active user signs up with the email of a soft-deleted record.
-- **Mandatory Standard**: Always use partial unique indexes for soft-deleted tables:
-  ```sql
-  CREATE UNIQUE INDEX idx_users_email_active ON "User"(email) WHERE deleted_at IS NULL;
-  ```
-
----
-
-## 4. Relational Foreign Key Invariants & UI Mapping
-
-- **Mandatory Existence Validation:** The application and domain layers must defensively assert foreign key target existence prior to child entity persistence. If a referenced parent entity does not exist, return an RFC 7807 problem detail (`400 Bad Request` or `404 Not Found`).
-- **No Raw Identifier Text Inputs:** User interfaces must never expose raw string or UUID input fields for foreign key references. Associations must be selected via accessible dropdown selectors (`shadcn/ui` `<Select>`) displaying human-readable contextual metadata (names, labels, numbers, pricing).
-- **Complete Lifecycle CRUD:** All relational entities must provide complete CRUD functionality (Create, Read/Detail, Update/Transition, Delete/Archive) before being considered feature-complete.
-
----
-
-## 5. Mandatory Universal Audit Columns
-
-Every stateful entity across all relational schemas, ORMs, and persistence layers must maintain strict audit accountability.
-
-### The Canonical 6 Total Audit Fields:
-All mutable database tables, domain entities, and models must define the total audit suite:
-1. **`createdAt` / `created_at`** (`TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP`): Immutable timestamp when the record was initially created.
-2. **`createdBy` / `created_by`** (`VARCHAR/TEXT NOT NULL DEFAULT 'SYSTEM'`): The user ID (`User.id`) of the authenticated actor who created the record, or `'SYSTEM'` for automated background tasks, seeds, or system bootstrap.
-3. **`updatedAt` / `updated_at`** (`TIMESTAMP WITH TIME ZONE NOT NULL`): Timestamp automatically updated on every record mutation.
-4. **`updatedBy` / `updated_by`** (`VARCHAR/TEXT NOT NULL DEFAULT 'SYSTEM'`): The user ID (`User.id`) of the authenticated actor who performed the most recent mutation, or `'SYSTEM'` for automated workflows.
-5. **`deletedAt` / `deleted_at`** (`TIMESTAMP WITH TIME ZONE NULL`): Timestamp when the record was soft-deleted/archived. Null for active records.
-6. **`deletedBy` / `deleted_by`** (`VARCHAR/TEXT NULL`): The user ID (`User.id`) of the authenticated actor who performed or authorized deletion, or `'SYSTEM'`.
-
-All queries for active records MUST filter `WHERE deletedAt IS NULL` (or ORM equivalent). Paired with partial unique indexes `WHERE deleted_at IS NULL` where uniqueness constraints apply.
-
-### Append-Only Immutable Ledgers / Log Streams:
-Pure financial ledgers (e.g. `PaymentLedgerEntry`, `JournalEntry`) and event outbox streams are strictly immutable. They require:
-- **`createdAt` / `created_at`** (`NOT NULL DEFAULT CURRENT_TIMESTAMP`)
-- **`createdBy` / `created_by`** (`NOT NULL DEFAULT 'SYSTEM'`)
-- *Mutations and soft-deletes are prohibited*: `updatedAt`, `updatedBy`, `deletedAt`, and `deletedBy` are omitted because records are append-only. Financial adjustments must be recorded as offsetting ledger entries.
-
----
-
-## 6. Semi-Structured Evolution & Cryptographic Audit Trails
-
-- **Non-Destructive Schema Evolution via JSON**: For contractual covenants, dynamic conditions, or variable metadata subject to rapid domain iteration, employ semi-structured JSON fields (`termsJson`, `metadataJson`) validated against JSON Schema rather than premature table migrations.
-- **Cryptographic Electronic Signatures & Execution Auditing**: Legal agreements and execution records require defensible evidence beyond a boolean `isSigned` flag. All executed agreements must capture:
-  1. Typed signer legal name and designated role.
-  2. ISO 8601 UTC execution timestamp.
-  3. Authenticated actor ID (`userId`).
-  4. Client network IP address and User-Agent string.
-  5. Deterministic cryptographic checksum / hash of the executed terms.

package/docs/rules/database_migrations.md

@@ -1,41 +0,0 @@
-# Zero-Downtime Database Migrations (Expand-Contract)
-
-> **Core Mandate:** Enforce versioned declarative migrations, zero-downtime expand-contract schema evolutions, non-blocking concurrent index creation, and two-phase constraint validation.
-
----
-
-## 1. Universal Versioned & Declarative Migrations
-
-- **Strict Version Control**: All database modifications must occur via versioned migration engines (**Atlas**, **Flyway**, **Liquibase**, or **Goose**).
-- **Prohibited Actions**: Strictly forbid unversioned schema-push commands or raw manual DDL in staging or production environments.
-- **Automated CI Validation**: CI pipelines must lint migrations for breaking changes, lock timeouts, and full-table scans before merging schema PRs.
-
----
-
-## 2. Safe Column Additions & Deprecations (Expand-Contract)
-
-Never rename or drop a column in a single deployment step. Follow the 5-phase protocol:
-1. **Phase 1 (Expand):** Add the new column as nullable or with a non-locking default.
-2. **Phase 2 (Double-Write):** Deploy application version writing to both old and new columns; reads continue from the old column.
-3. **Phase 3 (Backfill):** Run batched background jobs backfilling historical rows from the old column to the new column in bounded batches (e.g. 500–1000 rows).
-4. **Phase 4 (Switch Read):** Deploy application reading and writing solely to the new column.
-5. **Phase 5 (Contract):** In the subsequent release, drop the old column and legacy constraints from the database.
-
----
-
-## 3. Concurrent Non-Blocking Indexing & Constraint Validation
-
-- **Concurrent Indexes**: Always construct indexes non-blockingly (`CREATE INDEX CONCURRENTLY` in PostgreSQL, `ALGORITHM=INPLACE, LOCK=NONE` in MySQL) to avoid locking read/write traffic:
-  ```sql
-  CREATE INDEX CONCURRENTLY idx_orders_customer_created 
-    ON orders (customer_id, created_at DESC);
-  ```
-- **Two-Phase Constraints**: Attach foreign keys and check constraints without scanning historical rows upfront, then validate asynchronously:
-  ```sql
-  -- Step 1: Attach foreign key without blocking writes
-  ALTER TABLE orders ADD CONSTRAINT fk_orders_tenant
-    FOREIGN KEY (tenant_id) REFERENCES tenants(id) NOT VALID;
-
-  -- Step 2: Validate constraint concurrently
-  ALTER TABLE orders VALIDATE CONSTRAINT fk_orders_tenant;
-  ```

package/docs/rules/database_performance.md

@@ -1,44 +0,0 @@
-# Database Performance & N+1 Prevention
-
-> **Core Mandate:** Eliminate N+1 query bottlenecks via explicit relation batching, enforce strict composite indexing, size connection pools scientifically, and terminate runaway queries with statement timeouts.
-
----
-
-## 1. N+1 Query Elimination
-
-- **Prohibit Iterative Queries in Loops**: Never query child collections inside iteration loops.
-  ```
-  ❌ FORBIDDEN:
-  parents = query("SELECT id FROM parent_table")
-  for p in parents:
-      children = query("SELECT * FROM child_table WHERE parent_id = :id", p.id)
-  ```
-- **Batching & Eager Fetching**: Always fetch related entities via single `JOIN` statements or batched `IN` clauses (`WHERE parent_id IN (...)`).
-  ```
-  ✅ CORRECT:
-  parents = query("SELECT id FROM parent_table")
-  children = query("SELECT * FROM child_table WHERE parent_id IN (:ids)", parents.map(id))
-  ```
-- **Universal DataLoader Pattern**: For decentralized domain resolvers or GraphQL pipelines, employ language-native DataLoader ports to batch and deduplicate entity lookups within an execution cycle.
-
----
-
-## 2. Multi-Tenant Indexing Strategy
-
-- **Tenant-Leading Composite Indexes**:
-  Every multi-tenant query pattern must be backed by a composite index where `tenant_id` is the primary leading column:
-  ```sql
-  CREATE INDEX idx_orders_tenant_created ON orders (tenant_id, created_at DESC);
-  CREATE UNIQUE INDEX uq_orders_tenant_number ON orders (tenant_id, order_number);
-  ```
-- **Covering Indexes**:
-  Include frequently projected columns in index definitions (`INCLUDE (status, total_amount)` in engines that support index-only scans) to avoid secondary table lookups.
-
----
-
-## 3. Connection Pooling & Statement Timeouts
-
-- **Scientific Pool Sizing Formula**:
-  $$\text{max\_connections} = (\text{CPU Cores} \times 2) + \text{Effective Disk / Spindle Count}$$
-- **Transaction-Scoped Pooling**: Use lightweight connection poolers (e.g. PgBouncer, ProxySQL, or HikariCP) in transaction pooling mode to support thousands of concurrent client connections without memory exhaustion.
-- **Defensive Statement Timeout**: Enforce strict statement timeouts (e.g. 5 seconds) at the connection pool or gateway layer to terminate unindexed runaway queries before they degrade the cluster.

package/docs/rules/database_transactions.md

@@ -1,81 +0,0 @@
-# Database Transactions, ACID Atomicity & Outbox Pattern
-
-> **Core Mandate:** Enforce full ACID transactional atomicity, appropriate isolation levels, defensive timeouts, deadlock prevention, and eliminate the dual-write problem via the Transactional Outbox pattern.
-
----
-
-## 1. ANSI SQL Transaction Isolation Levels
-
-1. **`Read Committed` (Default):** Guarantees statements see only committed data (eliminates dirty reads). Suitable for standard CRUD operations.
-2. **`Repeatable Read` (Snapshot Isolation):** All operations within the transaction see the exact same database snapshot taken at transaction start. Mandatory for multi-entity financial calculations, ledger balance transfers, and inventory decrement operations.
-3. **`Serializable`:** Strict serializability. Prevents phantom reads and write skew. Mandatory for complex booking and seat allocation operations. Requires application-level retry loops with jittered exponential backoff to handle serialization failures.
-
----
-
-## 2. Defensive Timeouts & Deadlock Prevention
-
-Prevent hung transactions or lock waits from starving database connection pools across any engine:
-
-```sql
-SET lock_timeout = '3s';                           -- Abort if lock cannot be acquired within 3s
-SET statement_timeout = '10s';                      -- Abort queries running longer than 10s
-SET idle_in_transaction_session_timeout = '30s';   -- Abort hung transactions idle for > 30s
-```
-
-### Deterministic Lock Ordering
-Always acquire locks on entities in a globally consistent order across application services (e.g. sort resource IDs lexicographically before issuing `SELECT ... FOR UPDATE`) to prevent circular wait deadlocks.
-
----
-
-## 3. Abstract Unit of Work & Transaction Boundaries
-
-Application services must control transaction boundaries via an abstract **Unit of Work** port, keeping domain logic decoupled from concrete ORMs:
-
-```
-┌────────────────────────────────────────────────────────┐
-│ Unit of Work Port Contract (Agnostic Specification)    │
-├────────────────────────────────────────────────────────┤
-│ executeTransaction(options, transactionCallback):       │
-│   options:                                             │
-│     isolationLevel: READ_COMMITTED | REPEATABLE_READ   │
-│     timeoutMs: integer (default 10000)                 │
-│     maxWaitMs: integer (default 5000)                  │
-│   behavior:                                            │
-│     1. Begin transaction on scoped connection          │
-│     2. Execute callback with transactional context     │
-│     3. On error: Rollback and propagate domain error   │
-│     4. On success: Commit atomically                   │
-└────────────────────────────────────────────────────────┘
-```
-
----
-
-## 4. Eliminating Dual-Writes: Transactional Outbox Pattern
-
-Never write to the database and publish to a message broker sequentially. Persist the domain mutation and the event record atomically within the same database transaction:
-
-```sql
-CREATE TABLE outbox_events (
-  id VARCHAR(64) PRIMARY KEY,
-  tenant_id VARCHAR(64) NOT NULL,
-  aggregate_type VARCHAR(64) NOT NULL,
-  aggregate_id VARCHAR(64) NOT NULL,
-  event_type VARCHAR(128) NOT NULL,
-  payload TEXT NOT NULL,
-  status VARCHAR(32) NOT NULL DEFAULT 'PENDING',
-  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
-);
-
-CREATE INDEX idx_outbox_pending ON outbox_events(status, created_at);
-```
-
-### Asynchronous Outbox Relaying
-- **Change Data Capture (CDC)**: Stream transaction logs directly to Kafka/NATS using tools like **Debezium**.
-- **Polling Worker**: Run background workers executing non-blocking polling:
-  ```sql
-  SELECT * FROM outbox_events 
-  WHERE status = 'PENDING' 
-  ORDER BY created_at ASC 
-  LIMIT 100 
-  FOR UPDATE SKIP LOCKED;
-  ```

package/docs/rules/devsecops.md

@@ -1,33 +0,0 @@
-# DevSecOps, Secret Scanning & SBOM Standards
-
-> **Core Mandate:** Enforce automated pre-commit secret gating, CycloneDX SBOM generation, polyglot SAST via Semgrep, and container/lockfile scanning with Trivy.
-
----
-
-## 1. Automated Pre-Commit Secret Gating
-
-- Run open-source secret scanning (**`gitleaks`** or **`secretlint`**) on every staged commit via pre-commit hooks.
-- Never bypass git commit hooks (`--no-verify`). Strictly forbid committing credentials, private keys, certificates, or API tokens to version control.
-
----
-
-## 2. Software Bill of Materials (SBOM) Generation
-
-- Generate reproducible **CycloneDX 1.6** or **SPDX** SBOMs for all build artifacts using open-source **`syft`**:
-  ```bash
-  syft dir:. -o cyclonedx-json=sbom.json
-  ```
-- Archive the generated `sbom.json` alongside release binaries and container registries.
-- Sign release artifacts and container images cryptographically using **Cosign** (Sigstore) with SLSA provenance attestation.
-
----
-
-## 3. Polyglot SAST & Vulnerability Scanning
-
-- **Static Analysis (SAST)**: Standardize on **Semgrep** for cross-language security and quality linting across Go, Rust, Python, Java, and TypeScript.
-- **Dependency & Container CVE Scanning**: Scan lockfiles (`go.mod`, `Cargo.lock`, `package-lock.json`, `poetry.lock`, `pom.xml`) and OCI container base images using open-source **`trivy`** and **`grype`**:
-  ```bash
-  trivy fs --severity HIGH,CRITICAL .
-  grype sbom:sbom.json
-  ```
-- Any unpatched `HIGH` or `CRITICAL` Common Vulnerabilities and Exposures (CVE) halts the continuous integration pipeline immediately.

package/docs/rules/multitenancy_isolation.md

@@ -1,88 +0,0 @@
-# Multi-Tenancy Context Resolution & Data Isolation Models
-
-> **Core Mandate:** Enforce multi-tenancy isolation through dynamic context resolution combined with database-agnostic isolation models (AST query interceptors, RLS, schema namespaces, or connection routing) as an immutable backstop.
-
----
-
-## 1. Multi-Tenant Context Resolution
-
-Resolve tenant identity dynamically in an inbound gateway or middleware pipeline in strict priority order:
-1. **Host Subdomain**: `subdomain.app.com` (extracted via hostname regex).
-2. **Explicit Headers**: `X-Tenant-ID: <uuid>` or `X-Tenant-Slug: <slug>`.
-3. **Path Prefix**: `/t/:tenantSlug/...`.
-4. **JWT Claim Fallback**: Authenticated token `tid` (tenant ID) claim.
-
-*Validation:* If the resolved tenant does not exist or is in `SUSPENDED` status, immediately return **`403 Forbidden`** (`TENANT_SUSPENDED` or `TENANT_INVALID`). Propagate `TenantContext` across service calls using standard W3C Baggage headers or request contexts.
-
-- **Fail-Closed Multi-Tenancy Invariant**: Never trust client-supplied tenant headers (`X-Tenant-ID`) without cryptographically verifying that the authenticated session actor actually belongs to the requested tenant organization/workspace. Mismatched tenant headers must immediately fail closed with HTTP 403 `FORBIDDEN_TENANT_ACCESS`.
-
----
-
-## 2. Four Universal Data Isolation Models
-
-Never rely solely on application developers remembering to manually append `WHERE tenant_id = ?`. Standardize on one of four architectural isolation strategies:
-
-```mermaid
-flowchart TD
-  Request["Inbound Request (TenantContext)"] --> Strategy{"Isolation Strategy"}
-  
-  Strategy -->|"Model 1: Discriminator AST"| AST["Query Interceptor / AST Rewriter\n(Automatically injects tenant_id into AST before DB execution)"]
-  Strategy -->|"Model 2: Engine RLS"| RLS["Row-Level Security (RLS)\n(Database session config: current_setting / session variable)"]
-  Strategy -->|"Model 3: Schema Namespace"| Schema["Schema-per-Tenant\n(SET search_path / USE tenant_schema)"]
-  Strategy -->|"Model 4: Instance Routing"| Pool["Database-per-Tenant\n(Connection pool router per tenant ID)"]
-
-  AST --> Database[(Any Relational / Document DB)]
-  RLS --> Database
-  Schema --> Database
-  Pool --> Database
-```
-
-### Model 1: Universal AST Query Interceptor (Engine-Agnostic)
-The persistence layer interceptor parses the query Abstract Syntax Tree (AST) at runtime and automatically enforces `tenant_id = current_tenant` for all reads and mutations. Compatible with all ANSI SQL and NoSQL engines.
-
-### Model 2: Database Row-Level Security (RLS)
-For engines supporting native RLS (e.g. PostgreSQL, Oracle):
-```sql
-ALTER TABLE "Order" ENABLE ROW LEVEL SECURITY;
-ALTER TABLE "Order" FORCE ROW LEVEL SECURITY;
-
-CREATE POLICY order_tenant_isolation ON "Order"
-  FOR ALL
-  USING (tenant_id = current_setting('app.tenant_id', true)::uuid)
-  WITH CHECK (tenant_id = current_setting('app.tenant_id', true)::uuid);
-```
-> [!IMPORTANT]
-> **Connection Pool Safety:** Always set `is_local = true` when configuring session variables (`set_config('app.tenant_id', id, true)`). This restricts settings strictly to the current database transaction, preventing cross-tenant leakage in connection pools.
-
-### Model 3: Schema-per-Tenant
-Separate schemas per tenant within a shared database instance (`tenant_acme`, `tenant_globex`). Routing dynamically sets the active search path per transaction.
-
-### Model 4: Database-per-Tenant
-Dedicated physical database instances per enterprise tenant, selected by a dynamic connection pool resolver based on resolved tenant metadata.
-
----
-
-## 3. Polyglot Adapter Interceptor Contract
-
-Adapters in any language (Go, Rust, Python, Java, TypeScript) must expose an interceptor wrapping the data access layer:
-
-```
-┌────────────────────────────────────────────────────────┐
-│ Context Interceptor Contract (Pseudocode / Polyglot)   │
-├────────────────────────────────────────────────────────┤
-│ onQueryExecution(query, tenantContext):                │
-│   assert(tenantContext != null, "MissingTenantContext")│
-│   if adapter.supportsRLS():                            │
-│     execute("SET LOCAL app.tenant_id = :tenantId")     │
-│   else if adapter.supportsAST():                       │
-│     query.addPredicate(EQUALS("tenant_id", tenantId))  │
-│   return execute(query)                                │
-└────────────────────────────────────────────────────────┘
-```
-
----
-
-## 4. Tenant Lifecycle Management
-
-- **Atomic Provisioning**: Tenant creation must run inside an atomic transaction (provision tenant record, seed default RBAC roles `ADMIN`/`MEMBER`, assign subscription tier).
-- **GDPR Cascading Deletion**: Deleting a tenant triggers an asynchronous job that cascade purges or pseudonymizes all tenant records, ensuring zero orphaned data.

package/docs/rules/react.md

@@ -1,78 +0,0 @@
-# React & Modern Frontend Architecture
-
-> **Core Mandate:** Enforce modern, production-grade React standards across all web interfaces: `shadcn/ui` with Radix UI primitives, TanStack Query for server-state caching, React Hook Form / TanStack Form with Zod validation, and zero ad-hoc `useState` forms or raw `useEffect` fetch loops.
-
----
-
-## 1. Component Library & Styling (`shadcn/ui` + Radix UI)
-
-- **Accessible Radix Primitives**: All interactive UI components (dialogs, dropdowns, selects, tabs, tooltips, popovers) must be built on `@radix-ui` headless primitives or `shadcn/ui` components located in `@/components/ui/`.
-- **Zero Unstyled Raw Elements**: Never create unstyled raw HTML modals, dropdowns, or custom select tags.
-- **Tailwind Utility Styling (`cn` helper)**: Combine Tailwind utility classes using `clsx` and `tailwind-merge` (`cn(...)`) to allow clean prop overrides and consistent theming.
-- **Strict Prohibition of Native Dialogs**: As mandated in [`docs/rules/accessibility.md`](./accessibility.md), `window.alert()` and `window.confirm()` are strictly forbidden. Use accessible Radix UI dialogs (`<ConfirmDialog />`).
-
----
-
-## 2. Server State & Data Fetching (TanStack Query)
-
-- **Mandatory TanStack Query**: All asynchronous data fetching, caching, and mutation must use **TanStack Query (`@tanstack/react-query`)**.
-- **No Raw `useEffect` Fetch Loops**:
-  - *Anti-Pattern:* `useEffect(() => { fetch(...).then(setData) }, [])` with manual `loading` and `error` state.
-  - *Standard Pattern:*
-    ```tsx
-    const { data: resources, isLoading, error } = useQuery({
-      queryKey: ['resources', tenantId],
-      queryFn: () => api.getResources(),
-    });
-    ```
-- **Declarative Mutations & Invalidation**:
-  - Mutations must define `useMutation` with `onSuccess` cache invalidation:
-    ```tsx
-    const queryClient = useQueryClient();
-    const createResourceMutation = useMutation({
-      mutationFn: (newResource: CreateResourceInput) => api.createResource(newResource),
-      onSuccess: () => {
-        queryClient.invalidateQueries({ queryKey: ['resources'] });
-      },
-    });
-    ```
-- **Query Key Conventions**: Format query keys hierarchically as tuples: `['entity', id, ...filters]`, e.g., `['orders', orderId]`, `['users', tenantId]`.
-
----
-
-## 3. Form State Management & Validation (Zod + Form Engines)
-
-- **Mandatory Schema Validation**: Every form submission must be validated against a formal **Zod schema** (`z.object({ ... })`) that mirrors the shared DTO/input contracts from shared packages.
-- **Form State Engines**: Use **React Hook Form (`react-hook-form` + `@hookform/resolvers/zod`)** or **TanStack Form (`@tanstack/react-form`)**.
-- **Zero Unvalidated `useState` Multi-Field Objects**:
-  - *Anti-Pattern:*
-    ```tsx
-    const [form, setForm] = useState({ name: '', email: '' });
-    // manual validation in submit handler...
-    ```
-  - *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"`.
-
----
-
-## 4. State Separation & Data Tables
-
-- **State Hierarchy**:
-  1. **Server State (Remote)**: Manage exclusively with **TanStack Query**.
-  2. **URL State (Search / Pagination / Filters)**: Manage in URL search params per [`docs/rules/ui_navigation.md`](./ui_navigation.md).
-  3. **Form State (Transient Edits)**: Manage via **React Hook Form / TanStack Form**.
-  4. **Global Client State (Session/UI)**: Manage via **Zustand** (or React Context for theme/auth).
-- **Data Grids & Tables**: When building sortable, paginated, or virtualized tables, standardize on **TanStack Table (`@tanstack/react-table`)**.
-
----
-
-## 5. Theme Architecture & Design Token Completeness
-
-- **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/rest_api_conventions.md

@@ -1,46 +0,0 @@
-# REST API Design & Response Conventions
-
-> **Core Mandate:** Enforce standardized RESTful conventions, proper HTTP status codes, enumeration masking, and consistent subresource routing.
-
----
-
-## 1. HTTP Status Code Conventions
-
-- **`200 OK`**: Successful GET, PUT, or PATCH requests returning modified state.
-- **`201 Created`**: Successful resource creation via POST (must include `Location` header or created entity).
-- **`204 No Content`**: Successful DELETE operations or operations returning no body.
-- **`400 Bad Request`**: Malformed payload or validation schema failure.
-- **`401 Unauthorized`**: Missing, expired, or invalid authentication credentials.
-- **`403 Forbidden`**: Authenticated caller lacks permissions, tenant is suspended, or action targets protected system roles.
-- **`404 Not Found`**: Resource does not exist or belongs to another tenant (enumeration masking).
-- **`409 Conflict`**: Unique constraint collision or concurrent optimistic lock conflict.
-- **`422 Unprocessable Entity`**: Semantic domain violation.
-- **`429 Too Many Requests`**: Rate limit exceeded.
-- **`500 Internal Server Error`**: Unexpected server error.
-
----
-
-## 2. Cross-Tenant Enumeration Masking
-
-- If an authenticated user attempts to access a resource ID belonging to a different tenant, the API must return **`404 Not Found`** (rather than `403 Forbidden`) to prevent leaking the existence of other tenants' records.
-
----
-
-## 3. Subresource Endpoints & Pluralization
-
-- Always use pluralized nouns for resources (e.g. `/api/v1/users`, `/api/v1/orders`).
-- Use nested subresources for closely owned relations:
-  - `/api/v1/roles/:id/permissions`
-  - `/api/v1/tenants/:id/members`
-
----
-
-## 4. Full Lifecycle Resource CRUD & Route Tolerances
-
-- **Full Lifecycle Support:** All primary resource endpoints must provide comprehensive CRUD capabilities before completion:
-  - `GET /api/v1/<resources>`: List with pagination and tenant filtering.
-  - `GET /api/v1/<resources>/:id`: Detailed record by ID.
-  - `POST /api/v1/<resources>`: Create new entity returning `201 Created`.
-  - `PUT /api/v1/<resources>/:id` or `PATCH`: Update attributes or mutate state machine status.
-  - `DELETE /api/v1/<resources>/:id`: Remove or archive returning `204 No Content`.
-- **Defensive Route Tolerances for Infrastructure Probes:** Operational probes (`/healthz`, `/readyz`) must defensively support trailing slashes (`/healthz/`) and common typos (`/healtz/`) to prevent reverse proxy routing mismatches between frontend dev servers (e.g. Vite) and ingress gateways.

package/docs/rules/tenant_dynamic_schemas.md

@@ -1,88 +0,0 @@
-# Multi-Tenant Schema Extensibility & Virtual Entities
-
-> **Core Mandate:** Enforce dynamic schema extensibility via hybrid relational columns and validated JSON Schema (Draft 2020-12), prohibiting sparse nullable columns and branch-specific migrations in shared databases.
-
----
-
-## 1. Hybrid Core + JSON/Document Extensibility
-
-Store universal relational attributes in standard typed columns. Store tenant-specific custom fields in a semi-structured `custom_attributes` column governed by tenant-scoped JSON Schemas:
-
-```sql
-CREATE TABLE customers (
-  id VARCHAR(64) PRIMARY KEY,
-  tenant_id VARCHAR(64) NOT NULL,
-  first_name VARCHAR(100) NOT NULL,
-  last_name VARCHAR(100) NOT NULL,
-  email VARCHAR(255) NOT NULL,
-  custom_attributes TEXT NOT NULL DEFAULT '{}',
-  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
-);
-
-CREATE TABLE tenant_schema_definitions (
-  id VARCHAR(64) PRIMARY KEY,
-  tenant_id VARCHAR(64) NOT NULL,
-  entity_name VARCHAR(50) NOT NULL,
-  json_schema TEXT NOT NULL,
-  version INT NOT NULL DEFAULT 1,
-  UNIQUE(tenant_id, entity_name)
-);
-```
-
-### Runtime Validation Contract (JSON Schema Draft 2020-12)
-Validate all inbound custom attribute payloads at runtime against the tenant's compiled JSON Schema before persisting mutations:
-
-```
-┌────────────────────────────────────────────────────────┐
-│ Dynamic Schema Validator Contract (Agnostic)           │
-├────────────────────────────────────────────────────────┤
-│ validateCustomAttributes(schemaDef, data):             │
-│   compiledValidator = compileJsonSchema(schemaDef)     │
-│   result = compiledValidator.validate(data)           │
-│   if !result.isValid:                                  │
-│     return Failure(ValidationError(result.errors))     │
-│   return Success(data)                                 │
-└────────────────────────────────────────────────────────┘
-```
-Supported natively by open-source engines in every major language (`valico` in Rust, `gojsonschema` in Go, `jsonschema` in Python, `networknt` in Java, `ajv` in Node).
-
----
-
-## 2. Meta-Schema Catalog for Virtual Custom Entities
-
-When tenants define completely custom entities/tables dynamically without deploying code:
-
-```sql
-CREATE TABLE tenant_entities (
-  id VARCHAR(64) PRIMARY KEY,
-  tenant_id VARCHAR(64) NOT NULL,
-  name VARCHAR(64) NOT NULL,
-  display_name VARCHAR(128) NOT NULL,
-  schema_definition TEXT NOT NULL,
-  UNIQUE(tenant_id, name)
-);
-
-CREATE TABLE tenant_records (
-  id VARCHAR(64) PRIMARY KEY,
-  tenant_id VARCHAR(64) NOT NULL,
-  entity_id VARCHAR(64) NOT NULL REFERENCES tenant_entities(id) ON DELETE CASCADE,
-  data TEXT NOT NULL DEFAULT '{}',
-  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
-);
-```
-
----
-
-## 3. Indexing Strategies for Dynamic Custom Attributes
-
-1. **Virtual / Generated Columns**: For high-throughput queried fields inside dynamic attributes, project them into virtual/generated columns and attach standard B-tree indexes:
-   ```sql
-   ALTER TABLE customers ADD COLUMN vat_number VARCHAR(64) 
-     GENERATED ALWAYS AS (custom_attributes->>'vat_number') STORED;
-   CREATE INDEX idx_customers_vat ON customers (tenant_id, vat_number);
-   ```
-2. **Functional / Expression Indexes**: Index specific nested attributes directly on engines that support expression indexes:
-   ```sql
-   CREATE INDEX idx_customers_po ON customers (tenant_id, ((custom_attributes->>'po_number')::text));
-   ```
-3. **Inverted Indexes**: Use generalized inverted indexing (e.g. GIN in PostgreSQL) for arbitrary key-value path searches.

package/docs/rules/tenant_pluggable_logic.md

@@ -1,59 +0,0 @@
-# Pluggable Multi-Tenant Business Logic & Workflows
-
-> **Core Mandate:** Eliminate `if-tenant` conditional branching via Strategy registries, Common Expression Language (CEL), durable workflow orchestration, and secure WebAssembly (Wasm) micro-sandboxes.
-
----
-
-## 1. Strategy Pattern & Dynamic Strategy Registry
-
-Encapsulate diverging tenant algorithms into discrete strategies conforming to a unified domain port:
-
-```
-┌────────────────────────────────────────────────────────┐
-│ Discount Strategy Port Contract                        │
-├────────────────────────────────────────────────────────┤
-│ calculateDiscount(order): Decimal                      │
-└────────────────────────────────────────────────────────┘
-```
-
-The application maintains an in-memory Strategy Registry resolving the active strategy based on `tenant.subscriptionTier` or custom tenant config:
-
-```
-StrategyRegistry.register("standard", StandardDiscountStrategy)
-StrategyRegistry.register("enterprise_vip", HighVolumeTierStrategy)
-
-strategy = StrategyRegistry.resolve(tenant.discountStrategyKey)
-discount = strategy.calculateDiscount(order)
-```
-
----
-
-## 2. Declarative Rule Evaluation: Common Expression Language (CEL)
-
-Allow tenants or administrators to configure dynamic conditional logic stored as declarative text or JSON without redeploying binaries. Standardize on **Common Expression Language (CEL)**:
-
-```cel
-// Example Tenant Rule Expression:
-order.total >= 500 && order.shipping_country == "US" && tenant.tier == "ENTERPRISE"
-```
-
-- **Memory-Safe & Non-Turing Complete**: Prevents infinite loops, recursion crashes, and side-effects.
-- **Polyglot Portability**: Native compilers and runtimes available across Go (`cel-go`), Rust (`cel-rust`), Python (`cel-python`), Java (`cel-java`), and TypeScript (`cel-js`).
-
----
-
-## 3. Durable Workflows & Orchestration (Temporal / BPMN 2.0)
-
-For tenants with diverging multi-step approval, fulfillment, or refund lifecycles:
-- **Durable Execution Engines**: Standardize on **Temporal.io** or **Camunda 8 / Zeebe (BPMN 2.0)**.
-- **Resilience Guarantees**: Workflows automatically persist state across node crashes, manage timeouts, execute automatic retries, and trigger compensation transactions (Saga pattern) across polyglot workers.
-- **Tenant Workflow Selection**: The domain routes entity state transitions to tenant-specific workflow IDs configured in database metadata.
-
----
-
-## 4. Secure Script Sandboxing: WebAssembly (Wasm / Extism)
-
-Never execute untrusted tenant strings via host runtime evaluation (`eval()`, dynamic reflection, or unshielded isolates).
-- **Universal Sandboxing with Extism / Wasmtime**: Tenants compile custom logic (in Rust, Go, Python, or TypeScript) to portable `.wasm` bytecode.
-- **Strict Execution Quotas**: Max 50ms CPU execution budget, max 16MB linear memory boundary.
-- **Complete Host Isolation**: Sandboxed instances possess zero access to host filesystem, network sockets, environment variables, or database connections unless explicitly passed via memory interfaces.