azcodr 1.0.0

package/docs/rules/database_integrity.md

@@ -0,0 +1,88 @@
+# 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. Invariants, DO's & DONT's
+
+### DO's:
+- **DO:** Include the canonical total audit fields (`createdAt`, `createdBy`, `updatedAt`, `updatedBy`, `deletedAt`, `deletedBy`) on every mutable entity model.
+- **DO:** Populate `createdBy`, `updatedBy`, and `deletedBy` from the verified session actor (`req.user.id`), falling back explicitly to `'SYSTEM'` only for background daemons or public bootstrap.
+- **DO:** Default foreign keys to `RESTRICT` for root aggregates and financial ledgers to prevent accidental cascading data loss.
+- **DO:** Enforce foreign key validation in use cases before persistence, returning RFC 7807 problem details if referenced records do not exist.
+- **DO:** Render foreign key associations using relational selectors (`shadcn/ui` `<Select>`) showing human-readable business metadata (names, labels, numbers, emails).
+- **DO:** Ensure every entity/feature implements full lifecycle CRUD (Create, Read/Detail, Update/Status Transition, Delete/Archive) before considering it complete.
+- **DO:** Filter active records with `WHERE deleted_at IS NULL` and pair uniqueness with partial indexes (`WHERE deleted_at IS NULL`).
+
+### DONT's:
+- **DONT:** Never create a database table or entity without `createdAt` and `createdBy`.
+- **DONT:** Never omit `updatedBy` or `deletedBy` on mutable tables. Every mutation and deletion must have an accountable actor.
+- **DONT:** Never expose raw string text inputs for foreign key identifiers in the user interface.
+- **DONT:** Never consider a feature complete if it only implements creation or listing without update, transition, or deletion capabilities.
+- **DONT:** Never allow cascading deletes on master entities with dependent transactional history.

package/docs/rules/database_migrations.md

@@ -0,0 +1,41 @@
+# 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_operations.md

@@ -0,0 +1,27 @@
+# Database Operations, PITR & Least-Privilege Roles
+
+> **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.
+
+---
+
+## 1. High Availability, Backups & Disaster Recovery (DR)
+
+- **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.
+
+---
+
+## 2. Table Maintenance & Bloat Defragmentation
+
+- **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.
+
+---
+
+## 3. Least-Privilege Role Partitioning & Audit Trails
+
+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.

package/docs/rules/database_performance.md

@@ -0,0 +1,44 @@
+# 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

@@ -0,0 +1,81 @@
+# 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/design_patterns.md

@@ -0,0 +1,40 @@
+# Modern Design Patterns & Result Pattern
+
+> **Core Mandate:** Enforce composition over inheritance, wrap third-party boundaries in project-owned adapters, and model domain errors with explicit Result types instead of untyped exceptions.
+
+---
+
+## 1. Structural & Creational Patterns
+
+- **Adapter Pattern (Hexagonal Boundary)**: Wrap all external libraries, database drivers, cloud SDKs, and third-party APIs in project-owned adapter interfaces. *Rule: Only mock types you own.*
+- **Factory Method**: Encapsulate complex collaborator instantiation (e.g. tenant-specific payment gateways or notification dispatchers) behind factory functions.
+- **Facade Pattern**: Expose a unified, simplified interface to complex underlying multi-service subsystems.
+- **Decorator / Middleware**: Compose cross-cutting concerns (observability, authentication, tenant context resolution, rate limiting) via middleware pipelines.
+
+---
+
+## 2. Behavioral Patterns & Explicit Result Types
+
+- **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]]              │
+└────────────────────────────────────────────────────────┘
+```
+
+Domain services must return explicit Result types, compelling callers to handle failure branches deterministically.
+
+---
+
+## 3. GoF 23 Patterns Catalog
+
+For reference implementations of all 23 Gang of Four patterns across OOP and functional paradigms, consult [docs/rules/gof_design_patterns_reference.md](./gof_design_patterns_reference.md).

package/docs/rules/devsecops.md

@@ -0,0 +1,33 @@
+# 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/domain_driven_design.md

@@ -0,0 +1,84 @@
+# Domain-Driven Design (DDD) & Ubiquitous Language
+
+> **Core Mandate:** Establish unambiguous Ubiquitous Language definitions, isolate Bounded Contexts, guarantee Domain-Code Language Agreement across all architectural layers, and separate Value Objects, Entities, and Aggregates.
+
+---
+
+## 1. Domain-Code Language Agreement
+
+The fundamental premise of Domain-Driven Design (Eric Evans) is that **the code is the model, and the model is the code**. Any divergence between the mental model of domain experts and the source code is called **Linguistic Drift**.
+
+### Principles of Linguistic Alignment
+1. **Zero Synonyms (The Single Name Rule)**: Every domain concept has exactly one authoritative term. Synonyms (e.g. `Client` vs `User`, `Account` vs `Organization`, `Contract` vs `Agreement`) are strictly forbidden across code, tests, and user interfaces.
+2. **Eliminate Technical Jargon from Domain Core**: Domain models must not leak technical implementation terms (e.g. `UserRecord`, `TenantRow`, `DataDTO`, `IsActiveFlag`). The domain language must be pure business vocabulary.
+3. **Contextual Isolation**: When a single English word has multiple meanings across business units, split the terms or isolate them within dedicated Bounded Contexts:
+   - *Example*: In multi-tenant infrastructure, a system isolation boundary is an **Organization** / **Tenant Workspace**. In application operations, a participant is a **Member**, **User**, or **Customer**. Using "Tenant" for both creates semantic ambiguity and catastrophic bugs.
+
+---
+
+## 2. Living Ubiquitous Language Glossary
+
+Every project must maintain an authoritative, version-controlled **Living Ubiquitous Language Glossary** at [`docs/knowledge/ubiquitous_language.md`](../knowledge/ubiquitous_language.md).
+
+### Structure of a Glossary Entry
+Each entry must define:
+- **Canonical Term**: The agreed domain name.
+- **Definition**: The business meaning agreed with stakeholders.
+- **Bounded Context**: The domain subsystem where this definition holds authority.
+- **Forbidden Synonyms**: Banned terms that must never appear in code, schemas, or UI.
+- **Code Representations**: Exact class, type, interface, and database table names.
+
+---
+
+## 3. Automated Enforcement & Linters
+
+To prevent linguistic drift over time, teams must employ mechanical enforcement:
+
+### 1. Static Analysis / Linter Rules
+Configure custom linter rules (e.g. ESLint `id-denylist` or custom AST rules) to forbid banned synonyms in identifiers:
+```json
+{
+  "rules": {
+    "id-denylist": ["error", "client_user", "account_org", "raw_data_dto"]
+  }
+}
+```
+
+### 2. Branded Nominal Types
+Prevent "Primitive Obsession" where generic strings or IDs are conflated across domain boundaries:
+```typescript
+export type UserId = string & { readonly __brand: unique symbol };
+export type OrganizationId = string & { readonly __brand: unique symbol };
+export type OrderId = string & { readonly __brand: unique symbol };
+
+// The compiler prevents accidentally passing an OrganizationId where a UserId is required:
+function assignUserToOrder(orderId: OrderId, userId: UserId): void { ... }
+```
+
+### 3. Living Executable Specifications (Gherkin BDD)
+Acceptance criteria must be written strictly in Ubiquitous Language, serving as executable contracts that verify domain terminology in automated test runners.
+
+---
+
+## 4. Tactical Patterns & Invariants
+
+1. **Entities**: Objects defined by identity that persists across state changes (e.g. `User`, `Order`, `Invoice`).
+2. **Value Objects**: Immutable objects defined strictly by their attributes with no identity (e.g. `Money`, `DateRange`, `EmailAddress`).
+3. **Aggregates & Aggregate Roots**: Clusters of domain objects treated as a single transactional consistency boundary. All mutations must pass through explicit methods on the Aggregate Root.
+4. **Anti-Corruption Layer (ACL)**: When integrating with third-party APIs or legacy systems that use different terminology, translate external payloads into the internal Ubiquitous Language at the boundary adapter before they enter the domain core.
+
+---
+
+## 5. Invariants (DO's & DONT's)
+
+### DO
+- **DO** use identical terminology in domain conversations, PRDs, code, database schemas, and user interfaces.
+- **DO** maintain an authoritative `ubiquitous_language.md` and treat it as a binding architectural contract.
+- **DO** use branded nominal types for IDs to catch cross-entity domain mixups at compile time.
+- **DO** translate foreign data structures at the perimeter using an Anti-Corruption Layer (ACL).
+
+### DONT
+- **DONT** use technical jargon (`dto`, `entity_row`, `table_item`) in domain business logic.
+- **DONT** allow competing synonyms for the same concept within the same Bounded Context.
+- **DONT** overload words with dual meanings across technical architecture and business domain.
+- **DONT** rename domain terms in code without updating the living glossary and recording an ADR.

package/docs/rules/domain_expertise.md

@@ -0,0 +1,42 @@
+# Domain Expertise, Capability Mapping & Business Invariants
+
+> **Core Mandate:** Decompose business domains into distinct capability boundaries, enforce business invariants strictly within Aggregate Roots, and protect living Ubiquitous Language.
+
+---
+
+## 1. Business Capability Mapping
+
+Structure enterprise business logic into three distinct capability tiers:
+1. **Core Capabilities**: Proprietary value drivers and differentiators (e.g. specialized tenant workflow engines, dynamic pricing algorithms). Allocate 80% of architectural effort here.
+2. **Supporting Capabilities**: Business functions specific to the domain but not competitive differentiators (e.g. order tracking, invoice rendering).
+3. **Generic Capabilities**: Standard commoditized software (e.g. authentication, audit logging, email transport). Rely exclusively on standard open-source libraries.
+
+---
+
+## 2. Invariant Protection within Aggregate Roots
+
+- **Zero Anemic Domain Models**: Domain entities must encapsulate state and validation. Do not expose public setters that allow outside code to corrupt business rules.
+- **Aggregate Root Gatekeeper**: All mutations that modify entity state or related child entities must pass through explicit methods on the Aggregate Root that assert invariants before committing state:
+  ```typescript
+  export class OrderAggregate {
+    private constructor(private order: OrderState) {}
+
+    submit(): Result<void, DomainError> {
+      if (this.order.items.length === 0) {
+        return err(new DomainError('Cannot submit empty order'));
+      }
+      if (this.order.status !== 'DRAFT') {
+        return err(new DomainError('Order already submitted'));
+      }
+      this.order.status = 'SUBMITTED';
+      return ok(undefined);
+    }
+  }
+  ```
+
+---
+
+## 3. Living Ubiquitous Language Dictionary
+
+- Maintain strict terminology discipline across models, database tables, API schemas, and frontend labels.
+- When domain experts or users establish a term, document it immediately and eliminate all competing synonyms across the codebase.

package/docs/rules/error_handling.md

@@ -0,0 +1,39 @@
+# Error Handling, Request Tracing & Schema Validation
+
+> **Core Mandate:** Enforce fail-fast schema validation at startup, structured OpenTelemetry/JSON request tracing, and standardized RFC 7807 / REST error envelopes.
+
+---
+
+## 1. Fail-Fast Configuration & Environment Validation
+
+Validate all configuration parameters and environment variables at process bootstrap using strict schema definitions before initializing servers or database connection pools:
+- **Immediate Process Termination**: Halt startup immediately with non-zero exit code if any mandatory variable is missing, malformed, or insecure.
+- **Strict Prohibition of Secret Fallbacks**: Never provide default fallback values for production secrets, database credentials, or private cryptographic keys.
+
+---
+
+## 2. Structured Tracing & Correlation (OpenTelemetry / W3C)
+
+- **Standardized Correlation IDs**: Bind a unique `x-request-id` (UUID v4) and W3C `traceparent` to every inbound request. Forward these identifiers across all downstream RPC calls, database queries, and async broker messages.
+- **Structured JSON Logging**: Format all application logs in structured JSON conforming to OpenTelemetry Resource Schemas or Elastic Common Schema (ECS) (`timestamp`, `severity`, `trace_id`, `span_id`, `request_id`, `tenant_id`, `message`).
+
+---
+
+## 3. Standardized Error Response Envelope (RFC 7807)
+
+Enforce a uniform error envelope across all external HTTP/REST endpoints conforming to the **RFC 7807 Problem Details** standard:
+
+```json
+{
+  "type": "https://api.domain.com/errors/RESOURCE_LOCKED",
+  "title": "Resource Conflict",
+  "status": 409,
+  "detail": "The requested order is currently undergoing payment processing.",
+  "instance": "/v1/orders/123",
+  "code": "ORDER_LOCKED",
+  "requestId": "550e8400-e29b-41d4-a716-446655440000",
+  "invalidParams": []
+}
+```
+
+- **Production Masking Invariant**: Strictly mask internal database error codes, raw SQL queries, file system paths, and stack traces from external client responses in non-local environments.

package/docs/rules/feature_flags.md

@@ -0,0 +1,42 @@
+# Feature Flagging & OpenFeature Standards
+
+> **Core Mandate:** Enforce the open-source OpenFeature standard, evaluate flags dynamically via Flipt or Unleash backends, and maintain clean flag lifecycles.
+
+---
+
+## 1. OpenFeature Standard Architecture
+
+Utilize open-source `@openfeature/server-sdk` with open-source providers (Flipt or Unleash):
+
+```typescript
+import { OpenFeature, Client } from '@openfeature/server-sdk';
+import { FliptProvider } from '@openfeature/flipt-provider';
+
+OpenFeature.setProvider(new FliptProvider({ url: process.env.FLIPT_URL }));
+export const featureClient: Client = OpenFeature.getClient();
+```
+
+---
+
+## 2. Contextual Tenant Targeting
+
+Pass tenant identity and contextual attributes during evaluation:
+
+```typescript
+const isEnabled = await featureClient.getBooleanValue(
+  'advanced-analytics',
+  false,
+  {
+    targetingKey: user.id,
+    tenantId: user.tenantId,
+    tier: tenant.subscriptionTier
+  }
+);
+```
+
+---
+
+## 3. 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/gof_design_patterns_reference.md

@@ -0,0 +1,70 @@
+# Gang of Four (GoF) Design Patterns — Universal Enterprise Reference
+
+> **Core Mandate:** Master catalog of all 23 Gang of Four design patterns mapped to real-world domain architectures across OOP and functional polyglot systems.
+
+---
+
+## 1. Creational Patterns (5 Patterns)
+
+Creational patterns abstract the instantiation process, making systems independent of how objects are created and composed.
+
+1. **Factory Method**: Define an interface for creating an object, but let subclasses or factory functions decide which class to instantiate.
+   - *Use Case:* Tenant-specific payment gateway instantiation (`StripeAdapter` vs `PayPalAdapter`).
+2. **Abstract Factory**: Provide an interface for creating families of related or dependent objects without specifying concrete classes.
+   - *Use Case:* Multi-cloud storage factories creating matching `FileUploader`, `FileDownloader`, and `PresignedUrlGenerator` for S3, GCS, or MinIO.
+3. **Builder**: Separate the construction of a complex object from its representation, allowing the same construction process to create different representations.
+   - *Use Case:* Fluent query builders, complex report generators, or test data builders (`OrderBuilder.withItems(...).build()`).
+4. **Prototype**: Specify the kinds of objects to create using a prototypical instance, creating new objects by cloning this prototype.
+   - *Use Case:* Fast cloning of default tenant configuration templates without querying storage.
+5. **Singleton (DI-Scoped)**: Ensure a class has only one instance and provide a global point of access.
+   - *Rule:* Avoid global static singletons (causes test coupling). Enforce singleton lifecycle strictly through Dependency Injection (DI) containers.
+
+---
+
+## 2. Structural Patterns (7 Patterns)
+
+Structural patterns deal with object composition and relationships, ensuring subsystems remain decoupled and flexible.
+
+6. **Adapter (Mandatory)**: Convert the interface of a class into another interface clients expect.
+   - *Use Case:* Wrapping 3rd-party SDKs, storage drivers, and external network clients in application-owned interfaces. *Rule: Only mock types you own.*
+7. **Bridge**: Decouple an abstraction from its implementation so the two can vary independently.
+   - *Use Case:* Decoupling notification abstractions (`UrgentNotification`, `BatchNotification`) from delivery channels (`EmailChannel`, `SlackChannel`).
+8. **Composite**: Compose objects into tree structures to represent part-whole hierarchies.
+   - *Use Case:* Nested RBAC permission trees or hierarchical menu navigation systems.
+9. **Decorator**: Attach additional responsibilities to an object dynamically as a flexible alternative to subclassing.
+   - *Use Case:* Wrapping repository methods with distributed caching, OpenTelemetry tracing, or metrics logging.
+10. **Facade**: Provide a unified, high-level interface to a complex set of interfaces in a subsystem.
+    - *Use Case:* Checkout facade orchestrating inventory verification, payment processing, invoice generation, and email notification.
+11. **Flyweight**: Use sharing to support large numbers of fine-grained objects efficiently.
+    - *Use Case:* In-memory sharing of immutable tenant metadata and shared system role permission definitions.
+12. **Proxy**: Provide a surrogate or placeholder for another object to control access to it.
+    - *Use Case:* Lazy-loading database relations, virtual proxies for large assets, or tenant-scoped connection proxies.
+
+---
+
+## 3. Behavioral Patterns (11 Patterns)
+
+Behavioral patterns characterize the ways in which classes or objects interact and distribute responsibility.
+
+13. **Chain of Responsibility**: Pass requests along a chain of handlers until a handler processes it or the chain ends.
+    - *Use Case:* Inbound gateway middleware pipelines (Authentication ➔ TenantResolution ➔ RateLimiting ➔ Controller).
+14. **Command**: Encapsulate a request as an object, thereby letting you parameterize clients with different requests, queue or log requests, and support undo.
+    - *Use Case:* Asynchronous job queues, transactional audit commands, CQRS command handlers.
+15. **Interpreter**: Given a language, define a representation for its grammar along with an interpreter that uses the representation to interpret sentences.
+    - *Use Case:* Custom search filter parsers (`status:active AND tier:pro`) or rule engine expression evaluation.
+16. **Iterator**: Provide a way to access the elements of an aggregate object sequentially without exposing its underlying representation.
+    - *Use Case:* Async iterators streaming large database cursor result sets or reading multi-part upload chunks.
+17. **Mediator**: Define an object that encapsulates how a set of objects interact, preventing direct coupling between them.
+    - *Use Case:* In-memory event dispatcher mediating communication between decoupled domain services.
+18. **Memento**: Without violating encapsulation, capture and externalize an object's internal state so the object can be restored to this state later.
+    - *Use Case:* Audit trail snapshots recording `before` and `after` states for rollback capabilities.
+19. **Observer**: Define a one-to-many dependency between objects so that when one object changes state, all its dependents are notified automatically.
+    - *Use Case:* Domain Event buses (`UserRegisteredEvent`, `PaymentFailedEvent`) invoking multiple listeners.
+20. **State**: Allow an object to alter its behavior when its internal state changes, appearing as if it changed its class.
+    - *Use Case:* Subscription lifecycles (`TrialState` ➔ `ActiveState` ➔ `PastDueState` ➔ `CanceledState`) where allowed actions change dynamically.
+21. **Strategy**: Define a family of algorithms, encapsulate each one, and make them interchangeable at runtime.
+    - *Use Case:* Dynamic fee calculation, tenant-specific password complexity policies, or feature flag evaluation providers.
+22. **Template Method**: Define the skeleton of an algorithm in an operation, deferring some steps to subclasses.
+    - *Use Case:* Base ETL or data import pipelines with fixed steps (Extract ➔ Validate ➔ Transform ➔ Persist) where subclasses define validation.
+23. **Visitor**: Represent an operation to be performed on the elements of an object structure, defining a new operation without changing the classes of the elements.
+    - *Use Case:* Document export engines traversing an AST of content blocks to generate HTML, Markdown, or PDF.