azcodr 1.0.0

package/docs/rules/api_versioning.md

@@ -0,0 +1,128 @@
+# API Versioning, SemVer Lifecycle & Swagger Multi-Version Architecture
+
+> **Core Mandate:** Enforce URI path major versioning (`/api/v1/`), SemVer 2.0.0 contract specifications, RFC 8594 Sunset/Deprecation headers, a 90-day retirement window, and multi-version Swagger UI exploration.
+
+---
+
+## 1. Semantic Versioning (SemVer 2.0.0) in Web APIs
+
+Semantic Versioning maps to Web APIs according to contract stability and backward compatibility:
+
+$$\text{Version Format: } \mathbf{MAJOR.MINOR.PATCH}$$
+
+| SemVer Component | Scope & Impact | Exposure Channel | Example |
+|---|---|---|---|
+| **MAJOR** | Breaking, backwards-incompatible contract modifications. Requires client code/URL changes. | URI Path (`/api/v1/`, `/api/v2/`) & OpenAPI `info.version` | `2.0.0` |
+| **MINOR** | Backwards-compatible additive functionality, new endpoints, or optional attributes. | OpenAPI `info.version`, `API-Version` response header | `1.1.0` |
+| **PATCH** | Backwards-compatible bug fixes, performance optimizations, and documentation fixes. | OpenAPI `info.version`, release tags, telemetry metadata | `1.0.1` |
+
+> [!IMPORTANT]
+> **Why URI Path Exposes MAJOR Only:**
+> Exposing minor or patch versions in the URL path (e.g. `/api/v1.2.3/`) is a severe anti-pattern. Minor additions and bug fixes must not break client routing. Clients bind to the stable major version (`/api/v1/`) while consuming backward-compatible updates transparently.
+
+---
+
+## 2. SemVer Trigger Matrix: What Triggers a Version Update?
+
+### A. MAJOR Bump (`1.x.x` ➔ `2.0.0`) — Breaking Changes
+A MAJOR version bump and a new URI prefix (`/api/v2/`) are triggered whenever existing clients would fail without code modifications:
+
+1. **Endpoint Alterations:**
+   - Deleting an existing endpoint or HTTP method.
+   - Renaming an existing URL path or subresource route.
+2. **Request Contract Breaking Changes:**
+   - Removing an existing request parameter (header, query, or body field).
+   - Renaming a request field.
+   - Changing the data type or format of a request field (e.g., string integer to number, date format change).
+   - Adding a new **mandatory / required** field to an existing request payload without a default value.
+   - Tightening input validation constraints (e.g., reducing max string length, narrowing allowed enum values).
+3. **Response Contract Breaking Changes:**
+   - Removing an existing field from a response payload.
+   - Changing the data type or structure of a response field (e.g., object converted to array, integer cents converted to float string).
+   - Changing the semantic business meaning of a field.
+4. **Behavioral & Protocol Breaking Changes:**
+   - Altering the standard HTTP status code for successful execution (e.g., changing `200 OK` to `204 No Content` or `201 Created`).
+   - Changing the error envelope schema away from RFC 7807 problem details.
+   - Changing authentication or authorization requirements (e.g. requiring a new OAuth scope or mTLS).
+
+### B. MINOR Bump (`1.0.x` ➔ `1.1.0`) — Additive, Backward-Compatible
+A MINOR version bump preserves the `/api/v1/` URI path and updates the contract specification:
+
+1. Adding completely new endpoints or resources (e.g., adding `POST /api/v1/documents/:id/signatures`).
+2. Adding new optional query parameters, headers, or request body fields.
+3. Adding new fields to response payloads (clients must follow Postel's Law / Tolerant Reader pattern).
+4. Adding new enum values to input requests if the service handles them gracefully without breaking old clients.
+5. Relaxing validation constraints (e.g., increasing maximum allowed file upload size or string length).
+6. Introducing deprecation notices on endpoints (via RFC 8594 headers) while maintaining functionality.
+
+### C. PATCH Bump (`1.0.0` ➔ `1.0.1`) — Bug Fixes & Non-Contractual Changes
+A PATCH version bump preserves contract schemas and updates release metadata:
+
+1. Internal bug fixes in domain logic that do not alter the contractual request/response schema or status codes.
+2. Performance enhancements, caching optimization, and database indexing.
+3. Security patches in dependencies and runtime frameworks.
+4. Clarifications, typo corrections, and formatting updates in OpenAPI descriptions.
+
+---
+
+## 3. RFC 8594 Sunset & Deprecation Lifecycle
+
+When an older major version or endpoint is scheduled for retirement, inject standardized RFC 8594 headers:
+
+```http
+Deprecation: @1773619200
+Sunset: Wed, 16 Sep 2026 23:59:59 GMT
+Link: <https://api.domain.com/docs/migration/v2>; rel="sunset"
+```
+
+- **Mandatory 90-Day Migration Window:** Retain deprecated API versions for a minimum of 90 days following formal deprecation notification before decommissioning.
+- **Access Telemetry:** Track consumer traffic on deprecated routes via OpenTelemetry attributes (`api.deprecated=true`, `http.route`) to coordinate client migration.
+
+---
+
+## 4. Swagger UI Multi-Version Selector Architecture
+
+Swagger UI must provide an interactive version dropdown selector enabling consumers and developers to inspect both active and upcoming API specifications.
+
+### Multi-Spec Configuration in Express / Swagger UI:
+```ts
+app.use(
+  '/docs',
+  swaggerUi.serve,
+  swaggerUi.setup(undefined, {
+    swaggerOptions: {
+      urls: [
+        { url: '/specs/v1/openapi.yaml', name: 'v1.0.0 (Current Stable)' },
+        { url: '/specs/v2/openapi.yaml', name: 'v2.0.0-draft (Next Major Preview)' }
+      ],
+      'urls.primaryName': 'v1.0.0 (Current Stable)'
+    }
+  })
+);
+```
+
+### Filesystem Specification Hierarchy:
+```
+specs/
+├── openapi/
+│   ├── v1/
+│   │   └── openapi.yaml
+│   └── v2/
+│       └── openapi.yaml
+```
+
+---
+
+## 5. Invariants, DO's & DONT's
+
+### DO's:
+- **DO:** Prefix all public REST endpoints with major version identifiers (`/api/v1/`, `/api/v2/`).
+- **DO:** Bump MAJOR and cut a new `/api/v2/` prefix whenever request or response breaking changes occur.
+- **DO:** Inject RFC 8594 `Sunset` and `Deprecation` headers on all retired endpoints and provide a 90-day grace period.
+- **DO:** Organize specs into versioned folders (`specs/openapi/v1/`, `v2/`) with an interactive Swagger selector.
+
+### DONT's:
+- **DONT:** Never expose minor or patch numbers in the URL path (e.g. `/api/v1.2/`).
+- **DONT:** Never introduce breaking schema or status code changes within an existing major version.
+- **DONT:** Never delete an active endpoint without a formal deprecation lifecycle.
+

package/docs/rules/application_security.md

@@ -0,0 +1,23 @@
+# Application Security & OWASP Top 10 Defenses
+
+> **Core Mandate:** Enforce proactive defenses against the OWASP Top 10 vulnerabilities, cryptographic rigor, and token-bucket rate limiting across all layers.
+
+---
+
+## 1. OWASP Top 10 Defenses
+
+- **A01: Broken Access Control**: Verify permissions server-side on every request using Policy Enforcement Points (PEPs). Enforce immutable multi-tenancy data isolation (AST interceptors, database RLS, or schema namespaces).
+- **A02: Cryptographic Failures**: Passwords must be hashed using **Argon2id** with memory-hard parameters. Encrypt sensitive data at rest using authenticated ciphers (**AES-256-GCM** or **ChaCha20-Poly1305**).
+- **A03: Injection (SQL / NoSQL / Command)**: Strictly prohibit raw query string interpolation or dynamic execution. All database interactions must use parameterized prepared statements.
+- **A07: Identification and Authentication Failures**: Enforce rate limiting on auth endpoints, FIDO2/WebAuthn passkeys, and Refresh Token Rotation (RTR) with family invalidation on replay detection.
+- **A10: Server-Side Request Forgery (SSRF)**: Validate and restrict outbound network requests to an explicit allowlist of domains. Block requests targeting RFC 1918 private IP ranges, loopback addresses (`127.0.0.1`), and cloud metadata endpoints (`169.254.169.254`).
+
+---
+
+## 2. Distributed API Rate Limiting
+
+- Utilize token-bucket or sliding-window rate limiters backed by a distributed in-memory cache port.
+- Enforce tiered rate limits:
+  - Authentication routes: Max 5 requests / minute per IP.
+  - Standard API routes: Max 100 requests / minute per tenant/user.
+- Return **`429 Too Many Requests`** with standard `Retry-After` and `RateLimit-*` IETF headers when limits are exceeded.

package/docs/rules/architecture_decision_records.md

@@ -0,0 +1,42 @@
+# Architecture Decision Records (ADR)
+
+> **Core Mandate:** Log all technical, architectural, and operational trade-offs in `memory.md` using the standardized Lightweight ADR format.
+
+---
+
+## 1. When to Author an ADR
+
+An Architectural Decision Record must be authored whenever a team member or agent:
+- Introduces or removes an external dependency or library.
+- Modifies database schema architecture, transaction boundaries, or migration strategies.
+- Selects an architectural pattern (e.g. Server-Driven UI, Event-Driven Outbox, OpenFeature).
+- Defines security boundaries, cryptographic standards, or compliance exceptions.
+
+---
+
+## 2. Lightweight ADR Format
+
+Log decisions in `memory.md` adhering to this structure:
+
+```markdown
+### ADR-[Number]: [Concise Title]
+
+- **Date:** [YYYY-MM-DD]
+- **Status:** [PROPOSED | ACCEPTED | SUPERSEDED]
+
+#### 1. Context & Problem Statement
+What business requirement, technical bottleneck, or security mandate necessitated this architectural decision?
+
+#### 2. Decision Drivers
+- [Driver 1: e.g. Zero-downtime database deployment]
+- [Driver 2: e.g. SOC 2 Type II tamper-evident logging compliance]
+
+#### 3. Considered Options
+- **Option A:** [Description and evaluation]
+- **Option B:** [Description and evaluation]
+
+#### 4. Decision Outcome & Consequences
+- **Chosen Option:** [Selected approach and core rationale]
+- **Positive Consequences:** [What improves]
+- **Negative Consequences / Trade-offs:** [What operational or code overhead is accepted]
+```

package/docs/rules/authentication.md

@@ -0,0 +1,76 @@
+# Enterprise Authentication, Token Rotation & WebAuthn
+
+> **Core Mandate:** Enforce in-memory short-lived access tokens, cryptographic Refresh Token Rotation (RTR) with family revocation on replay detection, FIDO2/WebAuthn passkeys, and OIDC federation.
+
+---
+
+## 1. Token Lifecycles & Cryptographic Refresh Token Rotation (RTR)
+
+- **Access Tokens**: Short-lived (max 15 minutes), held strictly in volatile application memory or client memory (never persisted in unencrypted browser storage). Standardize on **PASETO** (Platform-Agnostic Security Tokens) or **RFC 7519 JWT** with asymmetric RSA/EdDSA keys published via `/.well-known/jwks.json`.
+- **Refresh Tokens**: Stored strictly in `HttpOnly`, `Secure`, `SameSite=Strict` cookies or encrypted OS keyrings.
+- **Cryptographic Rotation & Replay Detection Protocol**:
+  - Persist only cryptographically salted hashes (e.g. SHA-256 / Argon2id) of refresh tokens in storage.
+  - Group tokens by `family_id` across rotation cycles.
+  - If an expired or already-consumed token in a family is presented (replay attack), **immediately invalidate the entire token family**, terminate active sessions, and emit a high-priority security alert.
+
+---
+
+## 2. FIDO2 / WebAuthn Passkeys & Multi-Factor Authentication
+
+- **FIDO2 / WebAuthn Standard**: Support hardware security keys (YubiKey, Apple Touch ID/Face ID, Windows Hello) conforming to the W3C WebAuthn Level 3 specification.
+- **Server Cryptographic Verification**: Validate hardware-signed cryptographic challenges against stored credential public keys using language-native WebAuthn verifier ports.
+- **Time-Based One-Time Passwords (TOTP)**: Implement RFC 6238 compliant TOTP verification as an alternative MFA factor.
+
+---
+
+## 3. Enterprise Identity Federation & Workload Identity
+
+- **OIDC & OAuth 2.1**: Standardize on OpenID Connect 1.0 Authorization Code Flow with PKCE for enterprise single sign-on (SSO) with Okta, Azure AD, Keycloak, or Google Workspace.
+- **SCIM 2.0 Provisioning**: Implement RFC 7644 SCIM endpoints for automated tenant user synchronization and lifecycle de-provisioning.
+- **Service-to-Service Workload Identity**: Utilize **SPIFFE / SPIRE** for zero-trust mutual TLS (mTLS) cryptographic attestation between polyglot microservices.
+
+---
+
+## 4. Frontend Authentication Architecture & Production UX
+
+- **Dedicated Auth Experience**:
+  - Provide a clean, focused, professional sign-in interface (dedicated `/login` route or unpolluted modal) with zero clutter.
+  - Require formal Zod schema validation on submit and blur using React Hook Form.
+  - Enforce accessible error messaging using ARIA live regions (`role="alert"` / `aria-live="assertive"`).
+  - Include "Remember me" session persistence and "Forgot password?" recovery options.
+  - Provide a separate, dedicated registration flow (`/register`) with tenant organization initialization.
+- **Post-Login Role-Based Redirection Matrix**:
+  - Authentication must evaluate the user's primary active role and immediately redirect to their tailored domain experience:
+    - `ADMIN`, `OPERATOR`, `MANAGER` ➔ `/` (Operator Executive Dashboard).
+    - `MEMBER`, `CONSUMER` ➔ `/portal` (Self-Service Consumer Portal).
+    - `PROSPECT`, `GUEST` ➔ `/catalog` or `/onboarding`.
+- **Session State & Token Management**:
+  - Store short-lived access tokens strictly in memory within the frontend application context.
+  - Automatically refresh tokens in the background via `POST /api/v1/auth/refresh` using HttpOnly refresh cookies.
+  - On application mount, restore session state and memberships gracefully without flashing unauthenticated screens or crashing.
+- **Declarative Route & Role Guards**:
+  - Wrap protected views in `<ProtectedRoute requiredRoles={[...]} fallbackUrl="...">`.
+  - Unauthenticated access redirects to `/login?returnTo=<current_url>`.
+  - Unauthorized access renders an accessible 403 Forbidden view with a "Return to My Dashboard" CTA.
+
+---
+
+## 5. Strict Decoupling of Developer Demo Personas from Production Authentication
+
+- **The Toy Prototype Anti-Pattern**: Embedding test personas ("Admin Alice", "Operator Bob", "Member Charlie") directly inside user-facing login forms or modals severely compromises application credibility and confuses real users.
+- **Mandatory Isolation**:
+  - Developer demo personas must be **100% decoupled** from production authentication.
+  - Demo personas must exist exclusively in a dedicated **Development Test Harness** (`<DevPersonaSwitcher />` or floating dev toolbar) rendered conditionally:
+    ```tsx
+    // Rendered ONLY in local development or preview environments
+    if (import.meta.env.DEV) {
+      return <DevPersonaToolbar />;
+    }
+    ```
+  - The Dev Toolbar must be explicitly badge-labeled: `[DEV / TEST HARNESS: Switch Role]`.
+  - When switching personas, the harness must:
+    1. Clear stale TanStack Query caches to prevent data cross-contamination.
+    2. Authenticate the selected demo persona and update auth context.
+    3. Trigger role-appropriate navigation (e.g. switching to Member navigates to `/portal`; switching to Operator navigates to `/`).
+- **Zero Production Leaks**: In production builds (`import.meta.env.PROD`), the developer persona switcher must be tree-shaken and completely stripped from the bundle.
+

package/docs/rules/authorization.md

@@ -0,0 +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.

package/docs/rules/caching.md

@@ -0,0 +1,52 @@
+# 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. 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):
+
+```
+┌────────────────────────────────────────────────────────┐
+│ Cache Port Interface (Agnostic Contract)               │
+├────────────────────────────────────────────────────────┤
+│ get(key): Optional<String>                             │
+│ set(key, value, ttlSeconds): void                      │
+│ delete(key): void                                      │
+│ deletePattern(pattern): void                           │
+│ acquireLock(lockKey, ttlMs): 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.
+
+---
+
+## 2. 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.
+
+---
+
+## 3. 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

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

package/docs/rules/cloud_native.md

@@ -0,0 +1,43 @@
+# 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:
+
+```
+┌────────────────────────────────────────────────────────┐
+│ Graceful Shutdown Flow (Universal / Agnostic)          │
+├────────────────────────────────────────────────────────┤
+│ onSignal(SIGTERM | SIGINT):                            │
+│   1. Set health check probe to UNHEALTHY (drain LB)    │
+│   2. Stop server listening for new connections         │
+│   3. Wait for in-flight requests (timeout: 10s)        │
+│   4. Close database and cache connection pools         │
+│   5. Flush OpenTelemetry trace & log buffers           │
+│   6. Terminate process with exit code 0                │
+└────────────────────────────────────────────────────────┘
+```

package/docs/rules/compliance.md

@@ -0,0 +1,25 @@
+# Regulatory Compliance: SOC 2, ISO 27001 & GDPR
+
+> **Core Mandate:** Enforce SOC 2 Type II Trust Services Criteria, ISO/IEC 27001 ISMS technical controls, and GDPR data subject privacy rights using open-source architectures.
+
+---
+
+## 1. SOC 2 Type II Trust Services Criteria
+
+- **Access Controls (CC6.1)**: Enforce least-privilege RBAC/ABAC on all API endpoints. System-defined roles must be protected from unauthorized mutation.
+- **Tamper-Evident Audit Trails (CC7.2)**:
+  - All state mutations must create write-only, immutable audit log records:
+    `{ timestamp, actorId, tenantId, action, entityType, entityId, ipAddress, userAgent, changes: { before, after } }`.
+  - Audit logs must be retained for at least 365 days in append-only storage.
+
+---
+
+## 2. ISO/IEC 27001 ISMS Technical Controls
+
+- **Annex A Cryptographic Controls (A.10.1)**: Enforce TLS 1.3 for data in transit and AES-256-GCM for sensitive data at rest. Passwords must be hashed using Argon2id or bcrypt.
+
+---
+
+## 3. GDPR Data Subject Rights
+
+- **Right to Erasure (Article 17)**: Deleting a tenant or user must cascade delete or pseudonymize all associated personal identifiable information (PII) across active databases and backups.

package/docs/rules/container_infrastructure.md

@@ -0,0 +1,32 @@
+# Container Infrastructure & Local Parity
+
+> **Core Mandate:** Enforce production parity through containerized reverse proxy routing, explicit OCI service healthchecks, non-root security boundaries, and minimal distroless base images.
+
+---
+
+## 1. Gateway Routing & Local Parity
+
+- **Unified Gateway Routing**: Route all local development and production services through an edge reverse proxy gateway (such as **Envoy** or **Nginx**) on standard HTTP ports to eliminate CORS discrepancies and simulate production multi-service topologies uniformly.
+- **Internal Network Isolation**: Isolate internal services and datastores on a private bridge or overlay network, exposing only the hardened gateway entrypoint to public interfaces.
+
+---
+
+## 2. OCI Healthchecks & Deterministic Dependency Ordering
+
+- **Explicit Service Healthchecks**: Every database, cache, message broker, and application service in container configurations (`docker-compose.yml` or Kubernetes manifests) must define an explicit healthcheck command and interval.
+- **Strict Dependency Ordering**: Dependent application services must wait for upstream database and cache readiness, never launching before health verification:
+  ```yaml
+  depends_on:
+    database:
+      condition: service_healthy
+    cache:
+      condition: service_healthy
+  ```
+
+---
+
+## 3. Container Security & Build Performance
+
+- **Non-Root Execution**: Run all application containers strictly as unprivileged users (UID >= 10001) with read-only root filesystems and dropped Linux capabilities (`cap_drop: ALL`).
+- **Minimal OCI Base Images**: Standardize on **Distroless** (Google Container Tools) or **Scratch** base images across all polyglot microservices, eliminating package managers, debug shells, and OS vulnerabilities.
+- **Multi-Stage Build Optimization**: Utilize multi-stage OCI builds with cache mounts across dependency steps to minimize image sizes and maximize layer cache reuse.

package/docs/rules/continuous_deployment.md

@@ -0,0 +1,24 @@
+# Continuous Deployment (CD) & Release Engineering
+
+> **Core Mandate:** Enforce zero-downtime deployment rollouts, cryptographic container signing with Cosign, and minimal attack surface container baselines.
+
+---
+
+## 1. Zero-Downtime Deployment Strategies
+
+- **Blue-Green / Rolling Deployments**: Deploy new application versions alongside active instances, verify readiness healthchecks, and shift traffic seamlessly without dropping connections.
+- **Rollback Automation**: If error rates or latency spike beyond thresholds immediately post-deployment, automate an instant rollback to the previous stable release.
+
+---
+
+## 2. Container Signing & Provenance (Cosign)
+
+- Utilize open-source **Cosign** (Sigstore) to cryptographically sign all release container images in the deployment pipeline.
+- Production Kubernetes / Docker hosts must verify Cosign image signatures and provenance attestations before pulling and launching containers.
+
+---
+
+## 3. Container Minimization
+
+- Standardize on minimal container base images (`node:24-alpine` or distroless images).
+- Purge all devDependencies, compilers, and package managers from the final production container layer.

package/docs/rules/continuous_integration.md

@@ -0,0 +1,20 @@
+# Continuous Integration (CI) & Quality Gates
+
+> **Core Mandate:** Enforce shift-left automated quality gates, trunk-based development with short-lived branches, and mandatory green pipeline verification before merge.
+
+---
+
+## 1. Shift-Left Automated Quality Gates
+
+Every pull request pipeline must execute automated checks in strict dependency stages:
+1. **Security & Secrets**: Open-source secret scanning (`secretlint`) and SAST analysis (`semgrep`).
+2. **Static Analysis**: ESLint (`npm run lint`) and TypeScript typecheck (`npm run typecheck`).
+3. **Full-Stack Test Coverage**: Unit and acceptance tests verifying **100.00%** coverage (`npm run coverage`).
+4. **Supply Chain Audit**: Vulnerability scan of dependencies and SBOM generation (`syft` + `grype`).
+
+---
+
+## 2. Trunk-Based Development
+
+- **Short-Lived Branches**: Feature branches must live less than 24–48 hours before merging to the main trunk.
+- **Fast Build Times**: Docker build layers and npm packages must be cached in CI runners to maintain pipeline execution times under 5 minutes.

package/docs/rules/continuous_learning.md

@@ -0,0 +1,29 @@
+# Continuous Learning & Automated Rule Ingestion
+
+> **Core Mandate:** Automatically log development defects, post-mortems, and lessons learned into workspace memory, dynamically updating or generating atomic rules to permanently prevent recurrence.
+
+---
+
+## 1. The Automated Rule Ingestion Loop
+
+Whenever an error, test failure, build friction, or architectural anti-pattern occurs during development, immediately execute the 5-step loop:
+
+```
+1. Capture Defect ──► 2. Root Cause Analysis ──► 3. Log Post-Mortem ──► 4. Synthesize Rule ──► 5. Update Rulebase
+```
+
+1. **Capture Defect**: Record the failure symptoms and stack trace.
+2. **Root Cause Analysis**: Identify the fundamental architectural or operational gap (not just the surface symptom).
+3. **Log Post-Mortem**: Append an entry to [`docs/knowledge/issue_log.md`](../knowledge/issue_log.md) documenting Symptom, Root Cause, Anti-Pattern, and Resolution.
+4. **Synthesize Rule**: Formulate the preventative DO and DONT directives and add them to [`docs/knowledge/dos_and_donts.md`](../knowledge/dos_and_donts.md).
+5. **Update Rulebase**:
+   - If the issue falls under an existing domain rule in `docs/rules/<domain>.md`, update that rule immediately.
+   - If it represents a new domain, author a new atomic rule file and index it in [`AGENTS.md`](../../AGENTS.md).
+   - Run the configuration validation script to ensure integrity.
+
+---
+
+## 2. Institutional Memory Maintenance
+
+- **ADR Synchronization**: Major technical decisions must be logged in [`memory.md`](../../memory.md) before or immediately upon implementation.
+- **Knowledge Graph Updates**: Keep [`docs/knowledge/knowledge_graph.md`](../knowledge/knowledge_graph.md) synchronized with new services, database models, or adapters to avoid repetitive token-expensive codebase discovery in future sessions.