azcodr 1.0.0

package/docs/knowledge/knowledge_graph.md

@@ -0,0 +1,188 @@
+# System Knowledge Graph & Architectural Topology
+
+> **Core Purpose:** High-density, token-efficient knowledge representation of the workspace architecture, data topologies, and subsystem boundaries, eliminating repetitive discovery prompts.
+
+---
+
+## 1. Universal Hexagonal Architectural Subsystems
+
+```mermaid
+flowchart TD
+  subgraph Ingress["Client & Primary Ingress Adapters"]
+    UI["Multi-Platform Client (Web / Mobile / Desktop SDUI)"]
+    Gateway["Ingress Gateway / Envoy (REST / gRPC / SSE)"]
+    BrokerIn["Message Consumer (Kafka / NATS / RabbitMQ)"]
+  end
+
+  subgraph Core["Pure Invariant Domain Core (Hexagonal Ports)"]
+    direction TB
+    TenantContext["Multi-Tenant Context Resolver Port"]
+    AuthPort["Authentication & Identity Port"]
+    AuthzPort["Authorization & Policy Port"]
+    DomainServices["Domain Services & Aggregate Roots"]
+    RulePort["Dynamic Rule Engine Port (CEL / Wasm)"]
+    WorkflowPort["Workflow Orchestration Port (Temporal / BPMN)"]
+    OutboxPort["Transactional Outbox Port"]
+    CachePort["Cache & Distributed Lock Port"]
+    RepoPort["Universal Repository Port"]
+  end
+
+  subgraph Egress["Secondary / Egress Polyglot Adapters"]
+    Storage["Relational & NoSQL Storage (Postgres / MySQL / Cockroach / Mongo)"]
+    CacheStore["In-Memory Store (Redis / Valkey / Dragonfly / Memcached)"]
+    BrokerOut["Event Streaming (Kafka / NATS / RabbitMQ / CloudEvents)"]
+    AuthEngines["Policy-as-Code (OPA Rego / OpenFGA ReBAC / Cerbos)"]
+    SMTP["Transactional Email Gateway (SMTP / Providers)"]
+  end
+
+  UI --> Gateway
+  Gateway --> TenantContext
+  BrokerIn --> DomainServices
+  TenantContext --> AuthPort
+  AuthPort --> AuthzPort
+  AuthzPort --> DomainServices
+  DomainServices --> RulePort
+  DomainServices --> WorkflowPort
+  DomainServices --> OutboxPort
+  DomainServices --> CachePort
+  DomainServices --> RepoPort
+
+  RepoPort --> Storage
+  OutboxPort --> Storage
+  OutboxPort --> BrokerOut
+  CachePort --> CacheStore
+  AuthzPort --> AuthEngines
+  DomainServices --> SMTP
+```
+
+---
+
+## 2. Multi-Tenant Data Isolation & Schema Graph
+
+```mermaid
+erDiagram
+  TENANT ||--o{ USER : "owns"
+  TENANT ||--o{ ROLE : "defines"
+  TENANT ||--o{ TENANT_SCHEMA : "configures"
+  TENANT ||--o{ TENANT_ENTITY : "defines"
+  TENANT_ENTITY ||--o{ TENANT_RECORD : "stores"
+  TENANT ||--o{ OUTBOX_EVENT : "emits"
+  TENANT ||--o{ AUDIT_LOG : "records"
+
+  TENANT {
+    uuid id PK
+    string slug UK
+    string name
+    string subscription_tier
+    string status
+    json theme_tokens
+    timestamptz created_at
+  }
+
+  USER {
+    uuid id PK
+    uuid tenant_id FK
+    string email UK
+    string password_hash
+    boolean mfa_enabled
+    timestamptz created_at
+  }
+
+  TENANT_SCHEMA {
+    uuid id PK
+    uuid tenant_id FK
+    string entity_name
+    json json_schema
+    int version
+  }
+
+  OUTBOX_EVENT {
+    uuid id PK
+    uuid tenant_id FK
+    string aggregate_type
+    string aggregate_id
+    string event_type
+    json payload
+    string status
+    timestamptz created_at
+  }
+```
+
+---
+
+## 3. Subsystem Fast Lookup Index
+
+| Capability | Invariant Contract / Open Standard | Swappable Polyglot Adapters | Governing Rule |
+|---|---|---|---|
+| **Runtime & Language** | Hexagonal Core (Zero Deps) | Polyglot (Go, Rust, Python, Java, TypeScript) | [`clean_code.md`](../rules/clean_code.md) |
+| **Type Safety** | Sound static types & branded primitives | Rust, TypeScript, Go, Python (type hints) | [`typescript.md`](../rules/typescript.md) |
+| **Persistence / DAL** | Abstract Repository & Unit of Work | Atlas / Flyway migrations; SQL & NoSQL drivers | [`database_transactions.md`](../rules/database_transactions.md) |
+| **Tenant Isolation** | 4 Models (AST Interceptor, Schema, DB, Proxy) | SQL AST parser, RLS, multi-pool router, Envoy | [`multitenancy_isolation.md`](../rules/multitenancy_isolation.md) |
+| **Dynamic Schemas** | JSON Schema Draft 2020-12 | Polyglot validators (`valico`, `gojsonschema`, `ajv`) | [`tenant_dynamic_schemas.md`](../rules/tenant_dynamic_schemas.md) |
+| **Authentication** | OIDC, OAuth 2.1, Passkeys (WebAuthn) | PASETO, JWT with JWKS, SPIFFE/SPIRE mTLS | [`authentication.md`](../rules/authentication.md) |
+| **Authorization** | Policy-as-Code & ReBAC | OPA (Rego/Wasm), OpenFGA (Zanzibar), Cerbos | [`authorization.md`](../rules/authorization.md) |
+| **Pluggable Logic** | Common Expression Language (CEL) / Wasm | `cel-go`, `cel-rust`, Extism (Wasm plugins) | [`tenant_pluggable_logic.md`](../rules/tenant_pluggable_logic.md) |
+| **Workflows** | Durable Orchestration & Statecharts | Temporal.io SDKs, Camunda/Zeebe (BPMN 2.0) | [`tenant_pluggable_logic.md`](../rules/tenant_pluggable_logic.md) |
+| **Caching** | Abstract Cache Port with XFetch | Redis, Valkey, Dragonfly, Memcached, Local LRU | [`caching.md`](../rules/caching.md) |
+| **Feature Flags** | OpenFeature Standard | Flipt, Unleash, LaunchDarkly, GoFeatureFlag | [`feature_flags.md`](../rules/feature_flags.md) |
+| **Testing** | Outside-In TDD, BDD & Consumer Contracts | Cucumber/Gherkin, Pact, Schemathesis | [`test_driven_development.md`](../rules/test_driven_development.md) |
+| **Presentation / SDUI** | Declarative JSON SDUI + DTCG Tokens | Web (React/Vue/Svelte), Mobile (Flutter/Native) | [`server_driven_ui.md`](../rules/server_driven_ui.md) |
+| **Transactional Email** | Declarative Email Specs / MJML | SMTP Gateway, Mailpit (Local), SES/Sendgrid | [`transactional_email.md`](../rules/transactional_email.md) |
+| **Event Streaming** | CNCF CloudEvents v1.0.2 | Kafka, NATS JetStream, RabbitMQ, SQS | [`database_transactions.md`](../rules/database_transactions.md) |
+| **Observability** | OpenTelemetry OTLP standard | OTel Collector, Jaeger, Prometheus, OpenSearch | [`cloud_native.md`](../rules/cloud_native.md) |
+
+---
+
+## 4. Agentic Skill Topology & Composability Matrix
+
+```mermaid
+flowchart TD
+  subgraph Inputs["Inception & Intent"]
+    Req["Stakeholder Feature Request / Mutation"]
+  end
+
+  subgraph Pattern1["Pattern 1: Sequential Pipeline Chaining (Workflows)"]
+    direction TB
+    SkillRQ["relentless-questioner"]
+    SkillPA["product-analyst"]
+    SkillTDD["test_driven_development"]
+    SkillRefactor["clean-code-refactor"]
+
+    SkillRQ -->|"Feature Alignment Spec (FAS)"| SkillPA
+    SkillPA -->|"INVEST Stories & Gherkin AC"| SkillTDD
+    SkillTDD -->|"Working Green Code"| SkillRefactor
+  end
+
+  subgraph Pattern2["Pattern 2: Dynamic Skill Stacking (Contextual Composition)"]
+    AgentCore["Primary Agent Session"]
+    SkillSec["compliance-audit"]
+    SkillArch["agentic-architect"]
+
+    AgentCore -.->|"Dynamic Load"| SkillSec
+    AgentCore -.->|"Dynamic Load"| SkillArch
+  end
+
+  subgraph Pattern3["Pattern 3: Multi-Agent Subagent Delegation (Division of Labor)"]
+    Coord["Coordinator Agent"]
+    SubA["Subagent A: Compliance Auditor"]
+    SubB["Subagent B: Code Refactorer"]
+
+    Coord -->|"Invoke Task"| SubA
+    Coord -->|"Invoke Task"| SubB
+    SubA -->|"Audit Findings"| Coord
+    SubB -->|"Refactored Units"| Coord
+  end
+
+  Req --> SkillRQ
+```
+
+### Many-to-Many Skill Cross-Matrix
+
+| Skill Name | Functional Specialty | Applicable Lifecycle Stages | Target Artifacts Produced |
+|---|---|---|---|
+| `relentless-questioner` | Context-aware ambiguity interrogation | Pre-Discovery, Pre-Planning | Feature Alignment Spec (FAS), Invariant List |
+| `product-analyst` | Requirements decomposition & Gherkin | Phase 1: Requirements | INVEST User Stories, Gherkin Scenarios |
+| `lets-build` | Technical infrastructure scaffolding | Initial Bootstrapping only | Package manifests, build configs, `/healthz` |
+| `clean-code-refactor` | Code smell eradication, GoF patterns | Phase 4: TDD Inner Loop | Decoupled classes, small functions (< 30 lines) |
+| `compliance-audit` | Security & compliance verification | Phase 1, Phase 5: DoD | Gitleaks, Semgrep, Trivy, OWASP audit logs |
+| `agentic-architect` | Agent configuration & skill governance | Continuous meta-refinement | Atomic `SKILL.md`, `AGENTS.md`, ADR records |

package/docs/knowledge/lessons_learned.md

@@ -0,0 +1,107 @@
+# Institutional Lessons Learned & Engineering Insights
+
+> **Core Purpose:** Capture high-level strategic takeaways, trade-off analyses, and architecture lessons to continuously elevate team velocity and agentic precision.
+
+---
+
+## 1. Agentic Architecture & Token Optimization
+- **Progressive Disclosure is Non-Negotiable:** Injecting 500 lines of documentation on every prompt degrades LLM reasoning. A lean root file (under 120 lines) acting as an indexed directory to modular rules preserves token budget and drastically improves model precision.
+- **Conjunctions Betray Anti-Patterns:** Rules named `x_and_y.md` almost always signal that two distinct concepts have been artificially bundled. Decomposing into pure single-responsibility files prevents documentation rot and makes rules truly composable.
+- **Relentless Questioning Prevents Hallucination:** Asking the 7 Core Inquiry Branches before authoring skills prevents speculative features, unused scripts, and ungrounded assumptions.
+
+---
+
+## 2. Multi-Tenancy & Data Isolation
+- **Defense in Depth Over Developer Memory:** Never assume every developer or agent will remember to write `where: { tenantId }`. Hard database constraints (PostgreSQL RLS) must enforce isolation as a physical barrier.
+- **Metadata Over Code Sprawl:** Enterprise tenants always require custom attributes, diverging workflows, and custom branding. Solving this through code branches (`if (tenant === 'acme')`) leads to exponential debt. Solving this through declarative schemas, JSON rule engines, and Server-Driven UI (SDUI) keeps the codebase tenant-agnostic.
+
+---
+
+## 3. Database Atomicity & Concurrency
+- **The Dual-Write Problem is Everywhere:** As soon as an application updates a database and publishes to a broker or sends an email sequentially, it risks data divergence. The Transactional Outbox pattern is the gold standard for reliable event-driven state propagation.
+- **DDL Locks Starve Production:** DDL queries queue up and block all subsequent reads and writes. Setting defensive `lock_timeout` and using non-blocking operations (`CREATE INDEX CONCURRENTLY`, two-phase constraint validation) is essential for zero-downtime operations.
+
+---
+
+## 4. Full-Stack Boundary & Monorepo Test Integrity
+- **The In-Memory Supertest Illusion:** In-memory integration testing (`supertest(app)`) operates entirely within Node.js process memory. It validates route mapping and status codes, but completely masks network binding failures, reverse proxy omissions (Vite dev server / NGINX), and frontend client JSON serialization mismatches.
+- **Coverage Percentages Do Not Equal System Integrity:** 100.00% statement and branch coverage in an isolated backend package gives zero guarantees about whether the frontend client or reverse proxy works. Monorepo test suites must mandate outer-loop smoke verification (`scripts/smoke_test.sh`) before declaring a full-stack system functional.
+
+---
+
+## 5. Process Integrity: Decoupling Bootstrapping from Domain Discovery
+- **The Bootstrapping Scope Trap:** AI agents naturally gravitate toward rapidly generating complete functional applications. When invoked with `/lets-build`, an eager agent tends to generate entire domain entities, database tables, and mock UIs on sheer assumptions. This skips the most crucial phase of software engineering: deep, relentless stakeholder domain analysis.
+- **Strict Phase Gating:** Project bootstrapping (`lets-build`) must be strictly confined to technical plumbing (toolchain, package manifests, build scripts, linter, Docker/Compose, and a minimal `/healthz` probe). Once the technical foundation is verified, the agent must stop and hand off to Domain Analysis (`product-analyst`, `relentless-questioner`). Real domain models must emerge exclusively from stakeholder interviews and Ubiquitous Language discovery.
+
+---
+
+## 6. UX Integrity: Decoupling Developer Personas from Production Auth & Design Triage
+- **The "Toy Prototype" Anti-Pattern:** A major failure mode in rapid prototyping is embedding test personas ("Admin Alice", "Operator Bob", "Member Charlie") directly inside end-user sign-in forms or modals. This destroys product credibility, confuses real users, and masks broken authentication and onboarding flows.
+- **Strict Separation of Concerns:** Developer testing personas must be 100% decoupled from production authentication. They belong exclusively in a dedicated development toolbar (`import.meta.env.DEV`), completely invisible in production builds. Production authentication must be a clean, dedicated, professional experience with validation, session persistence, and role-based post-login redirection.
+- **The Untriaged Design Architecture Trap:** Building user interfaces without upfront Design Architecture Triage (roles, information architecture, navigation shell, URL state synchronization, and page flows) inevitably produces fractured, toy-like prototypes. Every UI increment must pass the 7-Pillar Design Architecture Triage Gate before writing a line of view code.
+
+---
+
+## 7. Server State Synchronization vs. Mock React Context
+- **The Local Mock Store Debt:** Maintaining temporary in-memory React contexts (`MockResourceContext.tsx`) or mock data arrays alongside a real backend REST API creates phantom state, breaks multi-tab consistency, and causes state divergence.
+- **Server-Authoritative State via TanStack Query:** Migrating to server-authoritative state via TanStack Query (`useQuery`, `useMutation`, and cache invalidation) with declarative RBAC guards (`<Can permission="...">`) grounds the entire web application in persistent backend data, eliminating client-side mocks and guaranteeing multi-tenant consistency.
+
+---
+
+## 8. Zero-Dependency SMTP Sockets & Deterministic Email Testing
+- **Third-Party Mailer Bloat vs. Native Sockets:** Standard local development and containerized mail catchers (e.g. Mailpit) accept RFC 5321 commands over TCP sockets. Relying on heavy external mailer packages introduces unneeded transitive dependencies and supply chain risks. Implementing a clean socket-based SMTP adapter with standard library sockets provides zero-dependency, fully audited delivery with multipart/alternative MIME formatting and graceful offline fallback.
+- **Strict HTML Escaping & Injection Neutralization:** Transactional notifications interpolate user inputs (names, action titles, payment references). Centralizing sanitization through a strict escaping utility neutralizing `&`, `<`, `>`, `"`, and `'` guarantees zero HTML injection or XSS risks.
+- **Double-Loop Decoupling with Background Job Queue:** Decoupling notification delivery from HTTP request-response cycles via an asynchronous job queue ensures API responsiveness. Testing event dispatchers against in-memory notification sinks allows 100.00% branch and statement coverage without network flakes.
+
+---
+
+## 9. Digital Contract Execution, Schema Evolution & Signature Auditing
+- **Non-Destructive Schema Evolution with Declarative JSON:** Expanding database models to support variable contractual covenants, conditions, and digital signature records without table bloat is achieved cleanly through semi-structured JSON fields (`termsJson`, `signatureJson`). Running declarative synchronization preserves database integrity and avoids premature migration schema lock-in during rapid domain evolution.
+- **Cryptographic Execution Audit Trails:** Digital signatures require more than a boolean `isSigned` flag. A legally defensible electronic execution record must record: (1) Typed signer legal name, (2) ISO 8601 UTC timestamp, (3) Authenticated user actor ID, (4) Client IP address, (5) Client User-Agent string, and (6) A deterministic cryptographic checksum or execution reference hash.
+- **Outside-In Event Notification Synchronization:** Executing an agreement is a domain transition that must trigger notification side effects. Emitting domain events on an asynchronous queue allows event notification dispatchers to compose transactional confirmation messages with executed terms and receipt summaries without blocking the HTTP response.
+
+---
+
+## 10. Design Token Completeness & Application-Wide Theme Architecture
+- **The Partial Dark Mode Token Pitfall:** Automated component CLI generators inject component-scoped CSS variables into `.dark` (e.g. `--sidebar-*`), but do not populate omitted foundational design tokens (`--background`, `--foreground`, `--card`, `--border`, `--popover`). If root `.dark` is missing foundational tokens, applying the `dark` class leaves background colors white and text illegible. Always maintain symmetric, complete design tokens across `:root` and `.dark`.
+- **System Preference Detection & Reactive Synchronization:** A robust `ThemeProvider` must listen to `window.matchMedia('(prefers-color-scheme: dark)')` with dynamic event listeners so OS appearance toggles seamlessly propagate in real-time. Synchronizing `document.documentElement.style.colorScheme = resolvedTheme` ensures native browser elements (scrollbars, datetime pickers) match the selected theme.
+
+---
+
+## 11. Dependency Injection Hygiene vs. Split-Brain In-Memory Traps
+- **The Split-Brain Instantiation Anti-Pattern:** When application factories (`createApp(deps)`) provide default fallback instances for domain repositories, passing some repositories while omitting others creates two disconnected sets of state. For instance, if `index.ts` creates a `userRepo` and seeds admin credentials, but `createApp` defaults to a newly constructed `userRepo`, API requests hit the empty fallback instance.
+- **Strict Inversion of Control:** Factories must accept a fully instantiated `AppDependencies` composite or explicit container. Server entrypoints must assemble the complete dependency graph and inject all collaborators explicitly.
+
+---
+
+## 12. Domain Invariant Synchronization & Resource Concurrency
+- **Aggregate Isolation Requires Domain Coordination:** An agreement or reservation is a separate aggregate from a constrained inventory resource. However, activating an agreement without validating resource availability permits double-allocation race conditions. Hexagonal use cases must coordinate aggregate transitions atomically: validating resource availability before agreement signing, transitioning the resource status to `ALLOCATED` upon execution, and restoring `AVAILABLE` upon termination.
+- **Fail-Closed Multi-Tenancy:** Never trust client-supplied tenant headers (`x-tenant-id`) without cryptographically verifying the authenticated actor's tenant organization memberships. Mismatched tenant headers must immediately fail closed with HTTP 403 `FORBIDDEN_TENANT_ACCESS`.
+
+---
+
+## 13. Client-Side Resilience & Multi-Tab Reactive Synchronization
+- **Error Boundaries Prevent Catastrophic Shell Crashes:** Heavy visual components (such as charts with dynamic SVG/canvas rendering) or dynamic sub-routes can throw runtime exceptions on unexpected data. Wrapping page outlets and complex widgets in accessible `<ErrorBoundary>` components preserves the shell and navigation while offering modular retry.
+- **Cross-Tab Synchronization via Storage Events:** Modern multi-tab workflows mean users open links, resource lists, or self-service portals in separate tabs. Listening to the browser's native `storage` event ensures that login, logout, and active tenant switches are immediately synchronized across all open tabs without desynchronization.
+
+---
+
+## 14. Decoupling Developer Diagnostics from Production Shell & Centralizing UI Copy
+- **The Telemetry Bleed Anti-Pattern:** Placing internal architectural metrics ("ACID ledger", "Hexagonal ports", "API Connected" pulsing pills, "Role: OPERATOR" badges) into user-facing wayfinding breadcrumbs, headers, or footers creates confusion for end users (consumers and enterprise operators alike). These technical indicators belong strictly within development tools conditionally mounted under `import.meta.env.DEV`, ensuring production builds are clean and focused on user tasks.
+- **Centralized Single Source of Truth for Copy:** Distributing strings across JSX templates causes text divergence, typos, and high refactoring overhead. Consolidating all copy, error messages, empty states, breadcrumbs, and action text into a single configuration module (`UI_STRINGS` in `app-constants.ts`) simplifies internationalization readiness, branding updates, and unit test verification.
+
+---
+
+## 15. Monorepo-Wide Module Path Aliasing (`@/*`) & Deep Relative Traversal Elimination
+- **Fragility of Deep Relative Imports:** Using deep relative traversals (`../../../..`, `../../..`, `../..`) across modular hexagonal architectures creates fragile couplings. Minor file restructuring breaks dozens of imports, and deep relative paths obscure which architectural boundary (domain core, primary ports, secondary adapters) is being invoked.
+- **Unified Path Aliasing Standard:** Standardizing on `@/*` mapped to `./src/*` across TypeScript compiler configs (`tsconfig.json`), test runners (Vitest), and bundlers (Vite) enforces consistent, unambiguous imports across the entire monorepo.
+- **Node.js ESM Build Resolution via `tsc-alias`:** TypeScript's `tsc` compiler does not rewrite path aliases in emitted JavaScript by default. In Node.js ESM environments, running `tsc-alias` post-compilation (`tsc && tsc-alias`) transforms `@/*` aliases into valid relative paths directly in `dist/`, enabling 100% native Node.js ESM execution with zero runtime loader overhead.
+
+---
+
+## 16. Canonical Domain Error Hierarchy & Zero-`any` Type Safety
+- **The Monkey-Patching Anti-Pattern:** Adding status codes to arbitrary error objects at catch sites (e.g. `(err as any).statusCode = 404`) bypasses TypeScript strict mode, prevents compile-time exhaustiveness checking, and risks dropping contextual problem details.
+- **Structured Domain Error Model:** Modeling operational domain errors via an explicit `DomainError` base class with canonical subclasses (`ValidationError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `ExpiredError`) allows clean `instanceof` type narrowing in HTTP error middleware, guaranteeing RFC 7807 compliance without type assertion escape hatches.
+
+
+

package/docs/knowledge/ubiquitous_language.md

@@ -0,0 +1,23 @@
+# Living Ubiquitous Language Glossary Template
+
+> **Source of Truth:** Authoritative terminology dictionary binding domain concepts, business definitions, and exact code identifiers. Customize this glossary per project.
+
+---
+
+## Canonical Domain Vocabulary Matrix
+
+| Canonical Term | Business Definition | Bounded Context | Forbidden Synonyms | Code & Database Identifiers |
+|---|---|---|---|---|
+| **Organization** | The top-level administrative and multi-tenant isolation container. | Multi-Tenancy & Identity | Account, Company, Workspace, TenantGroup | `Organization`, `organizationId`, `organizations` table |
+| **User** | A human actor authenticated with verified credentials across the platform. | Identity & Access | Member (when unauthenticated), Account, Login | `User`, `userId`, `users` table |
+| **Membership** | The formal association connecting a User to an Organization with assigned roles. | Authorization & RBAC | UserOrg, Seat, PermissionAssignment | `Membership`, `membershipId`, `memberships` table |
+| **Role** | A named set of granular `<entity>:<action>` permissions within an organization. | Authorization | Group, Profile, Level | `Role`, `roleId`, `roles` table |
+| **Resource** | The primary business entity managed within the domain core. | Core Domain | Item, Object, Record, Entity | `Resource`, `resourceId`, `resources` table |
+| **Ledger Entry** | An immutable audit record detailing a financial or transactional state change. | Finance & Accounting | TransactionRow, MoneyLog, BillEntry | `LedgerEntry`, `ledgerEntryId`, `ledger_entries` table |
+
+---
+
+## Linguistic Invariants & Rules
+1. **The Single Name Rule:** Every domain concept has exactly one authoritative name. Synonyms are strictly forbidden across code, schemas, and UI.
+2. **Contextual Boundaries:** If a word has multiple meanings across business departments, isolate the terms within dedicated Bounded Contexts.
+3. **Continuous Updating:** When domain experts establish or rename a term, update this glossary immediately, record an ADR in `memory.md`, and refactor all occurrences.

package/docs/rules/accessibility.md

@@ -0,0 +1,31 @@
+# Accessibility (A11y) & WCAG 2.2 Standards
+
+> **Core Mandate:** Enforce WCAG 2.2 Level AA compliance, accessible Radix UI primitives, keyboard focus management, visible focus rings, and ARIA live regions across all user interfaces.
+
+---
+
+## 1. Accessible UI Primitives & Radix UI
+
+- **Prohibited Native Alerts**: Strictly prohibit browser-native `window.confirm()` or `window.alert()`. Use accessible Radix UI dialogs (`@radix-ui/react-dialog`, `@radix-ui/react-alert-dialog`).
+- **Focus Management & Trapping**:
+  - Modal dialogs must trap keyboard focus within the dialog container while open.
+  - Closing a dialog must return keyboard focus deterministically to the triggering element.
+- **Visible Focus Indicators**: Never remove default outline rings (`outline: none`) without providing an explicit, high-contrast replacement (`focus-visible:ring-2 focus-visible:ring-offset-2`).
+
+---
+
+## 2. Form & Feedback Accessibility
+
+- **Form Input Wiring**:
+  - Every form input must have an associated `<label>` using `htmlFor` or nested wrapping.
+  - Validation errors must be programmatically linked to their inputs via `aria-invalid="true"` and `aria-describedby="<error-message-id>"`.
+- **Dynamic Content & Status Feedback (ARIA Live Regions)**:
+  - Asynchronous notifications, toast alerts, and status updates must use `role="status"` or `aria-live="polite"` so screen readers announce changes without interrupting the user.
+  - Critical error alerts must use `role="alert"` or `aria-live="assertive"`.
+
+---
+
+## 3. Visual & Contrast Baselines
+
+- **Color Contrast**: Maintain a minimum contrast ratio of 4.5:1 for normal text and 3:1 for large text / UI controls against their background.
+- **Semantic Landmark Markup**: Use semantic landmark elements (`<main>`, `<nav>`, `<aside>`, `<header>`, `<footer>`, `<section>`) rather than unsemantic `<div>` structures.

package/docs/rules/advanced_api_patterns.md

@@ -0,0 +1,104 @@
+# Advanced REST API Patterns & Capability Architecture
+
+> **Core Mandate:** Enrich API responses with capability metadata (Allowed Actions), ensure safe mutations via idempotency keys, enforce cursor pagination, and prevent race conditions with optimistic concurrency.
+
+---
+
+## 1. Allowed Actions & Capability Metadata (HATEOAS-Lite)
+
+Clients must not duplicate server-side business and authorization rules to decide whether an action (edit, delete, approve, cancel) is 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 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" }
+  }
+}
+```
+
+### UI Benefits
+- Frontend buttons and menus simply bind to `resource._actions.canDelete`.
+- When business logic evolves (e.g. orders over $1,000 require manager approval), only the backend logic changes—zero frontend redeployment required.
+
+---
+
+## 2. Safe Mutations via Idempotency Keys (IETF Draft)
+
+To prevent duplicate processing (double charging, duplicate resource creation) caused by network retries:
+
+### Protocol
+- Clients generating mutating requests (`POST`, `PATCH`) must supply a unique `Idempotency-Key: <uuid-v4>` header.
+- **Server Lifecycle**:
+  1. Check distributed idempotency store 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 status code, headers, and response payload without re-executing.
+  4. If not found: Acquire distributed lock, process mutation atomically, cache response with a 24-hour TTL, and release lock.
+
+---
+
+## 3. 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.
+
+### Specification
+- 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 cursor token for `nextCursor`.
+
+---
+
+## 4. Optimistic Concurrency Control (OCC)
+
+Prevent lost-update anomalies during concurrent edits without pessimistic database row locking:
+
+### Protocol
+- Every mutable entity contains an incrementing integer `version` column.
+- Server returns the current version in the `ETag` response header: `ETag: W/"v4"`.
+- Clients submitting updates (`PUT`, `PATCH`) must include `If-Match: W/"v4"`.
+- **Conflict Handling**:
+  - Atomic update: `UPDATE table SET ..., version = version + 1 WHERE id = :id AND version = :expectedVersion`.
+  - If 0 rows updated: Return **`409 Conflict`** with error code `CONCURRENCY_CONFLICT` and the latest entity representation.
+
+---
+
+## 5. Asynchronous Processing (`202 Accepted`)
+
+For tasks taking > 1.5 seconds (video rendering, large PDF export, batch imports):
+- Do NOT block synchronous client requests.
+- Dispatch task to an asynchronous worker queue or workflow engine.
+- Return **`202 Accepted`** immediately with:
+  - Header: `Location: /api/v1/tasks/:taskId`
+  - Body: `{ "taskId": "tsk_123", "status": "QUEUED", "pollIntervalMs": 2000 }`

package/docs/rules/agentic_configuration.md

@@ -0,0 +1,168 @@
+# Agentic Configuration, Skills & 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.
+
+---
+
+## 1. The Root AGENTS.md Standard
+
+Root configuration files (`AGENTS.md`) are injected into the agent context on **every single prompt**. To prevent context pollution and token degradation:
+
+### Required Contents (Keep under 100–120 lines)
+- **Identity & Mission:** 1–2 sentences defining workspace purpose and core domain.
+- **Runtime Environment:** Declared package manager, runtime version, and non-standard scripts.
+- **Core Operating Framework:** Foundational principles (Rule Zero, Zero-Assumption, Relentless Questioning, 5-stage lifecycle, action boundaries).
+- **Open-Source Mandate:** Strict requirement to standardize on 100% open-source packages and tools.
+- **High-Level Layout:** High-level architectural boundaries only (packages, apps).
+- **Progressive Disclosure Table:** Clean index linking to specialized domain rules in `docs/rules/*.md`.
+
+### Explicit Prohibitions (What NOT to Include)
+- **No Developer Onboarding / Getting Started Guides:** Do not include steps for cloning, environment setup, or basic onboarding meant for human engineers.
+- **No Granular File Trees:** Never enumerate individual file paths that change frequently (causes rapid documentation rot).
+- **No Monolithic Domain Tutorials:** Never embed full CSS conventions, database migration steps, API specs, or PR delivery checklists directly in the root file.
+- **No Preemptive Speculation:** Never add rules for errors the AI has not actually made. Ground rules in verified project mistakes or requirements.
+
+---
+
+## 2. Monorepo & Nested AGENTS.md Files
+
+- In multi-package workspaces or monorepos (e.g. `apps/backend/`, `apps/frontend/`), place package-specific instructions in a nested `AGENTS.md` within that package folder.
+- The root `AGENTS.md` remains high-level; the nested `AGENTS.md` provides scoped context only when the agent operates within that subdirectory.
+
+---
+
+## 3. Harness Parity & Symlinks
+
+Different AI agents and IDE harnesses look for different configuration filenames:
+- Standard: `AGENTS.md`
+- Lowercase: `agents.md`
+- Anthropic Claude Code: `CLAUDE.md`
+
+**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
+```
+Never duplicate content into separate files.
+
+---
+
+## 4. Skills Architecture (`.agents/skills/<skill-name>/`)
+
+Skills provide on-demand capabilities for **specialized, complex, or multi-step workflows** that should not pollute the global context.
+
+### Front Matter Specification (`SKILL.md`)
+```yaml
+---
+name: <skill-name>
+description: <Imperative trigger description under 1024 characters. MUST start with 'Use when...'>
+---
+```
+- **Description Requirements:**
+  - Focus strictly on **user intent**, not just technology descriptions.
+  - Explicitly state when to use: `Use when the user wants to...`
+  - Explicitly state when NOT to use: `Do not use for...`
+  - Never write generic summaries like `"A library for managing state"`.
+
+### Body Guidelines
+- Keep under **500 lines**.
+- Ground instructions in real codebase experience, not generic documentation the LLM already knows.
+- **Mandatory "Gotchas & What NOT to Do" section:** Explicitly list known AI anti-patterns and pitfalls.
+- 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.
+- `scripts/`: Deterministic executable scripts (bash, node, python) for tasks where LLMs produce non-deterministic drift.
+- `assets/`: Static data, lookup tables, schemas, or boilerplate templates.
+
+---
+
+## 5. The Architectural Atomicity Mandate for Rules & Skills
+
+Every rule, skill, workflow, and configuration component must adhere to the **Single Responsibility Principle (SRP)**: indivisible, self-contained, orthogonal, and composable.
+
+### Rule Atomicity
+- **One Domain Per Rule:** Each rule file in `docs/rules/` must govern exactly one architectural or engineering subdomain.
+- **Completeness Without Stubs:** A rule must never be a shallow stub or placeholder; it must codify production-grade invariants, anti-patterns, and concrete code patterns.
+- **Zero Cross-Leakage:** Rules must be mutually orthogonal—never duplicate or contradict directives across files.
+
+### Skill Atomicity
+- **One Capability Per Skill:** Each skill in `.agents/skills/` must encapsulate one discrete, multi-step workflow.
+- **Bounded Negative Triggers:** Must define both what it does (`Use when...`) and explicitly what it does not do (`Do not use for...`).
+- **Encapsulated Artifacts:** Scripts, assets, and reference docs must live within the skill's isolated directory tree.
+- **Idempotent Execution:** Re-executing a skill against the same inputs must produce identical, deterministic results.
+
+### Many-to-Many Skill Composability Models
+Coding tasks and agentic skills exhibit an explicit **Many-to-Many ($M:N$) Relationship**:
+1. **Multiple Skills per Coding Task:** Implementing a complex domain feature frequently requires composing several orthogonal skills:
+   - `relentless-questioner` (resolves ambiguous invariants and failure edge cases).
+   - `product-analyst` (decomposes into INVEST user stories and executable Gherkin criteria).
+   - `compliance-audit` (verifies OWASP, SOC 2, and data isolation controls).
+   - `clean-code-refactor` (applies GoF patterns, CQS, SLAP, and eliminates code smells during the TDD inner loop).
+2. **Single Skill in Multiple Scenarios:** An atomic skill functions as a reusable capability across completely different business problems (e.g. `clean-code-refactor` applies equally to financial ledgers, order lifecycle state machines, and authentication middleware).
+
+#### The 3 Composition Patterns:
+- **Pattern 1: Sequential Pipeline Chaining (Workflow Composition):** Skill $A$ produces a structured artifact (e.g. Feature Alignment Spec) that serves as the direct input contract for Skill $B$ (e.g. Gherkin test suite generation).
+- **Pattern 2: Dynamic Skill Stacking (Contextual Composition):** An agent activates multiple orthogonal skills simultaneously in its execution context, adhering to Progressive Disclosure without polluting global prompts.
+- **Pattern 3: Multi-Agent Subagent Delegation (Division of Labor):** A coordinator agent delegates isolated sub-tasks to specialized subagents equipped with specific skills, synthesizing their outputs into a single atomic change.
+
+#### Invariants for Valid Skill Composition:
+- **Standardized Output Contracts:** Skills must emit predictable, structured markdown or JSON envelopes (e.g. FAS, Gherkin blocks, ADR templates).
+- **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 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]
+```
+
+### The 7 Core Inquiry Branches
+
+| # | Inquiry Branch | What to Interrogate | If Unanswered |
+|---|---|---|---|
+| **1** | **Placement & Scope** | Does this apply to all prompts (Root `AGENTS.md`), one package (Nested `AGENTS.md`), a continuous coding domain (`docs/rules/`), or an on-demand task (`.agents/skills/`)? | Stop and categorize correctly. Never bloat root configs. |
+| **2** | **Trigger Intent** | What explicit user intent wakes this skill? What are the negative conditions? | Interrogate the user on exact workflow boundaries. |
+| **3** | **Domain Truth** | Is this grounded in this project's architecture, or generic fluff the LLM already knows? | Purge generic definitions (e.g. "What is a PDF/REST API"). |
+| **4** | **Gotchas & Anti-Patterns** | What exact mistakes has the AI repeatedly made in this task? | Formulate 3–5 explicit negative "DO NOT" rules. |
+| **5** | **Determinism** | Are there brittle CLI sequences that need a bash/Node script instead of stochastic LLM generation? | Create helper scripts in `scripts/`. |
+| **6** | **Progressive Bloat** | Does `SKILL.md` exceed 500 lines? | Extract sub-topic guides into `references/`. |
+| **7** | **Verification Loop** | How will the agent and user prove the skill succeeded? | Provide structured response templates & validation checklists. |
+
+---
+
+## 7. 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.