azcodr 1.5.2 → 2.1.0

package/docs/rules/authorization.md

@@ -1,75 +1,75 @@
-# Enterprise Authorization, Policy-as-Code & ReBAC
-
-> **Core Mandate:** Enforce granular Role-Based, Attribute-Based, and Relationship-Based Access Control (RBAC/ABAC/ReBAC) via Open Policy Agent (OPA), OpenFGA, or Cerbos across all API boundaries.
-
----
-
-## 1. Declarative Policy-as-Code with Open Policy Agent (OPA)
-
-Standardize on **Open Policy Agent (OPA)** and the **Rego** language for externalized, auditable policy evaluation:
-
-```rego
-package app.authz
-
-default allow = false
-
-# Allow tenant admin to manage all resources within their tenant
-allow if {
-    input.user.role == "ADMIN"
-    input.user.tenant_id == input.resource.tenant_id
-}
-
-# Allow standard member to update drafts in their tenant
-allow if {
-    input.action == "update"
-    input.resource.type == "Order"
-    input.resource.status == "DRAFT"
-    input.user.tenant_id == input.resource.tenant_id
-}
-```
-
-### High-Performance In-Process Evaluation (OPA WebAssembly)
-- In addition to running OPA as a local daemon or sidecar over HTTP/gRPC, compile Rego policies to **`.wasm`** binaries.
-- Embedded OPA Wasm modules evaluate policies directly within application process memory across any language (Rust, Go, Python, Java, Node) with sub-millisecond latency and zero network roundtrips.
-
----
-
-## 2. Relationship-Based Access Control (ReBAC): OpenFGA / Zanzibar
-
-For multi-tenant organizational hierarchies, shared folders, and delegated permissions, standardize on **OpenFGA** (CNCF):
-
-```
-type user
-type organization
-  relations
-    define admin: [user]
-    define member: [user]
-
-type document
-  relations
-    define owner: [user]
-    define editor: [user] or owner
-    define viewer: [user] or editor or member from parent_org
-    define parent_org: [organization]
-```
-
-Evaluated via standard gRPC/REST clients from any polyglot service:
-`check(user="user:alice", relation="editor", object="document:doc-100")`
-
----
-
-## 3. Server-Side Policy Enforcement Point (PEP) Guarding
-
-- **Mandatory Enforcement**: Never rely on client-side permission checks. Every backend endpoint or command handler must verify authorization at the boundary before executing domain logic:
-  ```
-  decision = PolicyEngine.evaluate({
-    principal: currentUser,
-    action: "Order.Update",
-    resource: targetOrder,
-    context: { ip: request.ip, time: now() }
-  })
-  if (!decision.allowed) {
-    return Forbidden("INSUFFICIENT_PERMISSIONS")
-  }
-  ```
-- **Immutable System Role Invariants**: System-level roles (e.g. `OWNER`, `SECURITY_ADMIN`) must be protected by explicit policy rules preventing self-demotion or unauthorized role grants.
+# Enterprise Authorization, Policy-as-Code & ReBAC
+
+> **Core Mandate:** Enforce granular Role-Based, Attribute-Based, and Relationship-Based Access Control (RBAC/ABAC/ReBAC) via Open Policy Agent (OPA), OpenFGA, or Cerbos across all API boundaries.
+
+---
+
+## 1. Declarative Policy-as-Code with Open Policy Agent (OPA)
+
+Standardize on **Open Policy Agent (OPA)** and the **Rego** language for externalized, auditable policy evaluation:
+
+```rego
+package app.authz
+
+default allow = false
+
+# Allow tenant admin to manage all resources within their tenant
+allow if {
+    input.user.role == "ADMIN"
+    input.user.tenant_id == input.resource.tenant_id
+}
+
+# Allow standard member to update drafts in their tenant
+allow if {
+    input.action == "update"
+    input.resource.type == "Order"
+    input.resource.status == "DRAFT"
+    input.user.tenant_id == input.resource.tenant_id
+}
+```
+
+### High-Performance In-Process Evaluation (OPA WebAssembly)
+- In addition to running OPA as a local daemon or sidecar over HTTP/gRPC, compile Rego policies to **`.wasm`** binaries.
+- Embedded OPA Wasm modules evaluate policies directly within application process memory across any language (Rust, Go, Python, Java, Node) with sub-millisecond latency and zero network roundtrips.
+
+---
+
+## 2. Relationship-Based Access Control (ReBAC): OpenFGA / Zanzibar
+
+For multi-tenant organizational hierarchies, shared folders, and delegated permissions, standardize on **OpenFGA** (CNCF):
+
+```
+type user
+type organization
+  relations
+    define admin: [user]
+    define member: [user]
+
+type document
+  relations
+    define owner: [user]
+    define editor: [user] or owner
+    define viewer: [user] or editor or member from parent_org
+    define parent_org: [organization]
+```
+
+Evaluated via standard gRPC/REST clients from any polyglot service:
+`check(user="user:alice", relation="editor", object="document:doc-100")`
+
+---
+
+## 3. Server-Side Policy Enforcement Point (PEP) Guarding
+
+- **Mandatory Enforcement**: Never rely on client-side permission checks. Every backend endpoint or command handler must verify authorization at the boundary before executing domain logic:
+  ```
+  decision = PolicyEngine.evaluate({
+    principal: currentUser,
+    action: "Order.Update",
+    resource: targetOrder,
+    context: { ip: request.ip, time: now() }
+  })
+  if (!decision.allowed) {
+    return Forbidden("INSUFFICIENT_PERMISSIONS")
+  }
+  ```
+- **Immutable System Role Invariants**: System-level roles (e.g. `OWNER`, `SECURITY_ADMIN`) must be protected by explicit policy rules preventing self-demotion or unauthorized role grants.

package/docs/rules/caching.md

@@ -1,69 +1,69 @@
-# Caching Strategies & Event-Driven Invalidation
-
-> **Core Mandate:** Enforce Cache Port semantics with namespaced keys, jittered TTLs, XFetch stampede defense, event-driven cache invalidation, and HTTP conditional caching (ETags / 304).
-
----
-
-## 1. The YAGNI Gate: Database First, Caching Second
-
-Caching introduces state duplication, cache invalidation race conditions, and memory overhead. **Caching is never a substitute for missing database indexes or poorly structured SQL queries.**
-
-```mermaid
-flowchart TD
-    subgraph CachingGate["Caching YAGNI Gate"]
-        B1["1. Simple Baseline (Day 1)<br/>• Relational queries with composite indexes<br/>• Request-scoped in-memory DataLoader batching to eliminate N+1<br/>• Zero distributed cache infrastructure (no Redis / Memcached)"]
-        B2["2. Anti-Triggers (Forbidden)<br/>• Queries that are slow due to missing indexes or sequential scans<br/>• High-write / high-churn entities (write-heavy mutation streams)<br/>• Low-traffic administrative or internal operational queries"]
-        B3["3. The Tipping Point (Graduation)<br/>• Query has been optimized with EXPLAIN ANALYZE, but p99 latency still exceeds SLA (> 100ms)<br/>• Read-to-write asymmetry on the entity exceeds 20:1<br/>• Downstream external API rate limits or third-party egress costs demand response caching"]
-        B1 -->|Forbidden if missing indexes| B2
-        B1 -->|Triggered by high read/write ratio| B3
-    end
-```
-
----
-
-## 2. Abstract Cache Port & Cache-Aside Pattern
-
-Application services interact with caching infrastructure through a swappable **Cache Port**, supporting any backend (Redis, Valkey, Dragonfly, KeyDB, Memcached, or in-memory LRU):
-
-```mermaid
-classDiagram
-    class CachePort {
-        <<interface>>
-        +get(key: string) Optional~string~
-        +set(key: string, value: string, ttlSeconds: number) void
-        +delete(key: string) void
-        +deletePattern(pattern: string) void
-        +acquireLock(lockKey: string, ttlMs: number) boolean
-    }
-```
-
-### Cache-Aside Implementation & Stampede Defense
-```
-function getCachedOrFetch(cachePort, key, ttlSeconds, fetcher):
-  cachedValue = cachePort.get(key)
-  if cachedValue is present:
-    return deserialize(cachedValue)
-
-  freshValue = fetcher()
-  // Add 10% random jitter to TTL to prevent simultaneous expiration spikes
-  jitter = randomInt(0, floor(ttlSeconds * 0.1))
-  cachePort.set(key, serialize(freshValue), ttlSeconds + jitter)
-  return freshValue
-```
-
-For high-throughput cache regeneration, employ the **XFetch algorithm** (probabilistic early expiration) to asynchronously warm the cache before hard expiry.
-
----
-
-## 3. Key Namespacing & Event-Driven Invalidation
-
-- **Universal Key Hierarchy**: Structure all keys hierarchically:
-  `tenant:{tenantId}:{entity}:{entityId}` (e.g. `tenant:123:order:987`)
-- **Event-Driven Invalidation**: Invalidate affected cache keys immediately upon emitting domain mutation events (`OrderUpdated`, `CustomerDeleted`) rather than waiting for passive TTL expiry.
-
----
-
-## 4. HTTP Conditional Caching (ETags)
-
-- Generate strong cryptographic `ETag` hashes (e.g. SHA-256 of representation or resource version) for cacheable `GET` endpoints.
-- Return **`304 Not Modified`** with zero payload body when inbound requests present matching `If-None-Match` headers, preserving bandwidth and client CPU.
+# Caching Strategies & Event-Driven Invalidation
+
+> **Core Mandate:** Enforce Cache Port semantics with namespaced keys, jittered TTLs, XFetch stampede defense, event-driven cache invalidation, and HTTP conditional caching (ETags / 304).
+
+---
+
+## 1. The YAGNI Gate: Database First, Caching Second
+
+Caching introduces state duplication, cache invalidation race conditions, and memory overhead. **Caching is never a substitute for missing database indexes or poorly structured SQL queries.**
+
+```mermaid
+flowchart TD
+    subgraph CachingGate["Caching YAGNI Gate"]
+        B1["1. Simple Baseline (Day 1)<br/>• Relational queries with composite indexes<br/>• Request-scoped in-memory DataLoader batching to eliminate N+1<br/>• Zero distributed cache infrastructure (no Redis / Memcached)"]
+        B2["2. Anti-Triggers (Forbidden)<br/>• Queries that are slow due to missing indexes or sequential scans<br/>• High-write / high-churn entities (write-heavy mutation streams)<br/>• Low-traffic administrative or internal operational queries"]
+        B3["3. The Tipping Point (Graduation)<br/>• Query has been optimized with EXPLAIN ANALYZE, but p99 latency still exceeds SLA (> 100ms)<br/>• Read-to-write asymmetry on the entity exceeds 20:1<br/>• Downstream external API rate limits or third-party egress costs demand response caching"]
+        B1 -->|Forbidden if missing indexes| B2
+        B1 -->|Triggered by high read/write ratio| B3
+    end
+```
+
+---
+
+## 2. Abstract Cache Port & Cache-Aside Pattern
+
+Application services interact with caching infrastructure through a swappable **Cache Port**, supporting any backend (Redis, Valkey, Dragonfly, KeyDB, Memcached, or in-memory LRU):
+
+```mermaid
+classDiagram
+    class CachePort {
+        <<interface>>
+        +get(key: string) Optional~string~
+        +set(key: string, value: string, ttlSeconds: number) void
+        +delete(key: string) void
+        +deletePattern(pattern: string) void
+        +acquireLock(lockKey: string, ttlMs: number) boolean
+    }
+```
+
+### Cache-Aside Implementation & Stampede Defense
+```
+function getCachedOrFetch(cachePort, key, ttlSeconds, fetcher):
+  cachedValue = cachePort.get(key)
+  if cachedValue is present:
+    return deserialize(cachedValue)
+
+  freshValue = fetcher()
+  // Add 10% random jitter to TTL to prevent simultaneous expiration spikes
+  jitter = randomInt(0, floor(ttlSeconds * 0.1))
+  cachePort.set(key, serialize(freshValue), ttlSeconds + jitter)
+  return freshValue
+```
+
+For high-throughput cache regeneration, employ the **XFetch algorithm** (probabilistic early expiration) to asynchronously warm the cache before hard expiry.
+
+---
+
+## 3. Key Namespacing & Event-Driven Invalidation
+
+- **Universal Key Hierarchy**: Structure all keys hierarchically:
+  `tenant:{tenantId}:{entity}:{entityId}` (e.g. `tenant:123:order:987`)
+- **Event-Driven Invalidation**: Invalidate affected cache keys immediately upon emitting domain mutation events (`OrderUpdated`, `CustomerDeleted`) rather than waiting for passive TTL expiry.
+
+---
+
+## 4. HTTP Conditional Caching (ETags)
+
+- Generate strong cryptographic `ETag` hashes (e.g. SHA-256 of representation or resource version) for cacheable `GET` endpoints.
+- Return **`304 Not Modified`** with zero payload body when inbound requests present matching `If-None-Match` headers, preserving bandwidth and client CPU.

package/docs/rules/clean_code.md

@@ -1,62 +1,62 @@
-# Clean Code & Pragmatic Programming Directives
-
-> **Core Mandate:** Enforce intention-revealing naming, small focused functions, Command-Query Separation (CQS), Single Level of Abstraction (SLAP), and DRY pragmatic architecture across all codebases.
-
----
-
-## 1. Clean Code Standards (Robert C. Martin)
-
-- **Intention-Revealing Naming**: Names of variables, functions, and classes must describe why they exist, what they do, and how they are used. Avoid abbreviations, single-letter variables, and type-encoding prefixes.
-- **Function Guidelines**:
-  - **Small and Focused**: Functions should do one thing, do it well, and do only that (Single Responsibility Principle). Max 20–30 lines per function.
-  - **Single Level of Abstraction (SLAP)**: Statements within a function must belong to the exact same level of abstraction.
-  - **Command-Query Separation (CQS)**: A function must either perform an action (mutate state) or return a value (query state), never both.
-  - **Argument Limit**: Limit function arguments to 3 or fewer. Bundle additional parameters into typed configuration DTOs or Value Objects.
-- **Eliminate Side-Effects**: Functions must not have unexpected side effects (e.g. modifying passed arguments in-place or mutating global state) without explicit naming.
-- **Dead Code**: Never leave commented-out code; rely entirely on version control history.
-
----
-
-## 2. The Pragmatic Programmer Directives (Hunt & Thomas)
-
-- **DRY (Don't Repeat Yourself)**: Every piece of knowledge must have a single, unambiguous, authoritative representation within the system. DRY applies to business domain knowledge, not superficial syntax duplication.
-- **Orthogonality**: Eliminate coupling between unrelated modules. Changing one component must not cascade unexpected side effects into another.
-- **Broken Windows Theory**: Never leave bad code, failing lint checks, or out-of-date documentation unfixed. Fix defects immediately before entropy normalizes.
-- **Design by Contract (DbC)**: Define explicit preconditions (runtime boundary validation), postconditions (guaranteed response envelopes), and domain invariants.
-
----
-
-## 3. Evolutionary Architecture & Architectural Tipping Points (Ford, Parsons & Fowler)
-
-Architecture is not a static Day 1 monument; it evolves incrementally as complexity grows. AI coding tools naturally take the path of least resistance (local token minimization), repeatedly appending code to simple files until they rot into a Big Ball of Mud. To eliminate **AI-Accelerated Architectural Drift**, the agent must pause and execute an architectural upgrade whenever code hits a **Deterministic Tipping Point**:
-
-| Simple Baseline (Day 1) | Tipping Point / Mutation Trigger | Required Architectural Upgrade |
-|---|---|---|
-| **Flat Script / Single File** | File exceeds **250 lines**, or coordinates **>2 distinct I/O resources**, or is imported by **>3 distinct callers**. | **Extract Modular Subsystems:** Decouple domain logic from platform I/O; split into dedicated, focused submodules. |
-| **Inline `if/else` or `switch` Cascades** | **Rule of Three:** The 3rd branching variant, payment provider, or protocol format is introduced. | **Strategy Pattern / Registry:** Replace conditional branching with a polymorphic Strategy interface or handler registry; update `memory.md`. |
-| **In-Memory Store / Global State** | State requires **concurrent mutations**, **persistence across process restarts**, or **transactional rollback**. | **Repository Pattern & Persistence Port:** Introduce an explicit storage port contract; swap in-memory mock for a persistent database adapter. |
-| **Direct Platform / Third-Party Calls** | External SDK or platform API is called from **>2 places**, or SDK throws untyped exceptions across boundaries. | **Adapter Pattern (Anti-Corruption Layer):** Wrap external SDK inside an application-owned port interface; mock only the owned interface in tests. |
-| **Monolithic Domain Model** | The same business noun represents divergent lifecycles or definitions across workflows (e.g. `User` in Auth vs `User` in Billing). | **Bounded Context Split:** Separate into isolated domain contexts with explicit DTO / Anti-Corruption translation between them. |
-
----
-
-## 4. The "Refactor-Before-Add" Protocol (Kent Beck's Rule)
-
-> *"Make the change easy (warning: this may be hard), then make the easy change."* — Kent Beck
-
-Before writing production code for any new feature or user story, the agent must execute the **Refactor-Before-Add Check**:
-1. **Assess Tipping Points**: Will adding this requirement cause any module, function, or data structure to cross an architectural tipping point?
-2. **Phase A — Structural Refactoring (Under Green)**: If yes, refactor the existing architecture *first* while existing test suites remain 100% green. Zero behavioral changes; purely structural evolution.
-3. **Phase B — ADR Mutation**: When an architectural tipping point is crossed, log a Lightweight Architectural Decision Record in `memory.md` summarizing the new structural boundary and trade-off.
-4. **Phase C — Feature Implementation (Inner TDD)**: Only once the architecture cleanly accommodates the new capability, write the failing micro-test and implement the feature.
-
----
-
-## 5. Architectural Fitness Functions (Automated Tripwires)
-
-Prevent AI-generated code rot using automated fitness functions integrated into linting and continuous verification:
-- **File Length Gates**: Maximum 250–300 lines per file (ESLint `max-lines`).
-- **Function Length Gates**: Maximum 20–30 lines per function (ESLint `max-lines-per-function`).
-- **Dependency Direction Gates**: Enforce unidirectional import rules (e.g. `import/no-restricted-paths`, `dependency-cruiser`, `ArchUnit`) ensuring domain core never imports infrastructure or transport adapters.
-- **Complexity Budgets**: Enforce cyclomatic complexity limits (maximum 10 per function).
-If an AI attempt to add code violates any fitness function, the build fails immediately, blocking completion until the architecture is refactored.
+# Clean Code & Pragmatic Programming Directives
+
+> **Core Mandate:** Enforce intention-revealing naming, small focused functions, Command-Query Separation (CQS), Single Level of Abstraction (SLAP), and DRY pragmatic architecture across all codebases.
+
+---
+
+## 1. Clean Code Standards (Robert C. Martin)
+
+- **Intention-Revealing Naming**: Names of variables, functions, and classes must describe why they exist, what they do, and how they are used. Avoid abbreviations, single-letter variables, and type-encoding prefixes.
+- **Function Guidelines**:
+  - **Small and Focused**: Functions should do one thing, do it well, and do only that (Single Responsibility Principle). Max 20–30 lines per function.
+  - **Single Level of Abstraction (SLAP)**: Statements within a function must belong to the exact same level of abstraction.
+  - **Command-Query Separation (CQS)**: A function must either perform an action (mutate state) or return a value (query state), never both.
+  - **Argument Limit**: Limit function arguments to 3 or fewer. Bundle additional parameters into typed configuration DTOs or Value Objects.
+- **Eliminate Side-Effects**: Functions must not have unexpected side effects (e.g. modifying passed arguments in-place or mutating global state) without explicit naming.
+- **Dead Code**: Never leave commented-out code; rely entirely on version control history.
+
+---
+
+## 2. The Pragmatic Programmer Directives (Hunt & Thomas)
+
+- **DRY (Don't Repeat Yourself)**: Every piece of knowledge must have a single, unambiguous, authoritative representation within the system. DRY applies to business domain knowledge, not superficial syntax duplication.
+- **Orthogonality**: Eliminate coupling between unrelated modules. Changing one component must not cascade unexpected side effects into another.
+- **Broken Windows Theory**: Never leave bad code, failing lint checks, or out-of-date documentation unfixed. Fix defects immediately before entropy normalizes.
+- **Design by Contract (DbC)**: Define explicit preconditions (runtime boundary validation), postconditions (guaranteed response envelopes), and domain invariants.
+
+---
+
+## 3. Evolutionary Architecture & Architectural Tipping Points (Ford, Parsons & Fowler)
+
+Architecture is not a static Day 1 monument; it evolves incrementally as complexity grows. AI coding tools naturally take the path of least resistance (local token minimization), repeatedly appending code to simple files until they rot into a Big Ball of Mud. To eliminate **AI-Accelerated Architectural Drift**, the agent must pause and execute an architectural upgrade whenever code hits a **Deterministic Tipping Point**:
+
+| Simple Baseline (Day 1) | Tipping Point / Mutation Trigger | Required Architectural Upgrade |
+|---|---|---|
+| **Flat Script / Single File** | File exceeds **250 lines**, or coordinates **>2 distinct I/O resources**, or is imported by **>3 distinct callers**. | **Extract Modular Subsystems:** Decouple domain logic from platform I/O; split into dedicated, focused submodules. |
+| **Inline `if/else` or `switch` Cascades** | **Rule of Three:** The 3rd branching variant, payment provider, or protocol format is introduced. | **Strategy Pattern / Registry:** Replace conditional branching with a polymorphic Strategy interface or handler registry; update `memory.md`. |
+| **In-Memory Store / Global State** | State requires **concurrent mutations**, **persistence across process restarts**, or **transactional rollback**. | **Repository Pattern & Persistence Port:** Introduce an explicit storage port contract; swap in-memory mock for a persistent database adapter. |
+| **Direct Platform / Third-Party Calls** | External SDK or platform API is called from **>2 places**, or SDK throws untyped exceptions across boundaries. | **Adapter Pattern (Anti-Corruption Layer):** Wrap external SDK inside an application-owned port interface; mock only the owned interface in tests. |
+| **Monolithic Domain Model** | The same business noun represents divergent lifecycles or definitions across workflows (e.g. `User` in Auth vs `User` in Billing). | **Bounded Context Split:** Separate into isolated domain contexts with explicit DTO / Anti-Corruption translation between them. |
+
+---
+
+## 4. The "Refactor-Before-Add" Protocol (Kent Beck's Rule)
+
+> *"Make the change easy (warning: this may be hard), then make the easy change."* — Kent Beck
+
+Before writing production code for any new feature or user story, the agent must execute the **Refactor-Before-Add Check**:
+1. **Assess Tipping Points**: Will adding this requirement cause any module, function, or data structure to cross an architectural tipping point?
+2. **Phase A — Structural Refactoring (Under Green)**: If yes, refactor the existing architecture *first* while existing test suites remain 100% green. Zero behavioral changes; purely structural evolution.
+3. **Phase B — ADR Mutation**: When an architectural tipping point is crossed, log a Lightweight Architectural Decision Record in `memory.md` summarizing the new structural boundary and trade-off.
+4. **Phase C — Feature Implementation (Inner TDD)**: Only once the architecture cleanly accommodates the new capability, write the failing micro-test and implement the feature.
+
+---
+
+## 5. Architectural Fitness Functions (Automated Tripwires)
+
+Prevent AI-generated code rot using automated fitness functions integrated into linting and continuous verification:
+- **File Length Gates**: Maximum 250–300 lines per file (ESLint `max-lines`).
+- **Function Length Gates**: Maximum 20–30 lines per function (ESLint `max-lines-per-function`).
+- **Dependency Direction Gates**: Enforce unidirectional import rules (e.g. `import/no-restricted-paths`, `dependency-cruiser`, `ArchUnit`) ensuring domain core never imports infrastructure or transport adapters.
+- **Complexity Budgets**: Enforce cyclomatic complexity limits (maximum 10 per function).
+If an AI attempt to add code violates any fitness function, the build fails immediately, blocking completion until the architecture is refactored.

package/docs/rules/cloud_native.md

@@ -1,41 +1,41 @@
-# Cloud-Native 12-Factor Standards (2026 Edition)
-
-> **Core Mandate:** Enforce stateless isolates, OpenTelemetry (OTel) observability, API-first design, fast startup, and graceful disposal on SIGTERM across all execution runtimes.
-
----
-
-## 1. Stateless Isolates & Shared-Nothing
-
-- Application processes must be strictly stateless and share nothing.
-- Any persistent state must reside in external, managed backing services (relational databases, document stores, distributed caches, object storage).
-- User sessions and conversational state must never be held in local process memory.
-
----
-
-## 2. OpenTelemetry (OTel) Standardization
-
-- Standardize exclusively on open-source **OpenTelemetry** across all language runtimes.
-- Export traces, metrics, and logs in vendor-neutral **OTLP (OpenTelemetry Protocol)** format over gRPC (port 4317) or HTTP (port 4318) to an OpenTelemetry Collector.
-- Propagate distributed trace context across service boundaries using standard W3C `traceparent` and `tracestate` headers.
-
----
-
-## 3. Disposability & Graceful Shutdown
-
-All application processes and containers must handle graceful termination:
-- Trap operating system `SIGTERM` and `SIGINT` signals.
-- Cease accepting new inbound HTTP/gRPC requests immediately upon signal receipt.
-- Drain active, in-flight connections within a bounded timeout window (e.g. 10 seconds).
-- Gracefully flush telemetry buffers, terminate background workers, and close database/cache connection pools cleanly before exiting with code 0:
-
-```mermaid
-flowchart TD
-    subgraph GracefulShutdown["Graceful Shutdown Flow (Universal / Agnostic)"]
-        Sig["onSignal (SIGTERM | SIGINT)"] --> S1["1. Set health check probe to UNHEALTHY (drain LB)"]
-        S1 --> S2["2. Stop server listening for new connections"]
-        S2 --> S3["3. Wait for in-flight requests (timeout: 10s)"]
-        S3 --> S4["4. Close database and cache connection pools"]
-        S4 --> S5["5. Flush OpenTelemetry trace & log buffers"]
-        S5 --> S6["6. Terminate process with exit code 0"]
-    end
-```
+# Cloud-Native 12-Factor Standards (2026 Edition)
+
+> **Core Mandate:** Enforce stateless isolates, OpenTelemetry (OTel) observability, API-first design, fast startup, and graceful disposal on SIGTERM across all execution runtimes.
+
+---
+
+## 1. Stateless Isolates & Shared-Nothing
+
+- Application processes must be strictly stateless and share nothing.
+- Any persistent state must reside in external, managed backing services (relational databases, document stores, distributed caches, object storage).
+- User sessions and conversational state must never be held in local process memory.
+
+---
+
+## 2. OpenTelemetry (OTel) Standardization
+
+- Standardize exclusively on open-source **OpenTelemetry** across all language runtimes.
+- Export traces, metrics, and logs in vendor-neutral **OTLP (OpenTelemetry Protocol)** format over gRPC (port 4317) or HTTP (port 4318) to an OpenTelemetry Collector.
+- Propagate distributed trace context across service boundaries using standard W3C `traceparent` and `tracestate` headers.
+
+---
+
+## 3. Disposability & Graceful Shutdown
+
+All application processes and containers must handle graceful termination:
+- Trap operating system `SIGTERM` and `SIGINT` signals.
+- Cease accepting new inbound HTTP/gRPC requests immediately upon signal receipt.
+- Drain active, in-flight connections within a bounded timeout window (e.g. 10 seconds).
+- Gracefully flush telemetry buffers, terminate background workers, and close database/cache connection pools cleanly before exiting with code 0:
+
+```mermaid
+flowchart TD
+    subgraph GracefulShutdown["Graceful Shutdown Flow (Universal / Agnostic)"]
+        Sig["onSignal (SIGTERM | SIGINT)"] --> S1["1. Set health check probe to UNHEALTHY (drain LB)"]
+        S1 --> S2["2. Stop server listening for new connections"]
+        S2 --> S3["3. Wait for in-flight requests (timeout: 10s)"]
+        S3 --> S4["4. Close database and cache connection pools"]
+        S4 --> S5["5. Flush OpenTelemetry trace & log buffers"]
+        S5 --> S6["6. Terminate process with exit code 0"]
+    end
+```