azcodr 1.1.0 → 1.2.1

package/docs/rules/domain_driven_design.md

@@ -1,10 +1,35 @@
 # Domain-Driven Design (DDD) & Ubiquitous Language
 
-> **Core Mandate:** Establish unambiguous Ubiquitous Language definitions, isolate Bounded Contexts, guarantee Domain-Code Language Agreement across all architectural layers, and separate Value Objects, Entities, and Aggregates.
+> **Core Mandate:** Separate Problem Space from Solution Space, establish unambiguous Ubiquitous Language definitions, isolate Bounded Contexts, guarantee Domain-Code Language Agreement, and protect Aggregate invariants.
 
 ---
 
-## 1. Domain-Code Language Agreement
+## 1. Problem Space vs. Solution Space (Evans & Vernon)
+
+Software engineering fails when teams jump directly into the **Solution Space** (choosing languages, frameworks, databases, and microservices) before fully defining the **Problem Space**.
+
+```
+  ┌────────────────────────────────────────────────────────────────────────┐
+  │                           THE PROBLEM SPACE                            │
+  │  Business Problem ➔ Subdomains (Core/Supporting/Generic) ➔ Invariants  │
+  │  Operational Constraints: Execution target, Latency budget, GC limits  │
+  └───────────────────────────────────┬────────────────────────────────────┘
+                                      │ Shapes & Dictates
+                                      ▼
+  ┌────────────────────────────────────────────────────────────────────────┐
+  │                           THE SOLUTION SPACE                           │
+  │  Bounded Contexts ➔ Architectural Style (DOD, Hexagonal, Pipeline)      │
+  │  Emergent Toolchain: Programming Language, Runtime, Persistence        │
+  └────────────────────────────────────────────────────────────────────────┘
+```
+
+- **The Problem Space (The Essence - Fred Brooks):** Concerns *what* problem is being solved, the entities, state transitions, and operational constraints (e.g. 16.6ms frame budget for games, zero-install browser sandbox for extensions, or ACID compliance for banking). **Zero technology, stack, or database choices are permitted in the Problem Space.**
+- **The Solution Space (The Accidents):** Concerns *how* the system is realized. Runtimes, programming languages (C, Rust, TS, Go, Java), and storage engines are **emergent outputs** derived strictly from Problem Space constraints.
+- **The Golden Hammer Anti-Pattern:** Selecting tools (e.g., "Let's use Next.js and PostgreSQL") before mapping problem constraints forces the domain to fit the tool, creating massive accidental complexity.
+
+---
+
+## 2. Domain-Code Language Agreement
 
 The fundamental premise of Domain-Driven Design (Eric Evans) is that **the code is the model, and the model is the code**. Any divergence between the mental model of domain experts and the source code is called **Linguistic Drift**.
 
@@ -16,7 +41,7 @@ The fundamental premise of Domain-Driven Design (Eric Evans) is that **the code
 
 ---
 
-## 2. Living Ubiquitous Language Glossary
+## 3. Living Ubiquitous Language Glossary
 
 Every project must maintain an authoritative, version-controlled **Living Ubiquitous Language Glossary** at [`docs/knowledge/ubiquitous_language.md`](../knowledge/ubiquitous_language.md).
 
@@ -30,7 +55,7 @@ Each entry must define:
 
 ---
 
-## 3. Automated Enforcement & Linters
+## 4. Automated Enforcement & Linters
 
 To prevent linguistic drift over time, teams must employ mechanical enforcement:
 
@@ -60,25 +85,10 @@ Acceptance criteria must be written strictly in Ubiquitous Language, serving as
 
 ---
 
-## 4. Tactical Patterns & Invariants
+## 5. Tactical Patterns & Invariants
 
 1. **Entities**: Objects defined by identity that persists across state changes (e.g. `User`, `Order`, `Invoice`).
 2. **Value Objects**: Immutable objects defined strictly by their attributes with no identity (e.g. `Money`, `DateRange`, `EmailAddress`).
 3. **Aggregates & Aggregate Roots**: Clusters of domain objects treated as a single transactional consistency boundary. All mutations must pass through explicit methods on the Aggregate Root.
 4. **Anti-Corruption Layer (ACL)**: When integrating with third-party APIs or legacy systems that use different terminology, translate external payloads into the internal Ubiquitous Language at the boundary adapter before they enter the domain core.
-
----
-
-## 5. Invariants (DO's & DONT's)
-
-### DO
-- **DO** use identical terminology in domain conversations, PRDs, code, database schemas, and user interfaces.
-- **DO** maintain an authoritative `ubiquitous_language.md` and treat it as a binding architectural contract.
-- **DO** use branded nominal types for IDs to catch cross-entity domain mixups at compile time.
-- **DO** translate foreign data structures at the perimeter using an Anti-Corruption Layer (ACL).
-
-### DONT
-- **DONT** use technical jargon (`dto`, `entity_row`, `table_item`) in domain business logic.
-- **DONT** allow competing synonyms for the same concept within the same Bounded Context.
-- **DONT** overload words with dual meanings across technical architecture and business domain.
-- **DONT** rename domain terms in code without updating the living glossary and recording an ADR.
+5. **Cross-Aggregate Coordination in Use Cases**: While an Aggregate Root guards its own internal invariants, business operations frequently span multiple aggregates (e.g. reserving an inventory item for an agreement). Application use cases or orchestrators must coordinate aggregate transitions atomically: asserting resource availability prior to state change, transitioning the constrained entity (e.g. `ALLOCATED`), and restoring state (`AVAILABLE`) upon cancellation, avoiding double-allocation race conditions without coupling aggregates directly.

package/docs/rules/error_handling.md

@@ -1,6 +1,6 @@
 # Error Handling, Request Tracing & Schema Validation
 
-> **Core Mandate:** Enforce fail-fast schema validation at startup, structured OpenTelemetry/JSON request tracing, and standardized RFC 7807 / REST error envelopes.
+> **Core Mandate:** Enforce fail-fast schema validation at startup, structured OpenTelemetry/JSON request tracing, standardized RFC 7807 problem details, and an explicit canonical DomainError hierarchy.
 
 ---
 
@@ -37,3 +37,16 @@ Enforce a uniform error envelope across all external HTTP/REST endpoints conform
 ```
 
 - **Production Masking Invariant**: Strictly mask internal database error codes, raw SQL queries, file system paths, and stack traces from external client responses in non-local environments.
+
+---
+
+## 4. Canonical Domain Error Hierarchy & Type-Safe Narrowing
+
+- **Canonical DomainError Hierarchy**: Model operational domain failures using an explicit `DomainError` base class with canonical subclasses:
+  - `ValidationError` (maps to HTTP 400 / 422)
+  - `UnauthorizedError` (maps to HTTP 401)
+  - `ForbiddenError` (maps to HTTP 403)
+  - `NotFoundError` (maps to HTTP 404)
+  - `ConflictError` (maps to HTTP 409)
+  - `ExpiredError` (maps to HTTP 410)
+- **Eliminate Untyped Error Monkey-Patching**: Strictly prohibit monkey-patching arbitrary properties onto error objects at catch sites (e.g. `(err as any).statusCode = 404`). Use clean `instanceof` narrowing in HTTP error middleware to map domain errors deterministically to RFC 7807 status codes with full compiler type safety.

package/docs/rules/multitenancy_isolation.md

@@ -14,6 +14,8 @@ Resolve tenant identity dynamically in an inbound gateway or middleware pipeline
 
 *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

package/docs/rules/product_ownership.md

@@ -130,21 +130,3 @@ Following Gunther Verheyen's backlog topology, the Product Backlog serves as an
 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

@@ -47,20 +47,3 @@ A user story or task is only marked `DONE` when all of the following verifiable
 
 - 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

@@ -72,17 +72,7 @@
 
 ---
 
-## 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.
+## 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/requirements_engineering.md

@@ -94,20 +94,3 @@ Scenario: Successful Digital Agreement Execution
   - `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

@@ -44,19 +44,3 @@
   - `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`).

package/docs/rules/test_driven_development.md

@@ -83,24 +83,46 @@ Deviating from this lifecycle introduces catastrophic defects and architectural
 | **Skipping Outer Acceptance Tests** | In-memory unit tests pass, but user interactions and network routing fail. | "The In-Memory Supertest Illusion": App says "Offline/Connecting" while 100% unit tests pass. |
 | **Skipping the Refactor Phase** | Technical debt accumulates immediately behind green tests. | Code rot, duplicated logic, bloated monolithic functions (> 30 lines), violated DRY/SLAP. |
 
-### The Immutable Laws of TDD Execution:
-1. **No Production Code Without a Failing Test:** You are not allowed to write any production code unless it is to make a failing unit or acceptance test pass.
-2. **No Test Without Prior Domain Understanding:** You are not allowed to write a test without knowing the Ubiquitous Language, Aggregate Root, and business invariants it asserts.
-3. **Minimal Code Only:** Write only the minimal amount of code necessary to turn the failing test green. Do not anticipate speculative future requirements.
-4. **Refactor Under Green Only:** Never alter production code structure while tests are red. Refactor only when all existing assertions are green.
-
-### DO's:
-- **DO:** Strictly adhere to the 5-Phase Agile Domain Lifecycle: Requirements ➔ Domain Analysis ➔ Outer Acceptance Test (RED) ➔ Inner Unit Test (RED-GREEN-REFACTOR) ➔ Outer Verification (GREEN).
-- **DO:** Follow Outside-In TDD (London School): Outer acceptance test ➔ collaborator discovery ➔ unit tests with test doubles.
-- **DO:** Maintain 100.00% line, branch, statement, and function coverage across all backend, contract, and frontend suites.
-- **DO:** Verify cross-package integration boundaries (Vite dev server reverse proxy, real network sockets, HTTP client JSON parsing) with automated full-stack smoke tests (`scripts/smoke_test.sh`).
-- **DO:** Keep functions small (under 20–30 lines) adhering to Single Level of Abstraction (SLAP) and Command-Query Separation (CQS).
-
-### DONT's:
-- **DONT:** Never write a single line of production code without an existing failing test driving it.
-- **DONT:** Never write a test without prior domain analysis (Ubiquitous Language and invariant definition). Tests must assert domain invariants, not arbitrary syntax.
-- **DONT:** Never mock types you do not own; always wrap third-party dependencies in application-owned adapters.
-- **DONT:** Never equate in-memory test double passes (e.g. Supertest against in-memory Express instances) with real network transport, reverse proxying, or end-to-end user connectivity.
-- **DONT:** Never skip the Refactor phase under green; technical debt must not accumulate behind green tests.
-- **DONT:** Never use arbitrary `setTimeout()` or `sleep()` in tests; use deterministic event polling (`waitFor`).
+### The Immutable Three Laws of TDD (Uncle Bob & Kent Beck):
+1. **First Law:** You are not allowed to write any production code unless it is to make a single failing unit or acceptance test pass.
+2. **Second Law (Strict Incremental Boundary):** You are not allowed to write any more of a unit test than is sufficient to fail; and compilation failures are failures.
+3. **Third Law (Minimal Production Code):** You are not allowed to write any more production code than is sufficient to pass the one currently failing test.
+
+---
+
+## 4. The Batch-Test Anti-Pattern & The Incremental Nano-Cycle
+
+### The "Test-First Waterfall" Anti-Pattern (BANNED)
+A rampant anti-pattern in AI coding is dumping 10–20 test cases in a single test file, and then writing a 300-line implementation file in one shot so all tests pass simultaneously. **This is strictly prohibited.**
+- **Why It Fails:** Writing all tests upfront is Waterfall in disguise. It forces the AI to hallucinate and lock in speculative method signatures and class structures before any code runs. If test #3 reveals a design flaw, tests #4–20 are broken legacy code before running.
+- **Falsifiability Failure:** When 20 tests fail at once, you never prove that each individual assertion would catch its specific regression. Many batch tests are tautologies that pass by coincidence.
+
+### The Mandatory Incremental Nano-Cycle
+Every collaborator discovered in Phase 4 must progress through micro-cycles of one behavior at a time:
+1. **RED (Micro-Assertion):** Write **ONE** test asserting a single micro-behavior (e.g. `expect(cart.total()).toBe(0)`).
+2. **VERIFY RED:** Run the test suite (`npm test`). **Inspect and verify the specific failure message** (e.g. "method not defined" or "expected 0, got undefined"). Never skip running the test while RED.
+3. **GREEN (Minimal Implementation):** Write the **absolute minimum production code** required to pass the single failing assertion (even hardcoding `return 0` if appropriate).
+4. **VERIFY GREEN:** Run the test suite. Confirm the test turns green with zero side effects.
+5. **REFACTOR (Under Green):** Clean up names, eliminate duplication (DRY), enforce SLAP and Clean Code standards while tests remain 100% green.
+6. **REPEAT:** Move to the next micro-behavior (e.g. `cart with 1 item returns item price`).
+
+---
+
+## 5. Ping-Pong Pair Programming Protocol with AI
+
+When pairing with the human developer, operate in true **Ping-Pong TDD**:
+```
+  ┌─────────────────────────────────────────────────────────────┐
+  │                 PING-PONG PAIR PROGRAMMING                  │
+  │                                                             │
+  │  Turn 1 [Partner A]: Writes ONE micro-test assertion (RED)  │
+  │  Turn 2 [System]:    Runs test & displays verified failure  │
+  │  Turn 3 [Partner B]: Writes MINIMAL code to pass (GREEN)    │
+  │  Turn 4 [System]:    Runs test & displays verified pass     │
+  │  Turn 5 [Both]:      Refactors under green (REFACTOR)       │
+  │  Turn 6:             Roles swap; repeat for next behavior   │
+  └─────────────────────────────────────────────────────────────┘
+```
+- **Collaborative Steering**: The human developer can write the test while the AI writes the minimal pass, or the AI can present each micro-test and await confirmation before implementing.
+- **Continuous Alignment**: Design and data structures emerge organically through mutual feedback rather than monolithic code dumps.
 

package/docs/rules/transactional_email.md

@@ -1,20 +1,27 @@
 # Transactional Email Subsystem
 
-> **Core Mandate:** Enforce declarative email templates, safe variable interpolation, and deterministic local test delivery through Mailpit SMTP routing.
+> **Core Mandate:** Enforce declarative email templates, strict HTML sanitization, decoupled asynchronous dispatch, and deterministic local test delivery through Mailpit SMTP routing.
 
 ---
 
 ## 1. Declarative & Typed Email Templates
 
 - **Declarative Template Definition**: Author transactional email templates using language-agnostic markup formats (such as **MJML - Mailjet Markup Language**) or typed component schemas to ensure cross-client rendering consistency across Outlook, Gmail, and Apple Mail.
-- **Safe Variable Interpolation**: Strictly prohibit unescaped raw HTML string concatenation. Always use context-aware template engines that automatically escape HTML special characters to prevent Cross-Site Scripting (XSS) and injection vulnerabilities.
+- **Strict HTML Sanitization & Injection Defense**: Strictly prohibit unescaped raw HTML string concatenation. Centralize variable interpolation through a strict escaping utility neutralizing `&`, `<`, `>`, `"`, and `'` to prevent Cross-Site Scripting (XSS) and template injection vulnerabilities.
 
 ---
 
-## 2. Local Mail Transport & Integration Verification
+## 2. Decoupled Transport & Background Queues
+
+- **Async Queue Decoupling**: Decouple notification delivery from synchronous HTTP request-response cycles via an asynchronous job queue (e.g. BullMQ, Celery, or Transactional Outbox workers). API responses must never block on external network SMTP socket round-trips.
+- **Zero-Dependency Native Sockets**: Prefer socket-based SMTP adapters adhering to RFC 5321 commands over heavy third-party mailer libraries to eliminate supply chain risks and transitive dependencies.
+
+---
+
+## 3. Local Mail Transport & Integration Verification
 
 - **Local SMTP via Mailpit**:
   - Route local and CI SMTP traffic to **Mailpit** (SMTP port 1025 / Web UI port 8025).
   - Never route emails to public mail transfer agents (MTAs) or external API gateways during automated test runs or local development.
 - **Deterministic API Assertion Protocol**:
-  - Assert email delivery in integration tests by querying Mailpit's REST API (`GET /api/v1/messages`) to inspect recipient headers, delivery status, HTML body content, and verification links without timing dependencies.
+  - Assert email delivery in integration tests by querying Mailpit's REST API (`GET /api/v1/messages`) or testing against in-memory notification sinks to inspect recipient headers, delivery status, HTML body content, and verification links without timing dependencies.

package/docs/rules/ui_ux_architecture.md

@@ -139,30 +139,9 @@ Per [`docs/rules/ui_navigation.md`](./ui_navigation.md), all view state that rep
 4. **Pagination**: `?page=2&pageSize=25`
 5. **Drawers / Modals**: `?drawer=resource-102` or `?modal=create-order`
 
----
+## 7. Production UI Hygiene & Resilience Standards
 
-## 7. Invariants, DO's & DONT's
-
-### DO:
-- **DO** execute the 7-Pillar Design Architecture Triage before writing any UI code.
-- **DO** provide a collapsible left sidebar for operators that transitions into a slim 64px icon rail with hover tooltips and persists state in `localStorage`.
-- **DO** provide a dedicated, consumer-focused `/portal` layout for Members/Consumers with top and mobile-bottom navigation.
-- **DO** provide a public `/catalog` view for unauthenticated visitors to discover resources.
-- **DO** isolate developer demo personas into a dedicated dev-only floating toolbar (`import.meta.env.DEV`), completely decoupled from the real sign-in form.
-- **DO** enforce route guards on all routes, automatically redirecting users according to their authenticated role.
-- **DO** synchronize tabs, search terms, and pagination with URL search parameters.
-- **DO** use accessible Radix UI dialogs (`<ConfirmDialog>`) for destructive actions and ARIA live regions for status alerts.
-- **DO** synchronize authentication and tenant selection across browser tabs via `window.addEventListener('storage')`, and isolate complex subcomponents or page outlets using accessible `<ErrorBoundary>` components to prevent unhandled render exceptions from crashing the application shell.
-- **DO** decouple all technical internal telemetry (API gateway connection states, hexagonal port health, database adapter indicators, and active security roles) from user-facing screens and confine them exclusively to development tools and harnesses gated by `import.meta.env.DEV`.
-- **DO** centralize all user interface copy, status labels, error notifications, action titles, and templated messages into configuration constants (`UI_STRINGS`) to eliminate scattered hardcoded strings.
-
-### DONT:
-- **DONT** build UI views on assumptions without completing the Design Architecture Triage Gate.
-- **DONT** embed mock/demo personas inside user-facing login or registration forms.
-- **DONT** force Member/Consumer users to navigate the enterprise operator sidebar with disabled buttons.
-- **DONT** expose multi-tenant organization switchers or system audit fields to consumer roles.
-- **DONT** expose internal architecture jargon (e.g. "ACID ledger", "Hexagonal ports", "API Connected", "Active Role") in production user-facing or administrator views.
-- **DONT** hardcode error messages, status labels, or button copy directly in page components; reference centralized configuration constants.
-- **DONT** use browser-native `window.alert()` or `window.confirm()` popups.
-- **DONT** rely solely on hiding UI buttons to enforce authorization; always wrap routes in `<ProtectedRoute>`.
-- **DONT** lose search queries or active tab states upon page reload; always sync to URL search params.
+- **Multi-Tab State Synchronization**: Synchronize authentication and tenant selection across browser tabs using native `window.addEventListener('storage')`.
+- **Fault-Tolerant Error Boundaries**: Wrap complex widgets, charts, and page outlets in accessible `<ErrorBoundary>` components to prevent runtime render exceptions from crashing the persistent application shell.
+- **Strict Decoupling of Diagnostics & Telemetry**: Never expose internal architectural diagnostics (port health, connection badges, active role indicators) in production user-facing screens; gate diagnostic widgets strictly behind `import.meta.env.DEV`.
+- **Centralized UI Copy (`UI_STRINGS`)**: Centralize all user interface copy, status labels, error notifications, and action button labels into configuration constants (`UI_STRINGS`) rather than scattering hardcoded strings across templates.

package/docs/rules/upstream_synchronization.md

@@ -51,18 +51,3 @@ Every upstream-bound proposal logged to `changes.md` must follow the standardize
 - **Description:** Concise summary of the mutation or invariant added.
 - **Domain Filter Verification:** Verified 100% generic; purged of all project-specific business entities and models.
 ```
-
----
-
-## 4. Invariants, DO's & DONT's
-
-### DO's:
-- **DO:** Record candidate generic architectural improvements in `changes.md`.
-- **DO:** Distill all lessons and post-mortems into generic, domain-agnostic language before logging.
-- **DO:** Colocate DOs and DONTs directly inside the relevant atomic rules and skills.
-- **DO:** Verify that all entries in `changes.md` are 100% stack- and domain-agnostic.
-
-### DONT's:
-- **DONT:** Never execute automated upstream git cloning or merge AI workflows during project work.
-- **DONT:** Never contaminate `changes.md` with project-specific business logic, schemas, or customer requirements.
-- **DONT:** Never leave machine-specific or absolute user paths in scripts or documentation.

package/docs/rules/workflow_state_machines.md

@@ -98,21 +98,3 @@ Every state change across any entity or workflow MUST be immutably recorded in a
 | `reason` | String? | Optional justification or audit comment. |
 | `metadata` | JSON? | Snapshot of transition context or rule evaluation. |
 | `createdAt` | DateTime | Immutable timestamp of transition. |
-
----
-
-## 4. Invariants (DO's & DONT's)
-
-### DO
-- **DO** enforce core business invariants inside Aggregate Roots using strongly-typed state transitions.
-- **DO** decouple core domain state from operational display stages or tenant-specific sub-statuses.
-- **DO** use non-Turing complete expression languages (CEL) to evaluate dynamic transition guards.
-- **DO** maintain an immutable transition history table for all status alterations.
-- **DO** validate state transition graphs at creation time to prevent dead-end or unreachable states.
-
-### DONT
-- **DONT** make financial or legal integrity states (e.g., `SETTLED`, `CANCELLED`, `REFUNDED`) freely rewritable by tenant configuration.
-- **DONT** expose generic status setters (`entity.setStatus(newStatus)`) on domain models.
-- **DONT** execute untrusted scripts or dynamic strings in the host runtime for workflow evaluations.
-- **DONT** allow a workflow orchestrator to bypass aggregate invariants by directly updating database columns.
-- **DONT** delete historical state transitions; status audit logs must be append-only.