azcodr 1.5.2 → 2.0.0

package/docs/rules/devops_ci_cd.md

@@ -1,76 +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.
+# 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

@@ -1,122 +1,122 @@
-# Domain-Driven Design (DDD) & Ubiquitous Language
-
-> **Core Mandate:** Separate Problem Space from Solution Space, establish unambiguous Ubiquitous Language definitions, isolate Bounded Contexts, guarantee Domain-Code Language Agreement, and protect Aggregate invariants.
-
----
-
-## 1. Problem Space vs. Solution Space (Evans & Vernon)
-
-Software engineering fails when teams jump directly into the **Solution Space** (choosing languages, frameworks, databases, and microservices) before fully defining the **Problem Space**.
-
-```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.**
-- **The Solution Space (The Accidents):** Concerns *how* the system is realized. Runtimes, programming languages (C, Rust, TS, Go, Java), and storage engines are **emergent outputs** derived strictly from Problem Space constraints.
-- **The Golden Hammer Anti-Pattern:** Selecting tools (e.g., "Let's use Next.js and PostgreSQL") before mapping problem constraints forces the domain to fit the tool, creating massive accidental complexity.
-
-### Strategic Subdomain & Capability Mapping
-Structure enterprise business capabilities into three distinct tiers:
-1. **Core Subdomain / Capabilities**: Proprietary value drivers and business differentiators (e.g. specialized workflow engines, dynamic pricing algorithms). Allocate 80% of architectural effort here.
-2. **Supporting Subdomain / Capabilities**: Business functions specific to the domain but not competitive differentiators (e.g. order tracking, invoice rendering).
-3. **Generic Subdomain / Capabilities**: Standard commoditized software (e.g. authentication, audit logging, email transport). Rely exclusively on standard open-source libraries.
-
----
-
-## 2. 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.
-
----
-
-## 3. 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.
-
----
-
-## 4. 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.
-
----
-
-## 5. 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 that assert invariants before committing state:
-   - **Zero Anemic Domain Models**: Domain entities must encapsulate state and validation logic. Never expose public setters that allow outside code to corrupt business rules.
-   - **Aggregate Root Gatekeeper Pattern**:
-     ```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);
-       }
-     }
-     ```
-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. **Cross-Aggregate Coordination in Use Cases**: While an Aggregate Root guards its own internal invariants, business operations frequently span multiple aggregates (e.g. reserving an inventory item for an agreement). Application use cases or orchestrators must coordinate aggregate transitions atomically: asserting resource availability prior to state change, transitioning the constrained entity (e.g. `ALLOCATED`), and restoring state (`AVAILABLE`) upon cancellation, avoiding double-allocation race conditions without coupling aggregates directly.
+# Domain-Driven Design (DDD) & Ubiquitous Language
+
+> **Core Mandate:** Separate Problem Space from Solution Space, establish unambiguous Ubiquitous Language definitions, isolate Bounded Contexts, guarantee Domain-Code Language Agreement, and protect Aggregate invariants.
+
+---
+
+## 1. Problem Space vs. Solution Space (Evans & Vernon)
+
+Software engineering fails when teams jump directly into the **Solution Space** (choosing languages, frameworks, databases, and microservices) before fully defining the **Problem Space**.
+
+```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.**
+- **The Solution Space (The Accidents):** Concerns *how* the system is realized. Runtimes, programming languages (C, Rust, TS, Go, Java), and storage engines are **emergent outputs** derived strictly from Problem Space constraints.
+- **The Golden Hammer Anti-Pattern:** Selecting tools (e.g., "Let's use Next.js and PostgreSQL") before mapping problem constraints forces the domain to fit the tool, creating massive accidental complexity.
+
+### Strategic Subdomain & Capability Mapping
+Structure enterprise business capabilities into three distinct tiers:
+1. **Core Subdomain / Capabilities**: Proprietary value drivers and business differentiators (e.g. specialized workflow engines, dynamic pricing algorithms). Allocate 80% of architectural effort here.
+2. **Supporting Subdomain / Capabilities**: Business functions specific to the domain but not competitive differentiators (e.g. order tracking, invoice rendering).
+3. **Generic Subdomain / Capabilities**: Standard commoditized software (e.g. authentication, audit logging, email transport). Rely exclusively on standard open-source libraries.
+
+---
+
+## 2. 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.
+
+---
+
+## 3. 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.
+
+---
+
+## 4. 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.
+
+---
+
+## 5. 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 that assert invariants before committing state:
+   - **Zero Anemic Domain Models**: Domain entities must encapsulate state and validation logic. Never expose public setters that allow outside code to corrupt business rules.
+   - **Aggregate Root Gatekeeper Pattern**:
+     ```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);
+       }
+     }
+     ```
+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. **Cross-Aggregate Coordination in Use Cases**: While an Aggregate Root guards its own internal invariants, business operations frequently span multiple aggregates (e.g. reserving an inventory item for an agreement). Application use cases or orchestrators must coordinate aggregate transitions atomically: asserting resource availability prior to state change, transitioning the constrained entity (e.g. `ALLOCATED`), and restoring state (`AVAILABLE`) upon cancellation, avoiding double-allocation race conditions without coupling aggregates directly.

package/docs/rules/error_handling.md

@@ -1,52 +1,54 @@
-# Error Handling, Request Tracing & Schema Validation
-
-> **Core Mandate:** Enforce fail-fast schema validation at startup, structured OpenTelemetry/JSON request tracing, standardized RFC 7807 problem details, and an explicit canonical DomainError hierarchy.
-
----
-
-## 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.
-
----
-
-## 4. Canonical Domain Error Hierarchy & Type-Safe Narrowing
-
-- **Canonical DomainError Hierarchy**: Model operational domain failures using an explicit `DomainError` base class with canonical subclasses:
-  - `ValidationError` (maps to HTTP 400 / 422)
-  - `UnauthorizedError` (maps to HTTP 401)
-  - `ForbiddenError` (maps to HTTP 403)
-  - `NotFoundError` (maps to HTTP 404)
-  - `ConflictError` (maps to HTTP 409)
-  - `ExpiredError` (maps to HTTP 410)
-- **Eliminate Untyped Error Monkey-Patching**: Strictly prohibit monkey-patching arbitrary properties onto error objects at catch sites (e.g. `(err as any).statusCode = 404`). Use clean `instanceof` narrowing in HTTP error middleware to map domain errors deterministically to RFC 7807 status codes with full compiler type safety.
+# Error Handling, Request Tracing & Schema Validation
+
+> **Core Mandate:** Enforce fail-fast schema validation at startup, structured OpenTelemetry/JSON request tracing, standardized RFC 9457 problem details, and an explicit canonical DomainError hierarchy.
+
+---
+
+## 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 9457)
+
+Enforce a uniform error envelope across all external HTTP/REST endpoints conforming to the **RFC 9457 Problem Details** standard.
+
+> **Spec currency:** RFC 7807 was **obsoleted by RFC 9457** (July 2023). The wire format is unchanged — `type`/`title`/`status`/`detail`/`instance` plus the `application/problem+json` media type — so this is a citation correction, not a migration. Cite RFC 9457; do not reference RFC 7807 as a current 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.
+
+---
+
+## 4. Canonical Domain Error Hierarchy & Type-Safe Narrowing
+
+- **Canonical DomainError Hierarchy**: Model operational domain failures using an explicit `DomainError` base class with canonical subclasses:
+  - `ValidationError` (maps to HTTP 400 / 422)
+  - `UnauthorizedError` (maps to HTTP 401)
+  - `ForbiddenError` (maps to HTTP 403)
+  - `NotFoundError` (maps to HTTP 404)
+  - `ConflictError` (maps to HTTP 409)
+  - `ExpiredError` (maps to HTTP 410)
+- **Eliminate Untyped Error Monkey-Patching**: Strictly prohibit monkey-patching arbitrary properties onto error objects at catch sites (e.g. `(err as any).statusCode = 404`). Use clean `instanceof` narrowing in HTTP error middleware to map domain errors deterministically to RFC 7807 status codes with full compiler type safety.

package/docs/rules/feature_flags.md

@@ -1,59 +1,59 @@
-# 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. 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
-
-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';
-import { FliptProvider } from '@openfeature/flipt-provider';
-
-OpenFeature.setProvider(new FliptProvider({ url: process.env.FLIPT_URL }));
-export const featureClient: Client = OpenFeature.getClient();
-```
-
----
-
-## 3. 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
-  }
-);
-```
-
----
-
-## 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.
+# 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. 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
+
+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';
+import { FliptProvider } from '@openfeature/flipt-provider';
+
+OpenFeature.setProvider(new FliptProvider({ url: process.env.FLIPT_URL }));
+export const featureClient: Client = OpenFeature.getClient();
+```
+
+---
+
+## 3. 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
+  }
+);
+```
+
+---
+
+## 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.