azcodr 1.2.2 → 1.4.0

package/docs/rules/cqrs.md

@@ -0,0 +1,203 @@
+# CQRS (Command Query Responsibility Segregation) & YAGNI Defense
+
+> **Core Mandate:** Enforce evolutionary graduation across the CQRS spectrum, protect against premature abstraction (YAGNI), bound CQRS strictly to high-contention subdomains, decouple write aggregates from read projections, and prevent eventual consistency hazards.
+
+---
+
+## 1. The YAGNI Defense: Default Architecture vs. CQRS
+
+CQRS separates the data model used for state mutations (**Commands**) from the data model used for read operations (**Queries**). While powerful, **CQRS is one of the most frequently over-engineered patterns in modern software**. 
+
+```mermaid
+flowchart LR
+    subgraph DefaultModel["Default Single-Model (CRUD) - Start Here"]
+        D1["• 1 Unified Data Schema (ACID)<br/>• Immediate Strong Consistency<br/>• Zero Projection Infrastructure<br/>• Minimal Mental Overhead"]
+    end
+
+    subgraph DistributedCQRS["Distributed CQRS (Level 3) - Graduate on Proof"]
+        C1["• Dual Schemas & Dual Databases<br/>• Eventual Consistency & Lag<br/>• Outbox, Message Bus, CDC Workers<br/>• Projection Versioning & Replays"]
+    end
+
+    DefaultModel -.->|Graduate ONLY on high read-write asymmetry or SLA breaches| DistributedCQRS
+```
+
+### The YAGNI Rule for CQRS
+1. **Default to Single Model / Single Database**: Start every application, microservice, or bounded context with a standard single data model (Hexagonal/DDD) where repositories handle both reads and writes.
+2. **Never Use CQRS as Top-Level System Architecture**: CQRS must never be applied globally across an entire system. It is strictly a bounded-context tactical pattern. Generic subdomains (Auth, Settings, Billing, Organizations) must remain simple transactional CRUD.
+3. **Explicit Graduation Tipping Points**: Do not introduce segregated read databases or asynchronous projections until empirical metrics prove that a unified relational model cannot meet operational constraints:
+   - **Read/Write Asymmetry**: Read volume exceeds writes by > 50:1, and heavy read queries cause lock contention that starves transactional write operations.
+   - **Impedance Mismatch**: Constructing UI views requires joining 10+ relational tables across multiple consistency boundaries, causing query latency to violate SLAs (> 500ms).
+   - **Polyglot Query Topology**: Complex full-text search, spatial filtering, or columnar aggregation fundamentally requires specialized search engines (Elasticsearch, Meilisearch, ClickHouse) that cannot act as the primary write store.
+
+---
+
+## 2. The 4-Tier Evolutionary CQRS Spectrum
+
+Rather than treating CQRS as a binary switch, systems must graduate incrementally across four explicit architectural tiers:
+
+```mermaid
+flowchart TD
+    L0["Level 0: Method CQS (Bertrand Meyer)<br/>Functions either mutate state or return data; zero architectural overhead. Always mandatory."]
+    L1["Level 1: Segregated Handlers in Code (Single DB, Single Schema)<br/>Command Handlers load Aggregates; Query Handlers bypass domain model for flat DTOs."]
+    L2["Level 2: Segregated Read Models / Materialized Views (Single DB)<br/>Read queries query indexed SQL views or JSON cache tables populated synchronously via ACID transactions."]
+    L3["Level 3: Polyglot Persistence & Asynchronous Projections (Multi-Store)<br/>Write DB (Postgres) + Read DB (Elastic/Redis). Synchronized asynchronously via Transactional Outbox + CDC."]
+
+    L0 --> L1 --> L2 --> L3
+```
+
+### Level 0: Method-Level CQS (Command-Query Separation)
+- Mandatory across all codebases (see [`docs/rules/clean_code.md`](./clean_code.md)).
+- Any function that modifies state must return `void` or a `Result<void, DomainError>`. It must never return the mutated entity.
+- Any function that queries state must be pure and cause zero observable side-effects.
+
+### Level 1: Segregated Handlers in Code (Single DB, Single Schema)
+- When domain aggregates become rich with business logic, hydrating deep aggregate graphs (with children, value objects, and invariant checks) simply to render a flat summary list is wasteful.
+- **Commands**: Flow through `CommandHandler` ➔ loads `AggregateRoot` from `Repository` ➔ executes domain methods ➔ commits transaction.
+- **Queries**: Flow through `QueryHandler` ➔ bypasses domain repositories ➔ issues direct projection queries (SQL `SELECT` or ORM raw select) ➔ returns read-only `DTO`.
+- *Zero distributed complexity; 100% ACID consistency.*
+
+### Level 2: Segregated Read Models (Single DB, Synchronous)
+- When read queries require expensive aggregations or multi-table joins, create dedicated read tables, database views, or PostgreSQL JSONB projection columns in the same database.
+- Projections are updated **synchronously within the same database transaction** as the command mutation (or via database triggers).
+- *Guarantees immediate read-your-own-writes consistency without distributed outbox pipelines.*
+
+### Level 3: Polyglot Persistence & Asynchronous Projections
+- Writes commit to the transactional primary database (e.g. PostgreSQL).
+- Events are emitted via the Transactional Outbox pattern and streamed to secondary read stores (e.g. Elasticsearch for search, Redis for caches, ClickHouse for telemetry).
+- *Requires strict handling of eventual consistency, projection replay, and outbox delivery.*
+
+---
+
+## 3. Tactical Implementation Patterns (TypeScript)
+
+### 1. Command Side: Enforcing Invariants via Aggregates
+Commands express user intent, encapsulate validation, and mutate state through the Aggregate Root:
+
+```typescript
+// commands/create_order.command.ts
+export interface CreateOrderCommand {
+  readonly orderId: string;
+  readonly customerId: string;
+  readonly items: ReadonlyArray<{ productId: string; quantity: number; unitPriceCents: number }>;
+}
+
+// handlers/create_order.handler.ts
+export class CreateOrderCommandHandler {
+  constructor(
+    private readonly orderRepo: OrderRepositoryPort,
+    private readonly outbox: TransactionalOutboxPort
+  ) {}
+
+  async execute(command: CreateOrderCommand): Promise<Result<void, OrderDomainError>> {
+    // 1. Load or instantiate Aggregate Root
+    const orderResult = OrderAggregate.create({
+      id: command.orderId,
+      customerId: command.customerId,
+      items: command.items
+    });
+
+    if (orderResult.isFailure) {
+      return Result.fail(orderResult.error);
+    }
+
+    const order = orderResult.value;
+
+    // 2. Commit aggregate mutation and outbox event atomically in 1 transaction
+    await this.orderRepo.transaction(async (tx) => {
+      await this.orderRepo.save(order, tx);
+      for (const event of order.pullDomainEvents()) {
+        await this.outbox.stageEvent(event, tx);
+      }
+    });
+
+    return Result.ok();
+  }
+}
+```
+
+### 2. Query Side: Fast Direct Projection DTOs
+Queries bypass domain entities and ORM aggregate hydration entirely, executing direct, index-optimized reads:
+
+```typescript
+// queries/get_customer_orders.query.ts
+export interface GetCustomerOrdersQuery {
+  readonly customerId: string;
+  readonly limit: number;
+  readonly cursor?: string;
+}
+
+export interface CustomerOrderSummaryDTO {
+  readonly orderId: string;
+  readonly totalCents: number;
+  readonly status: string;
+  readonly itemCount: number;
+  readonly createdAt: string;
+}
+
+// handlers/get_customer_orders.handler.ts
+export class GetCustomerOrdersQueryHandler {
+  constructor(private readonly db: ReadDatabaseClient) {}
+
+  async execute(query: GetCustomerOrdersQuery): Promise<CustomerOrderSummaryDTO[]> {
+    // Direct SQL projection - zero domain aggregate hydration overhead
+    return await this.db.query<CustomerOrderSummaryDTO>(
+      `SELECT order_id as "orderId", total_cents as "totalCents", 
+              status, item_count as "itemCount", created_at as "createdAt"
+       FROM order_summaries_view
+       WHERE customer_id = $1
+       ORDER BY created_at DESC
+       LIMIT $2`,
+      [query.customerId, query.limit]
+    );
+  }
+}
+```
+
+---
+
+## 4. Asynchronous Projection Invariants (Level 3 CQRS)
+
+When graduating to Level 3 (asynchronous read stores), you must prevent data corruption, drift, and race conditions:
+
+### 1. Zero Dual-Writes (Strict Outbox Mandate)
+Never write to the command database and then publish to a message broker (RabbitMQ/Kafka) in two independent operations. Network failure between the two operations corrupts read models. Always use the **Transactional Outbox Pattern** (see [`docs/rules/database_design.md`](./database_design.md)).
+
+### 2. Monotonic Sequence & Idempotent Projectors
+Every domain event must carry an aggregate version number. Read projectors must discard duplicate or out-of-order events:
+```typescript
+export async function projectOrderUpdated(event: OrderUpdatedEvent, db: ReadDb): Promise<void> {
+  // Idempotent upsert guarded by monotonic version sequence
+  await db.query(
+    `UPDATE order_read_models 
+     SET status = $1, version = $2, updated_at = $3
+     WHERE order_id = $4 AND version < $2`,
+    [event.newStatus, event.version, event.occurredAt, event.orderId]
+  );
+}
+```
+
+---
+
+## 5. Defending Read-Your-Own-Writes Consistency
+
+The biggest hazard of asynchronous CQRS is **eventual consistency lag**: a user submits a mutation (e.g. updating their display name), receives an HTTP `200 OK`, gets redirected to their profile, but still sees their old name because the background projection worker is lagging.
+
+### Strategies to Eliminate User-Perceived Lag
+1. **Optimistic UI Updates**: The frontend immediately updates the client cache with the submitted values upon HTTP 200 response, without refetching from the query API.
+2. **Monotonic Version Headers**:
+   - The command response returns the new entity version: `ETag: "v14"`.
+   - Subsequent query requests include `If-None-Match: "v14"` or `X-Min-Version: 14`.
+   - If the read projection has not caught up to `v14`, the query service waits (up to 500ms) or falls back to querying the primary write database.
+3. **Session Read-Model Pinning**: Direct read requests from the mutating user's session to the primary database for 5 seconds after a command execution, while general traffic continues reading from the read replica.
+
+---
+
+## 6. Gotchas & Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Mandated Correction |
+|---|---|---|
+| **CQRS as Default Architecture** | Multiplies boilerplate, schemas, and cognitive load 3x on simple applications (YAGNI violation). | Default to Single Model / Single Database. Graduate only on measured bottlenecks. |
+| **Conflating CQRS with Event Sourcing** | Event Sourcing stores all state as event streams; CQRS only separates read and write pathways. ES adds severe schema migration complexity. | Implement CQRS with standard relational state. Only add Event Sourcing if the business requires legal/temporal audit ledgers. |
+| **Leaking Entities into Queries** | Hydrating full Domain Aggregates inside Query Handlers causes severe N+1 query cascades and memory bloat. | Query Handlers must bypass entities and return flat, serializable DTOs directly from the database. |
+| **Dual-Write Projections** | Emitting HTTP calls or message queue pushes directly inside mutation services causes silent sync failures. | Write events to a local `outbox` table in the same DB transaction as the aggregate state change. |
+| **CRUD Queries via Aggregate Roots** | Loading an entire Aggregate Root just to read 2 fields creates unnecessary lock contention and memory footprint. | Use direct projection queries (Level 1 CQRS) for read-only flows. |

package/docs/rules/database_design.md

@@ -0,0 +1,125 @@
+# Database Design, Relational Integrity & Transactions
+
+> **Core Mandate:** Enforce relational constraints at the database engine level (FKs, CHECKs, EXCLUDEs), the Canonical 6 Total Audit Fields, partial soft-delete indexes, ACID transactional boundaries, and the Transactional Outbox pattern.
+
+---
+
+## 1. Relational Integrity & Engine-Level Constraints
+
+Data integrity must be enforced by the relational database engine, not delegated exclusively to application code:
+
+```mermaid
+flowchart TD
+    App["Application Layer<br/>Validates DTOs (Zod / Pydantic / Bean Validation)"] --> DB["Database Engine (Final Arbiter of Truth)"]
+    subgraph EngineRules["Engine Constraints"]
+        DB --> FK["FOREIGN KEY<br/>Referential Integrity"]
+        DB --> CHECK["CHECK<br/>Domain Invariants & Ranges"]
+        DB --> EXCLUDE["EXCLUDE USING gist<br/>Temporal Non-Overlaps"]
+        DB --> PARTIAL["Partial Unique Indexes<br/>UNIQUE ... WHERE deleted_at IS NULL"]
+    end
+```
+
+### Invariants:
+1. **Mandatory Foreign Keys**: Every relational association must define an explicit foreign key constraint with explicit `ON DELETE` semantics (`ON DELETE RESTRICT` or `ON DELETE CASCADE`).
+2. **Domain `CHECK` Constraints**: Enforce domain value ranges at the schema level:
+   ```sql
+   ALTER TABLE orders ADD CONSTRAINT check_positive_amount CHECK (total_amount >= 0);
+   ALTER TABLE users ADD CONSTRAINT check_valid_role CHECK (role IN ('ADMIN', 'OPERATOR', 'MEMBER'));
+   ```
+3. **Temporal Non-Overlap (`EXCLUDE`)**: Scheduling, booking, or reservation systems must prevent double-booking using PostgreSQL range exclusion constraints:
+   ```sql
+   ALTER TABLE bookings ADD CONSTRAINT no_overlapping_reservations
+     EXCLUDE USING gist (room_id WITH =, reservation_period WITH &&);
+   ```
+
+---
+
+## 2. The Canonical 6 Total Audit Fields
+
+Every mutable stateful entity in the database must implement the **Canonical 6 Total Audit Fields** to guarantee complete traceability for compliance and security audits:
+
+```sql
+CREATE TABLE resources (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id UUID NOT NULL,
+  name VARCHAR(255) NOT NULL,
+  
+  -- The Canonical 6 Total Audit Fields
+  created_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
+  created_by UUID NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
+  updated_by UUID NOT NULL,
+  deleted_at TIMESTAMPTZ,
+  deleted_by UUID
+);
+```
+
+### Rules & Append-Only Exception:
+- **Mutable Tables:** All 6 fields are mandatory. Application repositories must automatically populate `createdBy`/`updatedBy` from the ambient authenticated user context.
+- **Append-Only Event / Ledger Tables:** Immutable financial ledgers, audit logs, and domain events omit `updated_at`, `updated_by`, `deleted_at`, and `deleted_by` (immutable rows are never updated or deleted).
+
+---
+
+## 3. Soft-Delete Invariants & Partial Unique Indexes
+
+When implementing soft-delete (`deleted_at IS NOT NULL`):
+1. **Never Use Unfiltered Unique Constraints**: A standard `UNIQUE(slug)` constraint prevents creating a new record with the same slug after deleting an old record.
+2. **Mandatory Partial Unique Index**:
+   ```sql
+   -- Correct: Allows reusing slug after soft-deletion
+   CREATE UNIQUE INDEX idx_resources_tenant_slug_active 
+     ON resources (tenant_id, slug) 
+     WHERE deleted_at IS NULL;
+   ```
+3. **Soft-Delete Query Filtering**: All read queries must filter `WHERE deleted_at IS NULL` unless explicitly requesting archived records.
+
+---
+
+## 4. ACID Transactions & Isolation Levels
+
+Every operation mutating multiple database rows or coordinating interrelated aggregates must execute within an explicit **ACID Transaction**:
+
+### Transaction Guidelines:
+- **Single Aggregate Transactions**: Strive to keep transactions bounded to a single aggregate root.
+- **Isolation Level Selection**:
+  - `READ COMMITTED` (Default): Acceptable for standard CRUD operations.
+  - `REPEATABLE READ` / `SERIALIZABLE`: Mandatory for financial ledger balances, inventory decrements, and ticket allocations where phantom reads cause double-spending.
+- **Defensive Timeouts**: Transactions must never run indefinitely. Always set a defensive statement and transaction timeout:
+  ```sql
+  SET LOCAL statement_timeout = '5s';
+  SET LOCAL idle_in_transaction_session_timeout = '10s';
+  ```
+
+---
+
+## 5. The Transactional Outbox Pattern (Dual-Write Defense)
+
+Never execute a database write and a message broker publish sequentially in application code. If the network fails between the two operations, the system enters an inconsistent, corrupted state (**The Dual-Write Anti-Pattern**).
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Caller
+    participant App as Application Service
+    participant DB as PostgreSQL Database
+    participant Relay as CDC Relay / Worker
+    participant Broker as Message Broker (Kafka/SQS)
+
+    Caller->>App: Execute Command
+    activate App
+    Note over App,DB: Atomic ACID Transaction
+    App->>DB: 1. Mutate Domain State (UPDATE accounts...)
+    App->>DB: 2. Insert Outbox Event (INSERT INTO outbox_events...)
+    App->>DB: COMMIT
+    App-->>Caller: Success Response
+    deactivate App
+
+    Note over Relay,Broker: Asynchronous Processing
+    Relay->>DB: 3. Read unpublished outbox_events (CDC / Polling)
+    Relay->>Broker: 4. Publish Event to Broker
+    Relay->>DB: 5. Mark Event Published / Purge
+```
+
+### Outbox Invariants:
+1. **Atomic Ingestion**: Domain entity mutation and event insertion must share the identical database transaction.
+2. **Guaranteed At-Least-Once Delivery**: The outbox relay guarantees delivery to consumers; consumers must implement idempotency.

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.