azcodr 1.2.2 → 1.4.0

package/docs/rules/agentic_configuration.md

@@ -1,6 +1,6 @@
-# Agentic Configuration, Skills & Harness Standards
+# Agentic Configuration, Governance & Harness Standards
 
-> **Core Mandate:** Maintain lean agent entrypoints via progressive disclosure, modular documentation, strict skill front matter standards, harness symlink parity, and relentless questioning during skill architecture.
+> **Core Mandate:** Enforce progressive disclosure across agent entrypoints, strict skill front matter standards, workspace sovereignty, continuous learning via the direct rule ingestion loop, and immutable Architectural Decision Records (ADRs).
 
 ---
 
@@ -37,14 +37,26 @@ Different AI agents and IDE harnesses look for different configuration filenames
 - Standard: `AGENTS.md`
 - Lowercase: `agents.md`
 - Anthropic Claude Code: `CLAUDE.md`
+- Google Antigravity & Gemini CLI: `GEMINI.md`
+- Cursor: `.cursorrules`
+- Windsurf: `.windsurfrules`
 
 **Standard:** Maintain identical configuration across all harnesses by establishing filesystem symbolic links:
 ```bash
 ln -sf AGENTS.md agents.md
 ln -sf AGENTS.md CLAUDE.md
+ln -sf AGENTS.md GEMINI.md
+ln -sf AGENTS.md .cursorrules
+ln -sf AGENTS.md .windsurfrules
 ```
 Never duplicate content into separate files.
 
+### Context Budget & Token Economy Directives
+To prevent LLM context exhaustion, attention dilution, and model degradation:
+- **Per-File Rule Size Cap (24 KB / 24,000 bytes):** Every rule file in `docs/rules/` must strictly stay under 24,000 bytes. Files exceeding this ceiling risk truncation across agent runtimes.
+- **Aggregate Rules Token Budget (20,000 tokens):** Continuous and directory-scoped rules share an aggregate budget. Over-budget rules are demoted to file-pointer references. Always use concise, actionable directives rather than prose tutorials.
+- **Progressive Offloading:** Offload deep specifications, schemas, or large lookup matrices to dedicated reference files loaded on demand.
+
 ---
 
 ## 4. Skills Architecture (`.agents/skills/<skill-name>/`)
@@ -71,9 +83,34 @@ description: <Imperative trigger description under 1024 characters. MUST start w
 - Include structured response templates and self-validation checklists for deterministic output.
 
 ### Progressive Disclosure Subdirectories
-- `references/`: Detailed sub-domain markdown files loaded on demand by the skill.
+Adhere strictly to the standard agent skills folder taxonomy:
 - `scripts/`: Deterministic executable scripts (bash, node, python) for tasks where LLMs produce non-deterministic drift.
-- `assets/`: Static data, lookup tables, schemas, or boilerplate templates.
+- `references/`: Detailed sub-domain markdown manuals loaded on demand by the skill.
+- `resources/`: Static templates, lookup tables, JSON schemas, or mock artifacts.
+- `examples/`: Reference implementations and concrete code patterns.
+
+### Deterministic Lifecycle Hooks (`.agents/hooks.json`)
+To enforce non-negotiable safety guardrails and automated verification without stochastic agent failure:
+- **`PreToolUse`**: Intercept destructive or dangerous CLI commands (`rm -rf`, DROP DATABASE, git push --force) and force explicit confirmation (`decision: ask`).
+- **`PostToolUse`**: Automatically trigger fast linters (`npm run lint`), formatters, or unit test verification after tool runs.
+- **`Stop`**: Intercept premature agent termination when background tasks are running or tests remain failing (`decision: continue`).
+
+### Model Context Protocol (MCP) Integration (`.agents/mcp_config.json`)
+When external tool capabilities are required (database introspectors, cloud telemetry, documentation search):
+- Standardize on vendor-neutral **Model Context Protocol (MCP)** specifications.
+- Declare local or containerized MCP tool servers in `.agents/mcp_config.json`.
+- Treat MCP tools as secondary adapter driving ports, keeping domain logic decoupled from proprietary platform APIs.
+
+### Explicit Prohibition: The "Library-as-a-Skill" Anti-Pattern
+Never author or dynamically generate skills for commodity open-source packages or libraries (e.g. `react`, `tanstack`, `shadcn`, `zustand`, `testing-library`, `vitest`):
+- **Prompt Bloat & Re-Explanation Tax:** Skill descriptions are continuously loaded into the agent's `<skills>` context. Proliferating skills for every library in a stack floods the prompt with thousands of redundant tokens and degrades model reasoning.
+- **Parametric Redundancy:** Frontier LLMs already possess extensive parametric knowledge of open-source library APIs. Re-explaining basic imports and function signatures in a skill wastes context and creates documentation rot.
+- **Trigger Collision & Agent Paralysis:** When a prompt touches UI, form validation, and data fetching, having 5 library skills triggers semantic collision, causing the agent to waste execution turns resolving which sub-skill to run.
+- **The 4-Layer Resolution Standard:** Always resolve library stack knowledge through the **4-Layer Resolution Model**:
+  1. *Layer 1 (Manifest Ground Truth):* Read `package.json`, `components.json`, or `tsconfig.json`.
+  2. *Layer 2 (Stack Contract in `AGENTS.md`):* 3–5 line declaration in project entrypoint stamped by `/lets-build`.
+  3. *Layer 3 (Universal Domain Rules):* Enforce architectural invariants (`frontend_architecture.md`, `test_driven_development.md`) rather than library syntax.
+  4. *Layer 4 (Tool & CLI Execution):* Direct execution of official CLIs (`npx shadcn@latest add ...`) or local component inspection.
 
 ---
 
@@ -111,38 +148,40 @@ Coding tasks and agentic skills exhibit an explicit **Many-to-Many ($M:N$) Relat
 - **Zero Cross-Contamination:** No skill may write code or modify files outside its declared functional boundary.
 - **Pure Function Semantics:** Analysis skills must remain read-only and side-effect free.
 
+## 6. The Mandatory YAGNI Gate Triad (Rules & Skills)
+
+LLM coding agents have a natural statistical bias toward **Instruction Creep** and **Eager Pattern Application**: when provided with a rule explaining an advanced pattern, agents reflexively apply it everywhere, causing severe architectural bloat.
+
+To prevent premature abstraction, every architectural pattern rule and skill must enforce the **YAGNI Gate Triad**:
+
+1. **The Simple Baseline (Day 1 Default):**
+   - The zero-overhead, default implementation that solves the immediate requirement without indirection (e.g. single database model before CQRS, relational indexes before Redis, standard React components before Server-Driven UI).
+2. **The Anti-Triggers (Strictly Forbidden Scenarios):**
+   - Explicit, negative conditions where applying the pattern or skill is forbidden as premature over-engineering (e.g. no caching for low-throughput queries, no state machines for 2-state boolean flags, no skills for routine typo fixes).
+3. **The Empirical Tipping Point (Graduation Threshold):**
+   - Measurable, verified criteria that MUST be breached before graduating to the pattern (e.g. p99 latency > 200ms after indexing, 3+ non-linear lifecycle states with transition guards, untrusted third-party user scripts).
+
+### Foundational Leverage vs. Speculative Over-Engineering
+A common misunderstanding is that YAGNI forbids using external libraries. **This is completely false**:
+- **YAGNI Attacks:** Speculative custom code, home-grown frameworks, custom wheel reinvention, and premature multi-tier distributed architectures.
+- **YAGNI Mandates:** Adopting battle-tested, open-source building blocks (`shadcn/ui`, `Tailwind CSS`, `Zod`, `TanStack Query`, `Lombok`) to solve concrete, present requirements with the minimum amount of custom code (preventing Not-Invented-Here / NIH syndrome).
+
 ---
 
-## 6. The Relentless Skill Architecture Inquiry
+## 7. The Relentless Skill Architecture Inquiry
 
 Never architect or modify a skill based on assumptions. Before authoring any `SKILL.md`, run the **7 Core Skill Inquiry Branches**:
 
-```
-[New Skill / Rule Request]
-       │
-       ▼
-[Branch 1: Placement] ────────── Should this be AGENTS.md, a Rule, or a Skill?
-       │
-       ▼
-[Branch 2: Trigger Boundaries] ── Exact 'Use when...' and explicit 'Do NOT use for...'?
-       │
-       ▼
-[Branch 3: Domain Ground Truth] ─ Have generic textbook tutorials been purged?
-       │
-       ▼
-[Branch 4: Gotchas & Anti-Patterns] What specific AI mistakes MUST be forbidden?
-       │
-       ▼
-[Branch 5: Determinism vs LLM] ── Should deterministic steps be scripts in scripts/?
-       │
-       ▼
-[Branch 6: Progressive Bloat] ─── Is SKILL.md < 500 lines with sub-docs in references/?
-       │
-       ▼
-[Branch 7: Verification Loop] ─── Are there output templates and self-checklists?
-       │
-       ▼
-[Ready to Author / Update Skill]
+```mermaid
+flowchart TD
+    Req["New Skill / Rule Request"] --> B1["Branch 1: Placement<br/>AGENTS.md, Rule, or Skill?"]
+    B1 --> B2["Branch 2: Trigger Boundaries<br/>Exact 'Use when...' & 'Do NOT use for...'?"]
+    B2 --> B3["Branch 3: Domain Ground Truth<br/>Generic textbook tutorials purged?"]
+    B3 --> B4["Branch 4: Gotchas & Anti-Patterns<br/>What AI mistakes MUST be forbidden?"]
+    B4 --> B5["Branch 5: Determinism vs LLM<br/>Deterministic steps scripted in scripts/?"]
+    B5 --> B6["Branch 6: Progressive Bloat<br/>SKILL.md < 500 lines with sub-docs in references/?"]
+    B6 --> B7["Branch 7: Verification Loop<br/>Output templates & self-checklists present?"]
+    B7 --> Ready["Ready to Author / Update Skill"]
 ```
 
 ### The 7 Core Inquiry Branches
@@ -159,10 +198,59 @@ Never architect or modify a skill based on assumptions. Before authoring any `SK
 
 ---
 
-## 7. The Continuous Refinement Loop
+## 8. The Continuous Refinement Loop
 
 When an AI produces suboptimal code or documentation:
 1. Preserve the original AI output draft.
 2. Make manual corrections to produce the desired gold-standard output.
 3. Diff the original draft against the corrected version to identify specific gaps.
 4. Update the relevant skill's "What NOT to do" or guideline section to prevent repeating that mistake.
+
+---
+
+## 9. Workspace Sovereignty & Zero Global Interference
+
+Enforce strict workspace containment within the workspace root (`./`):
+- **Ground Truth Boundary**: Only files, dependencies, configuration files (`package.json`, `tsconfig.json`, `docker-compose.yml`), and verified command executions within the local workspace (`./`) constitute project truth.
+- **Zero Global Contamination**: Never import, execute, or assume tools, environment variables, or conventions from global system directories (e.g. `~/.config`, `/tmp`, `~/.gemini/antigravity-cli`, or parent directories) unless explicitly defined within local workspace configuration.
+- **Sibling Project Isolation**: Strictly ignore external or legacy projects. Do not read from or write to directories outside the local repository (`./`).
+- **Subagent Context Sandboxing**: When spawning subagents or executing commands, ensure working directories are anchored strictly to `./`.
+
+---
+
+## 10. Continuous Learning & The Direct Rule Ingestion Loop
+
+Whenever an error, test failure, build friction, or architectural anti-pattern occurs during development, immediately execute the 4-step loop:
+
+```
+1. Capture Defect ──► 2. Root Cause Analysis ──► 3. Synthesize Invariant ──► 4. Update Rule / Skill
+```
+
+1. **Capture Defect**: Record the failure symptoms, stack trace, and failing test case.
+2. **Root Cause Analysis**: Identify the fundamental architectural or operational gap (not just the surface symptom).
+3. **Synthesize Invariant**: Formulate a concrete, positive architectural invariant and code example showing the correct implementation.
+4. **Update Rule / Skill**:
+   - Update the governing domain rule in `docs/rules/<domain>.md` or specialized skill in `.agents/skills/` directly.
+   - If the lesson introduces an architectural trade-off or paradigm shift, record a lightweight ADR in [`memory.md`](../../memory.md).
+   - Run verification (`npm test && npm run validate`) to ensure 100% integrity.
+
+---
+
+## 11. Architectural Decision Records (ADR) Standards
+
+Significant architectural, technical stack, or invariant decisions must be captured in [`memory.md`](../../memory.md):
+
+### Required ADR Envelope:
+```markdown
+#### ADR-XXX: <Imperative Action-Oriented Title>
+- **Date:** YYYY-MM-DD | **Status:** PROPOSED | ACCEPTED | SUPERSEDED | DEPRECATED
+- **Context:** The specific operational or technical problem, constraint, or trade-off requiring a decision.
+- **Decision:** Concrete, unambiguous architecture choice and positive invariants.
+- **Consequences:** Direct benefits and deliberate operational trade-offs accepted.
+- **Enforced In:** Links to specific rule files in `docs/rules/` or code paths.
+```
+
+### Numbering & Immutability:
+- ADR numbers are monotonically increasing (`ADR-001`, `ADR-002`, ...).
+- ADR entries are **immutable history**. Never edit past accepted ADRs to represent new decisions; author a new ADR that explicitly supersedes the former.
+

package/docs/rules/api_architecture.md

@@ -0,0 +1,179 @@
+# API Architecture, Protocols & Communication Standards
+
+> **Core Mandate:** Enforce standard HTTP semantics, synchronous vs. asynchronous processing (`202 Accepted`), capability metadata (`_actions`), safe mutations via idempotency keys, keyset cursor pagination, optimistic concurrency control (OCC), and RFC 8594 lifecycle versioning.
+
+---
+
+## 1. Standard HTTP Semantics & Status Codes
+
+APIs must adhere strictly to standard HTTP semantics. Never return `200 OK` for error envelopes:
+
+| Status Code | Semantic Purpose | When to Return |
+|---|---|---|
+| **`200 OK`** | Successful read or synchronous update | Standard `GET`, `PATCH`, `PUT` queries that return payloads. |
+| **`201 Created`** | Successful resource creation | Synchronous `POST` with `Location: /api/v1/resources/:id` header. |
+| **`202 Accepted`** | Asynchronous task accepted | Tasks exceeding latency budgets (> 1.5s) delegated to background queues. |
+| **`204 No Content`** | Successful action with zero payload | Standard `DELETE` or empty mutation responses. |
+| **`400 Bad Request`** | Malformed syntax or protocol violation | Unparseable JSON, invalid query parameters. |
+| **`401 Unauthorized`** | Missing or invalid authentication | Missing, expired, or tampered JWT / API token. |
+| **`403 Forbidden`** | Authenticated but insufficient permission | Role, tenant boundary, or policy guard denial. |
+| **`404 Not Found`** | Resource does not exist | Unknown entity identifier (or masked tenant resource). |
+| **`409 Conflict`** | State conflict or race condition | Concurrency mismatch (`If-Match`), unique constraint, or in-flight idempotency. |
+| **`422 Unprocessable`** | Semantic validation failure | Schema constraint violation (RFC 7807 problem details). |
+| **`500 Internal Error`** | Unhandled server exception | Unexpected server failure; never leak internal stack traces. |
+
+### Subresource URL Conventions
+- Express relational hierarchy cleanly: `/api/v1/organizations/:orgId/projects/:projectId/members`.
+- Limit URL nesting to a maximum of 2 subresource levels; for deeper resources, access directly via canonical ID (`/api/v1/tasks/:taskId`).
+
+### Enumeration Masking
+- Authentication and recovery endpoints must never reveal user existence (e.g. return `"If an account exists, a recovery link has been sent"` with identical timing).
+
+---
+
+## 2. Synchronous vs. Asynchronous Processing (`202 Accepted`)
+
+Operations with unpredictable or long execution durations (> 1.5 seconds, such as video rendering, large PDF exports, batch imports, or complex report generation) must never block synchronous HTTP request threads:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Client
+    participant Gateway as API Gateway
+    participant Queue as Task Queue / Worker
+    
+    Client->>Gateway: POST /reports/export (Long-running > 1.5s)
+    Gateway->>Queue: Dispatch background job
+    Gateway-->>Client: 202 Accepted (Location: /api/v1/tasks/tsk_123)
+    Note over Client,Gateway: Client polls GET /api/v1/tasks/tsk_123 until complete
+```
+
+### Protocol Standards:
+1. Dispatch the payload to a persistent worker queue (e.g., BullMQ, Temporal, Celery).
+2. Respond immediately with **`202 Accepted`** containing:
+   - Header: `Location: /api/v1/tasks/:taskId`
+   - Envelope:
+     ```json
+     {
+       "taskId": "tsk_123",
+       "status": "QUEUED",
+       "pollIntervalMs": 2000,
+       "_links": {
+         "status": { "href": "/api/v1/tasks/tsk_123", "method": "GET" },
+         "cancel": { "href": "/api/v1/tasks/tsk_123", "method": "DELETE" }
+       }
+     }
+     ```
+3. Polling endpoint (`GET /api/v1/tasks/:taskId`) returns:
+   - In-progress: `200 OK` with status `PROCESSING` and progress percentage.
+   - Finished: `303 See Other` with `Location: /api/v1/reports/rep_789` or `200 OK` with `status: "COMPLETED"` and the final artifact URI.
+
+---
+
+## 3. Allowed Actions & Capability Metadata (`_actions` Envelope)
+
+Clients must not duplicate complex server-side business and authorization rules to decide whether UI actions (edit, delete, approve, cancel, refund) are permitted. **The server is the authoritative source of truth.**
+
+### Pattern: `_actions` and `_links` Envelope
+Every resource response must embed an `_actions` boolean map and optional `_links` hypermedia block indicating what the requesting caller is permitted to do based on their role, tenant boundaries, and the entity's current lifecycle state:
+
+```json
+{
+  "id": "ord_9876",
+  "status": "SHIPPED",
+  "totalAmount": 149.99,
+  "currency": "USD",
+  "_actions": {
+    "canEdit": false,
+    "canCancel": false,
+    "canTrack": true,
+    "canRequestRefund": true
+  },
+  "_links": {
+    "self": { "href": "/api/v1/orders/ord_9876", "method": "GET" },
+    "track": { "href": "/api/v1/orders/ord_9876/tracking", "method": "GET" },
+    "refund": { "href": "/api/v1/orders/ord_9876/refunds", "method": "POST" }
+  }
+}
+```
+
+### Frontend Binding:
+- UI action buttons directly bind visibility or disabled state to `resource._actions.canCancel`.
+- When business logic evolves (e.g. orders over $1,000 require manager approval), only backend policy changes—zero frontend redeployment required.
+
+---
+
+## 4. Safe Mutations via Idempotency Keys (IETF Draft)
+
+To prevent duplicate execution (double charging, duplicate orders) caused by network retries or transient connection drops:
+
+### Protocol Standards:
+- Clients generating mutating requests (`POST`, `PATCH`) must supply a unique `Idempotency-Key: <uuid-v4>` header.
+- **Server Execution Lifecycle**:
+  1. Check distributed idempotency cache for key `idemp:<tenantId>:<idempotencyKey>`.
+  2. If found with status `IN_FLIGHT`: return **`409 Conflict`** (`IDEMPOTENT_OPERATION_IN_PROGRESS`).
+  3. If found with status `COMPLETED`: return the cached HTTP status code, headers, and response payload without re-executing.
+  4. If not found: Acquire distributed lock, execute mutation within an atomic database transaction, cache the response envelope with a 24-hour TTL, and release the lock.
+
+---
+
+## 5. High-Scale Keyset / Cursor-Based Pagination
+
+Never use offset pagination (`OFFSET 10000 LIMIT 20`) on large tables. Offsets degrade linearly ($O(N)$) and suffer from page-drift anomalies as rows are inserted or deleted.
+
+### Specification & Envelope:
+- Query Parameters: `?cursor=<opaque_base64>&limit=20` (default limit 20, max 100).
+- Response Envelope:
+  ```json
+  {
+    "data": [...],
+    "pagination": {
+      "nextCursor": "ZXlKaWRI...==",
+      "hasMore": true,
+      "limit": 20
+    }
+  }
+  ```
+- **Agnostic Keyset Query Pattern**:
+  ```sql
+  SELECT * FROM orders
+  WHERE tenant_id = :tenantId
+    AND (created_at, id) < (:cursorCreatedAt, :cursorId)
+  ORDER BY created_at DESC, id DESC
+  LIMIT :limit + 1;
+  ```
+  If `results.length > limit`, slice the extra item and encode its composite values (`created_at`, `id`) into the base64 `nextCursor`.
+
+---
+
+## 6. Optimistic Concurrency Control (OCC)
+
+Prevent lost-update anomalies during concurrent edits without pessimistic database row locking:
+
+### Protocol Standards:
+- Every mutable entity contains an incrementing integer `version` column.
+- The server returns the current entity version in the `ETag` response header: `ETag: W/"v4"`.
+- Clients submitting updates (`PUT`, `PATCH`) must include `If-Match: W/"v4"`.
+- **Atomic Concurrency Handling**:
+  ```sql
+  UPDATE orders 
+  SET status = :status, version = version + 1 
+  WHERE id = :id AND version = :expectedVersion;
+  ```
+  - If `rows_affected == 0`: Return **`409 Conflict`** with error code `CONCURRENCY_CONFLICT` and the latest entity representation.
+
+---
+
+## 7. API Versioning & RFC 8594 Lifecycle Deprecation
+
+### URI Versioning Standard
+- Standardize on explicit path versioning: `/v1/`, `/v2/`.
+- Never introduce breaking changes within an active major version:
+  - *Non-Breaking (Permitted in `/v1/`):* Adding optional fields, adding new endpoints, adding new enum variants.
+  - *Breaking (Demands `/v2/`):* Renaming/removing fields, changing validation constraints, altering status codes.
+
+### RFC 8594 Sunset & Deprecation Headers
+When deprecating an endpoint, provide clients with a minimum 90-day grace period:
+- `Deprecation: @<unix-timestamp>`: Date when the endpoint was deprecated.
+- `Sunset: <HTTP-date>`: Absolute date when the endpoint will return `410 Gone`.
+- `Link: </api/v2/docs>; rel="sunset"`: Link to migration documentation.

package/docs/rules/caching.md

@@ -4,20 +4,37 @@
 
 ---
 
-## 1. Abstract Cache Port & Cache-Aside Pattern
+## 1. The YAGNI Gate: Database First, Caching Second
 
-Application services interact with caching infrastructure through a swappable **Cache Port**, supporting any backend (Redis, Valkey, Dragonfly, KeyDB, Memcached, or in-memory LRU):
+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
 ```
-┌────────────────────────────────────────────────────────┐
-│ Cache Port Interface (Agnostic Contract)               │
-├────────────────────────────────────────────────────────┤
-│ get(key): Optional<String>                             │
-│ set(key, value, ttlSeconds): void                      │
-│ delete(key): void                                      │
-│ deletePattern(pattern): void                           │
-│ acquireLock(lockKey, ttlMs): boolean                   │
-└────────────────────────────────────────────────────────┘
+
+---
+
+## 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
@@ -38,7 +55,7 @@ For high-throughput cache regeneration, employ the **XFetch algorithm** (probabi
 
 ---
 
-## 2. Key Namespacing & Event-Driven Invalidation
+## 3. Key Namespacing & Event-Driven Invalidation
 
 - **Universal Key Hierarchy**: Structure all keys hierarchically:
   `tenant:{tenantId}:{entity}:{entityId}` (e.g. `tenant:123:order:987`)
@@ -46,7 +63,7 @@ For high-throughput cache regeneration, employ the **XFetch algorithm** (probabi
 
 ---
 
-## 3. HTTP Conditional Caching (ETags)
+## 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/cloud_native.md

@@ -28,16 +28,14 @@ All application processes and containers must handle graceful termination:
 - 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                │
-└────────────────────────────────────────────────────────┘
+```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
 ```