azcodr 1.0.0

package/docs/rules/multitenancy_isolation.md

@@ -0,0 +1,86 @@
+# 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.
+
+---
+
+## 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/product_ownership.md

@@ -0,0 +1,150 @@
+# Product Ownership, Backlog Management & OKRs
+
+> **Core Mandate:** Maximize product value through empiricism (Build-Measure-Learn), clear Product Goals, strategic OKR alignment, outcome-driven value measurement, and disciplined backlog ordering.
+
+---
+
+## 1. The Product Owner Accountability & Empiricism
+
+The Product Owner (PO) is accountable for maximizing the value of the product resulting from the work of the development team. This accountability is grounded in **empiricism**: making decisions based on observation, experimentation, and evidence rather than speculation.
+
+### Core Accountabilities
+1. **Developing & Communicating the Product Goal:** Formulating a singular, long-term target that provides direction and a measurable commitment for the Product Backlog.
+2. **Creating & Communicating Product Backlog Items (PBIs):** Translating stakeholder needs and strategic objectives into transparent, well-understood backlog items.
+3. **Ordering the Product Backlog:** Ranking items to optimize value, address critical risks, and sequence dependencies.
+4. **Deciding What NOT to Do:** The hallmark of effective product ownership is saying "no" to low-impact, out-of-scope, or speculative requests to preserve focus.
+5. **Ensuring Backlog Transparency:** Maintaining a single, accessible, and visible source of truth for the team and stakeholders.
+6. **Measuring Delivered Value:** Continuously gathering feedback from customers and stakeholders, calculating return on investment (ROI), and closing the satisfaction gap.
+
+---
+
+## 2. Product Value & Outcome vs. Output
+
+### Defining Product Value
+Product value is the benefit a product provides to customers (by meeting needs and increasing satisfaction) and to the organization (monetary return, business longevity, brand reputation).
+
+### The Satisfaction Gap
+Value creation focuses on closing the **Satisfaction Gap**:
+$$\text{Satisfaction Gap} = \text{Desired Customer Experience} - \text{Current Customer Experience}$$
+
+### Avoiding the "Feature Factory" (Output vs. Outcome)
+- **Output:** The sheer volume of work completed (e.g., number of features shipped, story points burned, code commits). Output alone does NOT equal value.
+- **Outcome:** The measurable positive change in customer behavior, satisfaction, operational efficiency, or business performance resulting from the product increment.
+- Shipping 10 features that users ignore is pure waste. Shipping 1 vertical slice that solves a critical pain point is high value.
+
+### The Product Increment & Definition of Done
+The only vehicle through which a team delivers actual product value is a usable, high-quality **Product Increment** that fully satisfies the **Definition of Done (DoD)**. Work that is not done delivers zero value and accumulates technical debt.
+
+---
+
+## 3. Strategic Alignment via OKRs (Objectives and Key Results)
+
+The OKR framework connects overarching strategic vision to sprint execution and product backlog ordering.
+
+```
+Company Vision & Strategy
+       │
+       ▼
+Strategic OKRs (Annual / Quarterly)
+       │
+       ▼
+  Product Goal (Long-Term Commitment)
+       │
+       ▼
+Product Backlog (Emergent, Ordered PBIs)
+       │
+       ▼
+  Sprint Goal (Tactical Increment)
+```
+
+### Anatomy of an OKR
+- **Objective (O):** Qualitative, aspirational, inspiring, and time-bound statement defining **WHAT** must be achieved.
+  - *Example:* "Establish our digital self-service portal as the fastest and most frictionless onboarding experience in the industry."
+- **Key Results (KRs):** 2 to 5 quantitative, outcome-focused metrics defining **HOW** progress toward the Objective is measured.
+  - *Rule:* KRs must measure outcomes or impact, never activities or tasks (e.g., "Conduct 5 meetings" is an activity; "Increase onboarding conversion from 40% to 75%" is an outcome).
+  - *Example KRs:*
+    1. Reduce average time from application approval to active service from 72 hours to under 4 hours.
+    2. Achieve a 95% digital self-service execution completion rate without customer support escalations.
+    3. Decrease manual operator review processing time by 60%.
+
+### OKRs vs. KPIs
+| Dimension | Key Performance Indicators (KPIs) | Objectives & Key Results (OKRs) |
+|---|---|---|
+| **Purpose** | Measure ongoing operational health and business-as-usual baseline metrics ("vital signs"). | Drive deliberate, time-bound, aspirational transformation and change. |
+| **Cadence** | Continuous / evergreen monitoring (e.g., server uptime, customer churn rate). | Typically quarterly or cyclical (e.g., Q1, Q2) with retrospective scoring. |
+| **Mindset** | "Keep the lights on and within acceptable thresholds." | "Move the needle on strategic priorities and break new ground." |
+
+---
+
+## 4. Product Backlog Ordering & Prioritization Techniques
+
+Never prioritize a backlog solely on "gut feeling" or the loudest voice. Utilize established open-standard prioritization models:
+
+### 1. The Kano Model (Customer Delight vs. Investment)
+Categorizes features based on how customer satisfaction correlates with implementation completeness:
+- **Must-be (Basic / Expected):** Table stakes. Absence causes extreme dissatisfaction; presence is taken for granted (e.g., secure password reset, data isolation).
+- **Performance (One-dimensional):** Linear satisfaction. The more, the better (e.g., search speed, export volume, page load time).
+- **Attractive (Delighters / Excitement):** Unexpected innovations. Absence causes no dissatisfaction, but presence triggers high customer delight (e.g., instant one-click self-service onboarding).
+- **Indifferent:** Features customers do not care about. Eliminate immediately.
+- **Reverse:** Features that cause dissatisfaction if added (e.g., excessive mandatory onboarding popups).
+
+### 2. MoSCoW Prioritization
+- **Must Have (M):** Non-negotiable core invariants; without them, the increment cannot be released or is illegal/insecure.
+- **Should Have (S):** Important capabilities that add substantial value, but a workaround exists for this release.
+- **Could Have (C):** Desirable enhancements implemented only if time and capacity permit.
+- **Won't Have This Time (W):** Explicitly agreed out-of-scope items for the current planning cycle, protecting the team from scope creep.
+
+### 3. RICE Scoring
+Calculates a numerical score to rank candidate backlog items objectively:
+$$\text{RICE Score} = \frac{\text{Reach} \times \text{Impact} \times \text{Confidence}}{\text{Effort}}$$
+- **Reach:** Number of users or transactions impacted over a fixed period.
+- **Impact:** Degree of benefit per user (e.g., $3 = \text{massive}$, $2 = \text{high}$, $1 = \text{medium}$, $0.5 = \text{low}$, $0.25 = \text{minimal}$).
+- **Confidence:** Percentage reflecting data backing your estimate ($100\% = \text{high evidence}$, $80\% = \text{medium}$, $50\% = \text{speculative}$).
+- **Effort:** Total person-weeks or person-sprints required to deliver the vertical slice.
+
+### 4. Buy a Feature
+A collaborative prioritization exercise where stakeholders are allocated a constrained budget of fictitious currency to "buy" features priced according to their engineering effort. Reveals true customer value by forcing trade-offs under scarcity.
+
+---
+
+## 5. Product Backlog Granularity & Progressive Elaboration
+
+Following Gunther Verheyen's backlog topology, the Product Backlog serves as an **emergent, living roadmap**:
+
+```
+▲ Finer Granularity (Top)
+│   [ PBI 1: Sprintable, vertically sliced, clear DoD & Gherkin ]
+│   [ PBI 2: High priority, well-understood, estimated ]
+│   [ PBI 3: Actionable, small, customer value clear ]
+│
+│ Medium Granularity (Middle)
+│   [ PBI 4: Candidate for next period, coarse slice ]
+│   [ PBI 5: Alternative approach under evaluation ]
+│
+▼ Coarser Granularity (Bottom)
+    [ PBI 6: Long-term idea, future capability ]
+    [ PBI 7: Raw thought, exploratory concept ]
+```
+
+### Rules of Progressive Elaboration
+1. **Single & Ordered:** Exactly one backlog exists per product.
+2. **Dynamic Splitting:** As coarse items approach the top of the backlog, they must be split into fine, sprintable INVEST slices.
+3. **Continuous Pruning:** Items may be reordered, added, split, or permanently deleted at any time based on empirical learning. If an item lingers at the bottom of the backlog for months without business justification, remove it.
+
+---
+
+## 6. Invariants, DO's & DONT's
+
+### DO's:
+- **DO:** Formulate a clear, inspiring Product Goal that guides all backlog prioritization.
+- **DO:** Ground prioritization in quantitative models (RICE, Kano, MoSCoW) rather than executive opinion.
+- **DO:** Measure outcomes (satisfaction gap closure, conversion, retention) instead of pure output (story points, lines of code).
+- **DO:** Explicitly state what will NOT be done (Won't Have this time) to preserve engineering focus.
+- **DO:** Ensure every sprint increment complies 100% with the Definition of Done.
+
+### DONT's:
+- **DONT:** Never confuse output (features shipped) with outcome (value realized).
+- **DONT:** Never treat OKRs as a task checklist; Key Results must be measurable outcomes.
+- **DONT:** Never prioritize speculative features when core "Must-be" baseline capabilities are unfulfilled.
+- **DONT:** Never maintain separate, disconnected backlogs for the same product.
+- **DONT:** Never deliver "un-done" work carrying forward technical debt.

package/docs/rules/project_management.md

@@ -0,0 +1,66 @@
+# Project Management, Work-In-Progress Limits & Definition of Done
+
+> **Core Mandate:** Enforce strict Work-In-Progress (WIP) limits, vertical task slicing, SMART developer task decomposition, explicit task lifecycle states, and an uncompromising Definition of Done (DoD).
+
+---
+
+## 1. Task Lifecycle & WIP Limits
+
+- **Task States**: Every operational task must progress through explicit states:
+  ```
+  BACKLOG ──► TODO ──► IN_PROGRESS ──► REVIEW ──► DONE
+  ```
+- **Strict WIP Limit**: Maintain a Work-In-Progress (WIP) limit of **exactly 1 atomic task** at any given time. Never begin a new task while a previous task is incomplete or failing tests.
+- **Vertical Task Slicing**: Stories must deliver full-stack value across UI, API, Domain, and DB layers (no horizontal layers like "create migration only").
+
+---
+
+## 2. Decomposing Stories into SMART Developer Tasks
+
+While user stories represent customer-facing value (governed by the INVEST model), engineering execution requires decomposing each story into technical developer tasks. Apply Bill Wake's **SMART** criteria to all developer tasks:
+
+- **S - Specific:** The task scope is clearly defined so every team member understands what is involved. Avoids overlapping with concurrent work and ensures all tasks aggregate into the complete story.
+- **M - Measurable:** Defined by the question: *"Can we objectively mark it as done?"* Completion requires that:
+  1. The code fulfills its intended behavior.
+  2. Automated tests are written and passing.
+  3. Clean code principles and refactoring have been applied.
+- **A - Achievable:** The task owner has the skills and context to complete it. Establish a psychological safety norm: anyone can ask for help immediately if a task encounters unexpected obstacles.
+- **R - Relevant:** Every developer task directly contributes to delivering the parent user story. Technical infrastructure tasks must be justified by the business capability they unlock.
+- **T - Time-Boxed:** Each task has a bounded duration expectation (typically 2–4 hours, never exceeding 1 day). Exceeding the time-box acts as an automatic trigger to pause, split the task, pair with a peer, or adjust the plan.
+
+---
+
+## 3. Definition of Done (DoD)
+
+A user story or task is only marked `DONE` when all of the following verifiable criteria are met:
+- [ ] **Lifecycle Provenance**: Code developed strictly via the 5-Phase Agile Domain Lifecycle (Requirements ➔ Domain Analysis ➔ Outer Acceptance RED ➔ Inner Unit RED-GREEN-REFACTOR ➔ Outer GREEN). Zero production code written before tests.
+- [ ] **Tests Green**: 100.00% full-stack test coverage maintained across statement, branch, function, and line metrics (`npm test` / `pnpm test`).
+- [ ] **Boundary Verified**: Cross-package boundary smoke tests passed against live running servers (`scripts/smoke_test.sh`).
+- [ ] **Zero Lints & Types**: 0 ESLint warnings and 0 TypeScript compilation errors (`npm run lint && npm run typecheck`).
+- [ ] **No Unverified Assumptions**: All behavior backed by tests, schema invariants, or verified command evidence.
+- [ ] **ADR Logged**: An Architectural Decision Record is logged in `memory.md` if architectural trade-offs were made.
+- [ ] **Documentation Clean**: Zero broken markdown links across workspace files and relevant knowledge documents updated.
+
+---
+
+## 4. Blocker Escalation & Risk Management
+
+- If a blocker or ambiguity arises, immediately transition the task to `BLOCKED`, halt execution, and interrogate the root cause.
+- Never guess or write speculative code to bypass an unresolved requirement.
+
+---
+
+## 5. Invariants, DO's & DONT's
+
+### DO's:
+- **DO:** Maintain strict WIP = 1 limit. Never work on multiple active tasks concurrently.
+- **DO:** Deliver features in vertical slices (UI ➔ API ➔ Domain ➔ DB) rather than isolated horizontal stubs.
+- **DO:** Apply SMART criteria to developer tasks, time-boxing them to under 4 hours.
+- **DO:** Halt and transition to `BLOCKED` whenever assumptions are required.
+- **DO:** Satisfy all 7 criteria of the Definition of Done before declaring any increment complete.
+
+### DONT's:
+- **DONT:** Never mark a task `DONE` with skipped, failing, or unwritten tests.
+- **DONT:** Never bypass the 5-Phase Agile Domain Lifecycle provenance gate.
+- **DONT:** Never create untracked, open-ended developer tasks without measurable completion tests.
+- **DONT:** Never leave unresolved blockers or silent errors in working branches.

package/docs/rules/react.md

@@ -0,0 +1,88 @@
+# 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. Invariants, DO's & DONT's
+
+### DO's:
+- **DO:** Use `shadcn/ui` components backed by `@radix-ui` primitives for all interactive elements.
+- **DO:** Use `@tanstack/react-query` (`useQuery`, `useMutation`) for all server data fetching, caching, and mutation invalidation.
+- **DO:** Validate all form inputs using formal Zod schemas and `react-hook-form` / `tanstack-form`.
+- **DO:** Display user feedback and errors using accessible ARIA live regions (`role="alert"` for errors, `role="status"` for confirmations) and `<ConfirmDialog>`.
+- **DO:** Synchronize pagination, active tabs, and search filters into URL search parameters.
+
+### DONT's:
+- **DONT:** Never use `window.alert()` or `window.confirm()`.
+- **DONT:** Never fetch data in raw `useEffect` hooks with manual `loading` / `error` boolean state.
+- **DONT:** Never manage multi-field forms using raw `useState` and manual imperative string validations.
+- **DONT:** Never use unstyled raw HTML select or dialog elements when `shadcn/ui` components exist.

package/docs/rules/relentless_questioning.md

@@ -0,0 +1,48 @@
+# Relentless Questioning Loop & Dynamic Interrogation Protocol
+
+> **Core Mandate:** Enforce context-aware, adaptive interrogation of requirements, technical constraints, and failure modes before code authoring, dynamically branching questions based on previous answers to eliminate all hidden assumptions.
+
+---
+
+## 1. The Context-Aware Interrogation Lifecycle
+
+Never write speculative code or draft implementation plans based on underspecified user prompts. Every non-trivial feature, database modification, or architectural task must pass through the **4-Stage Relentless Questioning Loop**:
+
+```
+1. CLASSIFY (Detect Archetype) ──► 2. ADAPTIVE BRANCHING (Context Questions) ──► 3. TENSION RECONCILIATION (Rule Conflicts) ──► 4. CONVERGENCE (Signed-Off Spec)
+```
+
+1. **Stage 1: Intent & Archetype Classification**: Analyze the incoming prompt to identify core domains (e.g. Financial/Ledger, Multi-Tenant Mutation, Async/Event-Driven, External Integration, Public API, or Read-Heavy Analytics).
+2. **Stage 2: Context-Aware Adaptive Branching**: Ask targeted questions in digestible batches (2–4 questions per turn). **Question $N+1$ must directly incorporate the answer to Question $N$**, exploring deep technical trade-offs rather than reciting generic checklists.
+3. **Stage 3: Architectural Tension Reconciliation**: If the user's proposed approach violates an existing workspace rule (e.g. dual-writes without an outbox, sparse nullable columns, or missing tenant isolation), immediately highlight the architectural conflict and propose compliant alternatives.
+4. **Stage 4: Convergence & Feature Alignment Specification (FAS)**: Lock down the scope with an unambiguous summary covering Invariants, Negative Scope (Non-Goals), Error Matrix, and Test Verification Strategy.
+
+---
+
+## 2. Adaptive Contextual Decision Branches
+
+Questions must dynamically pivot depending on the technical archetype:
+
+### Branch A: State Mutations & Financial Transactions
+*Trigger:* The feature involves balances, orders, payments, inventories, or status transitions.
+- *Adaptive Inquiries:* What isolation level is required (`REPEATABLE READ` vs `SERIALIZABLE`)? What is the idempotency key TTL? In the event of a downstream gateway failure, how is the compensating rollback (Saga) triggered? How is concurrent mutation race condition prevented (Optimistic Concurrency Control vs row lock)?
+
+### Branch B: Multi-Tenancy & Data Boundaries
+*Trigger:* The feature touches tenant-scoped entities or custom fields.
+- *Adaptive Inquiries:* How is the tenant context resolved if accessed via background workers? Which isolation model applies (AST interceptor, database RLS, or schema namespace)? If custom fields are needed, does the tenant's JSON Schema govern validation?
+
+### Branch C: Asynchronous Tasks & Event Streaming
+*Trigger:* The feature processes background jobs, emails, webhooks, or messaging.
+- *Adaptive Inquiries:* Is message delivery at-least-once or exactly-once? How are dual-writes prevented (Transactional Outbox)? How are poison pills and retries handled (Dead-Letter Queue with exponential backoff)?
+
+### Branch D: External Integrations & 3rd-Party APIs
+*Trigger:* The feature interacts with external SaaS, webhooks, or cloud services.
+- *Adaptive Inquiries:* What is the project-owned Port/Adapter boundary interface? What are the rate-limiting and circuit-breaking parameters? How are mock test doubles constructed without mocking third-party types directly?
+
+---
+
+## 3. Anti-Assumption Guardrails
+
+- **Zero Implicit Defaults**: If the user does not specify a behavior (e.g. timeout duration, error status code, rollback behavior), treat it as strictly unknown and ask.
+- **Explicit Non-Goals (Negative Scope)**: Every inquiry must establish what the feature will **NOT** do, preventing scope creep and unrequested architectural bloat.
+- **Mandatory User Confirmation**: Never transition from interrogation to code generation without an explicit confirmation from the user on the synthesized alignment specification.

package/docs/rules/requirements_engineering.md

@@ -0,0 +1,113 @@
+# Requirements Engineering, INVEST Stories & Gherkin Criteria
+
+> **Core Mandate:** Decompose business requirements into vertically sliced INVEST user stories, executable Gherkin acceptance criteria, and exhaustive edge case matrices, acknowledging that stories are conversation starters rather than full specification documents.
+
+---
+
+## 1. Are User Stories Requirements?
+
+In modern product engineering (per Scrum.org and XP principles), **user stories are NOT requirements**. Rather, a user story is one specific, highly effective technique used to *express, capture, and explore* user-centric requirements.
+
+### Key Distinctions
+- **A Token for Conversation:** A user story is a "placeholder" or token promising a future conversation. It captures the essence, not every granular detail upfront.
+- **The "Pidgin Language" Bridge:** A pidgin language is a simplified common language that allows people with different native tongues to trade and work together. User stories act as a pidgin language bridging the business/customer perspective and the software engineering architecture without forcing either side to abandon their domain language.
+- **Ron Jeffries' 3 C's of User Stories:**
+  1. **Card:** The physical index card or digital ticket capturing the intent (`As a... I want to... So that...`).
+  2. **Conversation:** The collaborative discussion between Product Owner, stakeholders, and developers where details and trade-offs are co-created.
+  3. **Confirmation:** The executable acceptance criteria and automated tests that prove whether the story satisfies its intent.
+
+### Non-Story Requirements
+Not all system requirements originate from an end-user persona or fit the user story syntax. High-integrity systems also require:
+- **System Invariants:** Core domain rules (e.g., "A transaction cannot be completed without a verified payment instrument").
+- **Non-Functional Requirements (NFRs):** Latency SLAs, encryption standards, concurrency limits, and accessibility compliance (WCAG 2.2 AA).
+- **Architectural Spikes:** Time-boxed exploratory investigations to resolve technical unknowns.
+- **Regulatory & Security Controls:** SOC 2 audit log immutability, GDPR data erasure rights, and OWASP Top 10 defenses.
+
+These requirements should be operationalized as explicit acceptance constraints, architectural fitness functions, or dedicated technical backlog items.
+
+---
+
+## 2. INVEST User Story Framework & Vertical Cake Slicing
+
+Ensure every user story satisfies Bill Wake's **INVEST** criteria:
+
+- **I - Independent:** Sliced vertically to minimize conceptual overlap. Can be scheduled, implemented, and released in any sequence without blocking peer stories.
+- **N - Negotiable:** Captures the core essence and problem space, not a rigid implementation contract. Specific details are co-created during pair programming and TDD.
+- **V - Valuable:** Delivers observable, direct benefit to the customer or business stakeholder.
+- **E - Estimable:** Well-understood and right-sized so the team can gauge complexity. Unknowns are resolved via prior time-boxed spikes.
+- **S - Small:** Sized to be completed within 1–2 development days. Small stories yield higher estimation accuracy and rapid feedback.
+- **T - Testable:** Accompanied by concrete pass/fail assertions. Non-functional requirements are operationalized into automated tests early.
+
+### The Multi-Layer Cake Metaphor (Vertical Slicing)
+Think of a complete feature as a multi-layer cake:
+```
+┌──────────────────────────────────────┐
+│ Presentation / UI Layer              │
+├──────────────────────────────────────┤
+│ Business Logic & Application Use Case│
+├──────────────────────────────────────┤
+│ Domain Invariants & Entities         │
+├──────────────────────────────────────┤
+│ Persistence & Database Layer         │
+└──────────────────────────────────────┘
+                   ▲
+                   │
+           Vertical Cake Slice
+   (Customer gets a taste of every layer)
+```
+- **Horizontal Slicing (Anti-Pattern):** Implementing only the database schema or only the UI mock. A full database table has zero observable value to the customer without presentation and logic layers.
+- **Vertical Slicing (Golden Standard):** Slicing thin through all layers (UI ➔ API ➔ Domain ➔ DB). Even a minimal vertical slice provides working functionality that can be deployed, tested, and validated empirically.
+
+---
+
+## 3. Executable Gherkin Acceptance Criteria
+
+Draft concrete, actionable scenarios directly convertible into automated acceptance tests:
+
+```gherkin
+Scenario: Successful Digital Agreement Execution
+  Given an authenticated customer with an approved application
+  And the agreement is in "PENDING_SIGNATURE" status
+  When the customer provides their legal name "Alice Smith" and confirms agreement
+  Then the response status is 200 OK
+  And the agreement status transitions to "ACTIVE"
+  And an execution audit record is persisted with timestamp, actorId, and IP address
+  And a transactional confirmation notification is queued for delivery
+```
+
+### Writing Rules for Gherkin Scenarios
+- **Use Active Voice:** State explicit actor actions (`When the user clicks "Confirm Agreement"` rather than passive `When the button is clicked`).
+- **One Observable Behavior Per Scenario:** Focus each scenario on one specific state transition or business invariant.
+- **Cover Both Happy and Unhappy Paths:** Every feature must include positive paths and negative failure assertions.
+
+---
+
+## 4. Negative Scope & Edge Case Matrices
+
+- **Out-of-Scope (Non-Goals):** Explicitly document what will NOT be built in this increment to prevent scope creep and align expectations.
+- **Edge Case Matrix:** Map all potential failure states to standardized RFC 7807 problem details and HTTP status codes:
+  - `400 Bad Request`: Schema validation failures, missing required fields.
+  - `401 Unauthorized`: Missing or invalid session tokens.
+  - `403 Forbidden`: Cross-tenant boundary violations, role privilege deficits.
+  - `404 Not Found`: Resource non-existence (or masked enumeration).
+  - `409 Conflict`: Duplicate unique constraints, state machine transition invalidity.
+  - `422 Unprocessable Entity`: Semantic domain invariant violations.
+  - `429 Too Many Requests`: Rate limiter token exhaustion.
+  - `500 Internal Server Error`: Unhandled upstream infrastructure failures.
+
+---
+
+## 5. Invariants, DO's & DONT's
+
+### DO's:
+- **DO:** Embody Ron Jeffries' 3 C's (Card, Conversation, Confirmation) for all user-facing stories.
+- **DO:** Slice user stories vertically through all layers (UI ➔ API ➔ Domain ➔ DB).
+- **DO:** Model technical constraints, invariants, and spikes as explicit non-story requirements.
+- **DO:** Write Gherkin scenarios with active voice covering happy and unhappy paths.
+- **DO:** Map edge cases to standard HTTP status codes and RFC 7807 problem details.
+
+### DONT's:
+- **DONT:** Never write horizontal technical stories that lack end-user observable value.
+- **DONT:** Never treat user stories as complete formal specification documents.
+- **DONT:** Never omit negative scope (out-of-scope / non-goals) in requirements.
+- **DONT:** Never skip edge cases or map errors to ambiguous status codes.

package/docs/rules/rest_api_conventions.md

@@ -0,0 +1,62 @@
+# 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.
+
+---
+
+## 5. Invariants, DO's & DONT's
+
+### DO's:
+- **DO:** Return standard HTTP status codes (`200 OK`, `201 Created`, `204 No Content`, `400 Bad Request`, `404 Not Found`, `409 Conflict`).
+- **DO:** Return RFC 7807 Problem Details envelopes for all `4xx` and `5xx` error responses.
+- **DO:** Mask cross-tenant resources with `404 Not Found` (enumeration masking) to avoid leaking existence of foreign records.
+- **DO:** Implement full lifecycle CRUD verbs across all primary resources.
+- **DO:** Support defensive trailing slashes on health and readiness probes.
+
+### DONT's:
+- **DONT:** Never return `200 OK` with an error object inside the response body (the anti-pattern of masking errors).
+- **DONT:** Never return detailed database stack traces or raw internal errors to client API callers in production.
+- **DONT:** Never use singular nouns for collection endpoints (use `/api/v1/users`, not `/api/v1/user`).