azcodr 1.2.2 → 1.4.0

package/docs/rules/multitenancy_isolation.md

@@ -1,88 +0,0 @@
-# Multi-Tenancy Context Resolution & Data Isolation Models
-
-> **Core Mandate:** Enforce multi-tenancy isolation through dynamic context resolution combined with database-agnostic isolation models (AST query interceptors, RLS, schema namespaces, or connection routing) as an immutable backstop.
-
----
-
-## 1. Multi-Tenant Context Resolution
-
-Resolve tenant identity dynamically in an inbound gateway or middleware pipeline in strict priority order:
-1. **Host Subdomain**: `subdomain.app.com` (extracted via hostname regex).
-2. **Explicit Headers**: `X-Tenant-ID: <uuid>` or `X-Tenant-Slug: <slug>`.
-3. **Path Prefix**: `/t/:tenantSlug/...`.
-4. **JWT Claim Fallback**: Authenticated token `tid` (tenant ID) claim.
-
-*Validation:* If the resolved tenant does not exist or is in `SUSPENDED` status, immediately return **`403 Forbidden`** (`TENANT_SUSPENDED` or `TENANT_INVALID`). Propagate `TenantContext` across service calls using standard W3C Baggage headers or request contexts.
-
-- **Fail-Closed Multi-Tenancy Invariant**: Never trust client-supplied tenant headers (`X-Tenant-ID`) without cryptographically verifying that the authenticated session actor actually belongs to the requested tenant organization/workspace. Mismatched tenant headers must immediately fail closed with HTTP 403 `FORBIDDEN_TENANT_ACCESS`.
-
----
-
-## 2. Four Universal Data Isolation Models
-
-Never rely solely on application developers remembering to manually append `WHERE tenant_id = ?`. Standardize on one of four architectural isolation strategies:
-
-```mermaid
-flowchart TD
-  Request["Inbound Request (TenantContext)"] --> Strategy{"Isolation Strategy"}
-  
-  Strategy -->|"Model 1: Discriminator AST"| AST["Query Interceptor / AST Rewriter\n(Automatically injects tenant_id into AST before DB execution)"]
-  Strategy -->|"Model 2: Engine RLS"| RLS["Row-Level Security (RLS)\n(Database session config: current_setting / session variable)"]
-  Strategy -->|"Model 3: Schema Namespace"| Schema["Schema-per-Tenant\n(SET search_path / USE tenant_schema)"]
-  Strategy -->|"Model 4: Instance Routing"| Pool["Database-per-Tenant\n(Connection pool router per tenant ID)"]
-
-  AST --> Database[(Any Relational / Document DB)]
-  RLS --> Database
-  Schema --> Database
-  Pool --> Database
-```
-
-### Model 1: Universal AST Query Interceptor (Engine-Agnostic)
-The persistence layer interceptor parses the query Abstract Syntax Tree (AST) at runtime and automatically enforces `tenant_id = current_tenant` for all reads and mutations. Compatible with all ANSI SQL and NoSQL engines.
-
-### Model 2: Database Row-Level Security (RLS)
-For engines supporting native RLS (e.g. PostgreSQL, Oracle):
-```sql
-ALTER TABLE "Order" ENABLE ROW LEVEL SECURITY;
-ALTER TABLE "Order" FORCE ROW LEVEL SECURITY;
-
-CREATE POLICY order_tenant_isolation ON "Order"
-  FOR ALL
-  USING (tenant_id = current_setting('app.tenant_id', true)::uuid)
-  WITH CHECK (tenant_id = current_setting('app.tenant_id', true)::uuid);
-```
-> [!IMPORTANT]
-> **Connection Pool Safety:** Always set `is_local = true` when configuring session variables (`set_config('app.tenant_id', id, true)`). This restricts settings strictly to the current database transaction, preventing cross-tenant leakage in connection pools.
-
-### Model 3: Schema-per-Tenant
-Separate schemas per tenant within a shared database instance (`tenant_acme`, `tenant_globex`). Routing dynamically sets the active search path per transaction.
-
-### Model 4: Database-per-Tenant
-Dedicated physical database instances per enterprise tenant, selected by a dynamic connection pool resolver based on resolved tenant metadata.
-
----
-
-## 3. Polyglot Adapter Interceptor Contract
-
-Adapters in any language (Go, Rust, Python, Java, TypeScript) must expose an interceptor wrapping the data access layer:
-
-```
-┌────────────────────────────────────────────────────────┐
-│ Context Interceptor Contract (Pseudocode / Polyglot)   │
-├────────────────────────────────────────────────────────┤
-│ onQueryExecution(query, tenantContext):                │
-│   assert(tenantContext != null, "MissingTenantContext")│
-│   if adapter.supportsRLS():                            │
-│     execute("SET LOCAL app.tenant_id = :tenantId")     │
-│   else if adapter.supportsAST():                       │
-│     query.addPredicate(EQUALS("tenant_id", tenantId))  │
-│   return execute(query)                                │
-└────────────────────────────────────────────────────────┘
-```
-
----
-
-## 4. Tenant Lifecycle Management
-
-- **Atomic Provisioning**: Tenant creation must run inside an atomic transaction (provision tenant record, seed default RBAC roles `ADMIN`/`MEMBER`, assign subscription tier).
-- **GDPR Cascading Deletion**: Deleting a tenant triggers an asynchronous job that cascade purges or pseudonymizes all tenant records, ensuring zero orphaned data.

package/docs/rules/react.md

@@ -1,78 +0,0 @@
-# React & Modern Frontend Architecture
-
-> **Core Mandate:** Enforce modern, production-grade React standards across all web interfaces: `shadcn/ui` with Radix UI primitives, TanStack Query for server-state caching, React Hook Form / TanStack Form with Zod validation, and zero ad-hoc `useState` forms or raw `useEffect` fetch loops.
-
----
-
-## 1. Component Library & Styling (`shadcn/ui` + Radix UI)
-
-- **Accessible Radix Primitives**: All interactive UI components (dialogs, dropdowns, selects, tabs, tooltips, popovers) must be built on `@radix-ui` headless primitives or `shadcn/ui` components located in `@/components/ui/`.
-- **Zero Unstyled Raw Elements**: Never create unstyled raw HTML modals, dropdowns, or custom select tags.
-- **Tailwind Utility Styling (`cn` helper)**: Combine Tailwind utility classes using `clsx` and `tailwind-merge` (`cn(...)`) to allow clean prop overrides and consistent theming.
-- **Strict Prohibition of Native Dialogs**: As mandated in [`docs/rules/accessibility.md`](./accessibility.md), `window.alert()` and `window.confirm()` are strictly forbidden. Use accessible Radix UI dialogs (`<ConfirmDialog />`).
-
----
-
-## 2. Server State & Data Fetching (TanStack Query)
-
-- **Mandatory TanStack Query**: All asynchronous data fetching, caching, and mutation must use **TanStack Query (`@tanstack/react-query`)**.
-- **No Raw `useEffect` Fetch Loops**:
-  - *Anti-Pattern:* `useEffect(() => { fetch(...).then(setData) }, [])` with manual `loading` and `error` state.
-  - *Standard Pattern:*
-    ```tsx
-    const { data: resources, isLoading, error } = useQuery({
-      queryKey: ['resources', tenantId],
-      queryFn: () => api.getResources(),
-    });
-    ```
-- **Declarative Mutations & Invalidation**:
-  - Mutations must define `useMutation` with `onSuccess` cache invalidation:
-    ```tsx
-    const queryClient = useQueryClient();
-    const createResourceMutation = useMutation({
-      mutationFn: (newResource: CreateResourceInput) => api.createResource(newResource),
-      onSuccess: () => {
-        queryClient.invalidateQueries({ queryKey: ['resources'] });
-      },
-    });
-    ```
-- **Query Key Conventions**: Format query keys hierarchically as tuples: `['entity', id, ...filters]`, e.g., `['orders', orderId]`, `['users', tenantId]`.
-
----
-
-## 3. Form State Management & Validation (Zod + Form Engines)
-
-- **Mandatory Schema Validation**: Every form submission must be validated against a formal **Zod schema** (`z.object({ ... })`) that mirrors the shared DTO/input contracts from shared packages.
-- **Form State Engines**: Use **React Hook Form (`react-hook-form` + `@hookform/resolvers/zod`)** or **TanStack Form (`@tanstack/react-form`)**.
-- **Zero Unvalidated `useState` Multi-Field Objects**:
-  - *Anti-Pattern:*
-    ```tsx
-    const [form, setForm] = useState({ name: '', email: '' });
-    // manual validation in submit handler...
-    ```
-  - *Standard Pattern:*
-    ```tsx
-    const form = useForm<CreateUserInput>({
-      resolver: zodResolver(createUserSchema),
-      defaultValues: { name: '', email: '' },
-    });
-    ```
-- **Accessible Error Linking**: Form inputs must bind validation errors to `aria-invalid="true"` and `aria-describedby="<field>-error"`.
-
----
-
-## 4. State Separation & Data Tables
-
-- **State Hierarchy**:
-  1. **Server State (Remote)**: Manage exclusively with **TanStack Query**.
-  2. **URL State (Search / Pagination / Filters)**: Manage in URL search params per [`docs/rules/ui_navigation.md`](./ui_navigation.md).
-  3. **Form State (Transient Edits)**: Manage via **React Hook Form / TanStack Form**.
-  4. **Global Client State (Session/UI)**: Manage via **Zustand** (or React Context for theme/auth).
-- **Data Grids & Tables**: When building sortable, paginated, or virtualized tables, standardize on **TanStack Table (`@tanstack/react-table`)**.
-
----
-
-## 5. Theme Architecture & Design Token Completeness
-
-- **Symmetric Design Tokens**: Ensure foundational CSS variables (`--background`, `--foreground`, `--card`, `--border`, `--popover`) are symmetrically declared across `:root` and `.dark`. Omitted root tokens in `.dark` result in unstyled backgrounds and illegible text when switching themes.
-- **System Preference Detection & Reactive Synchronization**: `ThemeProvider` implementations must listen to `window.matchMedia('(prefers-color-scheme: dark)')` with dynamic event listeners so OS appearance toggles seamlessly propagate in real-time, and synchronize `document.documentElement.style.colorScheme = resolvedTheme` to ensure browser-native elements (scrollbars, input widgets) match the active theme.

package/docs/rules/rest_api_conventions.md

@@ -1,46 +0,0 @@
-# REST API Design & Response Conventions
-
-> **Core Mandate:** Enforce standardized RESTful conventions, proper HTTP status codes, enumeration masking, and consistent subresource routing.
-
----
-
-## 1. HTTP Status Code Conventions
-
-- **`200 OK`**: Successful GET, PUT, or PATCH requests returning modified state.
-- **`201 Created`**: Successful resource creation via POST (must include `Location` header or created entity).
-- **`204 No Content`**: Successful DELETE operations or operations returning no body.
-- **`400 Bad Request`**: Malformed payload or validation schema failure.
-- **`401 Unauthorized`**: Missing, expired, or invalid authentication credentials.
-- **`403 Forbidden`**: Authenticated caller lacks permissions, tenant is suspended, or action targets protected system roles.
-- **`404 Not Found`**: Resource does not exist or belongs to another tenant (enumeration masking).
-- **`409 Conflict`**: Unique constraint collision or concurrent optimistic lock conflict.
-- **`422 Unprocessable Entity`**: Semantic domain violation.
-- **`429 Too Many Requests`**: Rate limit exceeded.
-- **`500 Internal Server Error`**: Unexpected server error.
-
----
-
-## 2. Cross-Tenant Enumeration Masking
-
-- If an authenticated user attempts to access a resource ID belonging to a different tenant, the API must return **`404 Not Found`** (rather than `403 Forbidden`) to prevent leaking the existence of other tenants' records.
-
----
-
-## 3. Subresource Endpoints & Pluralization
-
-- Always use pluralized nouns for resources (e.g. `/api/v1/users`, `/api/v1/orders`).
-- Use nested subresources for closely owned relations:
-  - `/api/v1/roles/:id/permissions`
-  - `/api/v1/tenants/:id/members`
-
----
-
-## 4. Full Lifecycle Resource CRUD & Route Tolerances
-
-- **Full Lifecycle Support:** All primary resource endpoints must provide comprehensive CRUD capabilities before completion:
-  - `GET /api/v1/<resources>`: List with pagination and tenant filtering.
-  - `GET /api/v1/<resources>/:id`: Detailed record by ID.
-  - `POST /api/v1/<resources>`: Create new entity returning `201 Created`.
-  - `PUT /api/v1/<resources>/:id` or `PATCH`: Update attributes or mutate state machine status.
-  - `DELETE /api/v1/<resources>/:id`: Remove or archive returning `204 No Content`.
-- **Defensive Route Tolerances for Infrastructure Probes:** Operational probes (`/healthz`, `/readyz`) must defensively support trailing slashes (`/healthz/`) and common typos (`/healtz/`) to prevent reverse proxy routing mismatches between frontend dev servers (e.g. Vite) and ingress gateways.

package/docs/rules/tenant_dynamic_schemas.md

@@ -1,88 +0,0 @@
-# Multi-Tenant Schema Extensibility & Virtual Entities
-
-> **Core Mandate:** Enforce dynamic schema extensibility via hybrid relational columns and validated JSON Schema (Draft 2020-12), prohibiting sparse nullable columns and branch-specific migrations in shared databases.
-
----
-
-## 1. Hybrid Core + JSON/Document Extensibility
-
-Store universal relational attributes in standard typed columns. Store tenant-specific custom fields in a semi-structured `custom_attributes` column governed by tenant-scoped JSON Schemas:
-
-```sql
-CREATE TABLE customers (
-  id VARCHAR(64) PRIMARY KEY,
-  tenant_id VARCHAR(64) NOT NULL,
-  first_name VARCHAR(100) NOT NULL,
-  last_name VARCHAR(100) NOT NULL,
-  email VARCHAR(255) NOT NULL,
-  custom_attributes TEXT NOT NULL DEFAULT '{}',
-  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
-);
-
-CREATE TABLE tenant_schema_definitions (
-  id VARCHAR(64) PRIMARY KEY,
-  tenant_id VARCHAR(64) NOT NULL,
-  entity_name VARCHAR(50) NOT NULL,
-  json_schema TEXT NOT NULL,
-  version INT NOT NULL DEFAULT 1,
-  UNIQUE(tenant_id, entity_name)
-);
-```
-
-### Runtime Validation Contract (JSON Schema Draft 2020-12)
-Validate all inbound custom attribute payloads at runtime against the tenant's compiled JSON Schema before persisting mutations:
-
-```
-┌────────────────────────────────────────────────────────┐
-│ Dynamic Schema Validator Contract (Agnostic)           │
-├────────────────────────────────────────────────────────┤
-│ validateCustomAttributes(schemaDef, data):             │
-│   compiledValidator = compileJsonSchema(schemaDef)     │
-│   result = compiledValidator.validate(data)           │
-│   if !result.isValid:                                  │
-│     return Failure(ValidationError(result.errors))     │
-│   return Success(data)                                 │
-└────────────────────────────────────────────────────────┘
-```
-Supported natively by open-source engines in every major language (`valico` in Rust, `gojsonschema` in Go, `jsonschema` in Python, `networknt` in Java, `ajv` in Node).
-
----
-
-## 2. Meta-Schema Catalog for Virtual Custom Entities
-
-When tenants define completely custom entities/tables dynamically without deploying code:
-
-```sql
-CREATE TABLE tenant_entities (
-  id VARCHAR(64) PRIMARY KEY,
-  tenant_id VARCHAR(64) NOT NULL,
-  name VARCHAR(64) NOT NULL,
-  display_name VARCHAR(128) NOT NULL,
-  schema_definition TEXT NOT NULL,
-  UNIQUE(tenant_id, name)
-);
-
-CREATE TABLE tenant_records (
-  id VARCHAR(64) PRIMARY KEY,
-  tenant_id VARCHAR(64) NOT NULL,
-  entity_id VARCHAR(64) NOT NULL REFERENCES tenant_entities(id) ON DELETE CASCADE,
-  data TEXT NOT NULL DEFAULT '{}',
-  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
-);
-```
-
----
-
-## 3. Indexing Strategies for Dynamic Custom Attributes
-
-1. **Virtual / Generated Columns**: For high-throughput queried fields inside dynamic attributes, project them into virtual/generated columns and attach standard B-tree indexes:
-   ```sql
-   ALTER TABLE customers ADD COLUMN vat_number VARCHAR(64) 
-     GENERATED ALWAYS AS (custom_attributes->>'vat_number') STORED;
-   CREATE INDEX idx_customers_vat ON customers (tenant_id, vat_number);
-   ```
-2. **Functional / Expression Indexes**: Index specific nested attributes directly on engines that support expression indexes:
-   ```sql
-   CREATE INDEX idx_customers_po ON customers (tenant_id, ((custom_attributes->>'po_number')::text));
-   ```
-3. **Inverted Indexes**: Use generalized inverted indexing (e.g. GIN in PostgreSQL) for arbitrary key-value path searches.

package/docs/rules/tenant_pluggable_logic.md

@@ -1,59 +0,0 @@
-# Pluggable Multi-Tenant Business Logic & Workflows
-
-> **Core Mandate:** Eliminate `if-tenant` conditional branching via Strategy registries, Common Expression Language (CEL), durable workflow orchestration, and secure WebAssembly (Wasm) micro-sandboxes.
-
----
-
-## 1. Strategy Pattern & Dynamic Strategy Registry
-
-Encapsulate diverging tenant algorithms into discrete strategies conforming to a unified domain port:
-
-```
-┌────────────────────────────────────────────────────────┐
-│ Discount Strategy Port Contract                        │
-├────────────────────────────────────────────────────────┤
-│ calculateDiscount(order): Decimal                      │
-└────────────────────────────────────────────────────────┘
-```
-
-The application maintains an in-memory Strategy Registry resolving the active strategy based on `tenant.subscriptionTier` or custom tenant config:
-
-```
-StrategyRegistry.register("standard", StandardDiscountStrategy)
-StrategyRegistry.register("enterprise_vip", HighVolumeTierStrategy)
-
-strategy = StrategyRegistry.resolve(tenant.discountStrategyKey)
-discount = strategy.calculateDiscount(order)
-```
-
----
-
-## 2. Declarative Rule Evaluation: Common Expression Language (CEL)
-
-Allow tenants or administrators to configure dynamic conditional logic stored as declarative text or JSON without redeploying binaries. Standardize on **Common Expression Language (CEL)**:
-
-```cel
-// Example Tenant Rule Expression:
-order.total >= 500 && order.shipping_country == "US" && tenant.tier == "ENTERPRISE"
-```
-
-- **Memory-Safe & Non-Turing Complete**: Prevents infinite loops, recursion crashes, and side-effects.
-- **Polyglot Portability**: Native compilers and runtimes available across Go (`cel-go`), Rust (`cel-rust`), Python (`cel-python`), Java (`cel-java`), and TypeScript (`cel-js`).
-
----
-
-## 3. Durable Workflows & Orchestration (Temporal / BPMN 2.0)
-
-For tenants with diverging multi-step approval, fulfillment, or refund lifecycles:
-- **Durable Execution Engines**: Standardize on **Temporal.io** or **Camunda 8 / Zeebe (BPMN 2.0)**.
-- **Resilience Guarantees**: Workflows automatically persist state across node crashes, manage timeouts, execute automatic retries, and trigger compensation transactions (Saga pattern) across polyglot workers.
-- **Tenant Workflow Selection**: The domain routes entity state transitions to tenant-specific workflow IDs configured in database metadata.
-
----
-
-## 4. Secure Script Sandboxing: WebAssembly (Wasm / Extism)
-
-Never execute untrusted tenant strings via host runtime evaluation (`eval()`, dynamic reflection, or unshielded isolates).
-- **Universal Sandboxing with Extism / Wasmtime**: Tenants compile custom logic (in Rust, Go, Python, or TypeScript) to portable `.wasm` bytecode.
-- **Strict Execution Quotas**: Max 50ms CPU execution budget, max 16MB linear memory boundary.
-- **Complete Host Isolation**: Sandboxed instances possess zero access to host filesystem, network sockets, environment variables, or database connections unless explicitly passed via memory interfaces.

package/docs/rules/test_isolation.md

@@ -1,26 +0,0 @@
-# Test Coverage, Isolation & Determinism
-
-> **Core Mandate:** Enforce 100.00% test coverage thresholds, transactional database rollback per test, deterministic data factories, and zero-sleep flakiness elimination across all test suites.
-
----
-
-## 1. Mandatory 100.00% Test Coverage Thresholds
-
-- **Strict Coverage Thresholds**: Maintain line, function, branch, and statement test coverage at **100.00%** across all backend domain logic, adapters, contracts, and frontend suites. Strictly enforce 100% threshold failure gates in CI pipelines.
-- **Exhaustive Status Codes & Error Branches**: Explicitly test all HTTP/gRPC response codes:
-  - Success: `200 OK`, `201 Created`, `204 No Content`
-  - Client Errors: `400 Bad Request`, `401 Unauthorized`, `403 Forbidden`, `404 Not Found`, `409 Conflict`, `422 Unprocessable Entity`, `429 Too Many Requests`
-  - Server Failures: `500 Internal Server Error`, `503 Service Unavailable`
-- **UI Interaction States & Edge Cases**: Fully assert all presentation states (loading spinners, disabled controls, error banners, success feedback, empty states) across suites.
-
----
-
-## 2. Database Test Isolation & Zero Flakiness
-
-- **Transactional Rollback per Integration Test**:
-  - Every integration test that interacts with persistence must execute within a scoped transaction that is rolled back upon test completion (`afterEach` rollback) or use ephemeral, disposable database isolates. Never leave mutated rows that pollute subsequent tests.
-- **Deterministic Test Data Factories**:
-  - Utilize strongly-typed test data factories (`buildUser()`, `buildOrder()`) with randomized unique identifiers rather than hardcoded magic strings or fixed database IDs.
-- **Zero Sleep / Flakiness Elimination**:
-  - Strictly forbid arbitrary `sleep()` or timeout pauses in tests.
-  - Rely exclusively on deterministic condition polling (`waitFor(condition)`) or reactive event promises to eliminate test flakiness.

package/docs/rules/typescript.md

@@ -1,55 +0,0 @@
-# Static Type Safety & Sound Type Systems
-
-> **Core Mandate:** Enforce maximum compiler strictness, branded nominal typing for domain identifiers, strict prohibition of untyped escape hatches, and automated pre-commit quality guardrails across polyglot implementations.
-
----
-
-## 1. Maximum Compiler Strictness & Soundness
-
-Regardless of the execution language chosen for an adapter or service, enforce maximum compiler rigor to eliminate runtime null pointer exceptions, unhandled type cases, and memory errors at compile time:
-
-- **TypeScript**: Enable all strict compiler flags (`strict: true`, `noImplicitAny: true`, `strictNullChecks: true`, `noUncheckedIndexedAccess: true`).
-- **Rust**: Enable `#![deny(clippy::all)]` and `#![deny(missing_docs)]` with zero `unsafe` blocks.
-- **Go**: Enable comprehensive static analysis (`golangci-lint` with `errcheck`, `govet`, `staticcheck`).
-- **Python**: Enforce strict type checking (`mypy --strict` or `pyright`).
-
----
-
-## 2. Branded Nominal Typing & Primitive Obsession Elimination
-
-Prevent accidental mixing of raw primitive identifiers (e.g. passing an arbitrary `string` representing a `TenantId` where a `UserId` is expected) by enforcing nominal types:
-
-```
-┌────────────────────────────────────────────────────────┐
-│ Nominal Domain Identifier Pattern (Polyglot)           │
-├────────────────────────────────────────────────────────┤
-│ Rust:       struct TenantId(String);                   │
-│             struct UserId(String);                     │
-│ Go:         type TenantId string                       │
-│             type UserId string                         │
-│ TypeScript: type TenantId = Brand<string, 'TenantId'>; │
-│             type UserId = Brand<string, 'UserId'>;     │
-│ Python:     TenantId = NewType('TenantId', str)        │
-│             UserId = NewType('UserId', str)            │
-└────────────────────────────────────────────────────────┘
-```
-
-Domain functions must accept and return branded types rather than raw primitive strings or integers.
-
----
-
-## 3. Strict Prohibition of Untyped Escape Hatches
-
-- **Zero Tolerance for Unsound Types**: Strictly prohibit `any` in TypeScript, raw `interface{}` / `any` without type assertion checks in Go, raw `Any` in Python, or unchecked casts in Java/Rust.
-- **Runtime Validation at Boundaries**: External payloads (network requests, message queues, disk files) must be parsed and narrowed into strongly-typed domain structures before passing to application services.
-- **Commit Guardrails**: Enforce Conventional Commits via commit linters. Never bypass pre-commit hooks running static type checking, formatting, and linters.
-
----
-
-## 4. Module Path Aliases & Relative Traversal Elimination
-
-- **Path Alias Mandate (`@/*`)**: All TypeScript packages in the workspace must configure and standardize on `@/*` mapped to `./src/*` across `tsconfig.json` (`"baseUrl": "."`, `"paths": { "@/*": ["./src/*"] }`), bundlers (Vite `resolve.alias`), and test runners (Vitest `resolve.alias`).
-- **Strict Prohibition of Deep Relative Traversal**: Never use deep relative traversals (`../../../..`, `../../..`, `../..`) across layers or contexts. Deep relative paths create fragile coupling, impair refactoring, and obscure domain layer boundaries.
-- **Node.js ESM Production Resolution**: In backend environments executing compiled JavaScript under Node.js ESM (`node dist/index.js`), use `tsc-alias` post-compilation (`tsc && tsc-alias`) to resolve path aliases in `dist/` to valid relative paths without introducing runtime loader overhead.
-- **Scope of Sibling Imports**: Local relative imports (`./file.js`) are permitted only for immediate siblings within the identical directory. Any import traversing up a directory hierarchy or crossing architectural boundaries (domain, ports, adapters, components, context) MUST resolve via `@/*`.
-

package/docs/rules/ui_navigation.md

@@ -1,20 +0,0 @@
-# UI Navigation & URL State Synchronization
-
-> **Core Mandate:** Enforce bidirectional URL state synchronization for all interactive view states, preserving deep linkability, bookmarkability, and native browser navigation.
-
----
-
-## 1. Bidirectional URL State Synchronization
-
-Every view state that represents navigation, active tab, filtering, sorting, pagination, or search query must synchronize bidirectionally with URL search parameters (`useSearchParams`):
-- **Bookmarkability**: A user copying the browser URL must be able to restore the exact view, active tab, filter selections, and pagination page on any device.
-- **Browser History Integration**: The browser's back and forward buttons must navigate between state transitions smoothly without triggering full page reloads.
-
----
-
-## 2. Deep Linking Standards
-
-- **Tabbed Interfaces**: Encode active tab keys in query params (e.g. `?tab=security` or `/settings/security`).
-- **Data Tables & Lists**: Preserve table states in URL parameters:
-  - `?page=2&limit=25&sort=createdAt&order=desc&status=ACTIVE`
-- **Modal & Drawer States**: If a modal or drawer represents an actionable sub-view (e.g. `?modal=edit-user&userId=123`), synchronize it with the URL so direct links open the intended context.

package/docs/rules/upstream_synchronization.md

@@ -1,53 +0,0 @@
-# Upstream Baseline Synchronization & changes.md Ledger
-
-> **Core Mandate:** Upstream template/baseline workspaces (`azcodr`) must remain strictly untouched during project development. When generic architectural improvements, rule refinements, or post-mortems are identified, record them solely into the `changes.md` ledger with zero automated repo merging or baseline contamination.
-
----
-
-## 1. The Baseline-Project Decoupling Principle
-
-Workspaces operate under a clean, decoupled flow:
-
-```
-[Upstream Generic Baseline: azcodr]
-               │
-               ▼  (Scaffolded via npx azcodr)
-[Derived Project Workspace: my-app / others]
-               │
-               │  (Accumulates project code, specificities, and institutional lessons)
-               │
-               ▼  (Record reusable improvements)
-[Upstream Changes Ledger: changes.md]
-```
-
-- **Pristine Upstream Mandate:** Never edit, commit, or attempt automated git merges to an upstream baseline repository during routine project development, feature implementation, or bug fixes.
-- **Ledger-Only Synchronization:** When generic architectural discoveries or defect post-mortems occur, document them cleanly in `changes.md` at the workspace root. No automated merge AI or remote repo synchronization is executed.
-
----
-
-## 2. Zero-Contamination Invariant (Generic vs. Specific)
-
-When logging proposed changes into `changes.md`, enforce strict domain filtering:
-
-| Element Category | Keep in Specific Project Workspace | Allow in changes.md for Upstream (`azcodr`) |
-|---|---|---|
-| **Domain Entities** | Concrete business models (`Order`, `Customer`, `Invoice`, etc.) | Abstract archetypes (`Entity`, `Aggregate`, `ValueObject`, `Resource`) |
-| **Tech Stack / Adapters** | Concrete choices (Prisma, SQLite dev, PostgreSQL prod, Vite React) | Hexagonal Ports, abstract repository contracts, polyglot adapter guidance |
-| **Architectural Rules** | Specific entity validation, specific route paths | Universal invariants (5-Phase Agile Lifecycle, SemVer trigger matrix, FK dropdowns) |
-| **ADRs** | Stack decisions (`ADR-006: Target Tech Stack for Project`) | Generic architecture patterns (`ADR-007` to `ADR-010`) |
-| **Test Suites** | Concrete domain tests (`order_domain.test.ts`, domain-specific suites) | Boundary smoke test pattern (`scripts/smoke_test.sh`), 100% coverage gate |
-
----
-
-## 3. Atomic changes.md Entry Protocol
-
-Every upstream-bound proposal logged to `changes.md` must follow the standardized format:
-
-```markdown
-### [YYYY-MM-DD] <Title of Change>
-- **Category:** Rule | Skill | Infrastructure | CLI | Knowledge Hub
-- **Target File(s):** `docs/rules/...`, `.agents/skills/...`, etc.
-- **Rationale:** Why this improvement is necessary or valuable across all enterprise projects.
-- **Description:** Concise summary of the mutation or invariant added.
-- **Domain Filter Verification:** Verified 100% generic; purged of all project-specific business entities and models.
-```

package/docs/rules/workspace_isolation.md

@@ -1,25 +0,0 @@
-# Workspace Isolation & Zero Global Context Interference
-
-> **Core Mandate:** Enforce strict workspace containment within the workspace root (`./`), strictly prohibiting any leakage, interference, or unverified assumptions from global configurations, external directories, or sibling projects.
-
----
-
-## 1. Principle of Workspace Sovereignty
-
-- **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 all external or legacy projects. Do not read from or write to directories outside the local repository (`./`).
-
----
-
-## 2. Dependency & Tooling Isolation
-
-- **Local Package Manager**: Standardize strictly on local workspace dependencies managed via `npm` within this workspace. Never rely on global npm packages (`npm install -g`).
-- **Container Network Containment**: All Docker containers and bridge networks must be named and scoped specifically to this project (e.g. `azcodr_network`, `azcodr_postgres`) to prevent port collisions or cross-project data leakage.
-
----
-
-## 3. Subagent & Execution Context Sandboxing
-
-- When spawning subagents or executing commands, ensure the working directory (`Cwd`) is anchored strictly to the workspace root (`./`).
-- Subagents must never carry over assumptions from other workspaces or global memory pools.