azcodr 1.0.1 → 1.2.0

package/changes.md

@@ -34,3 +34,29 @@ When an AI agent or engineer discovers a generic architectural improvement, bug
 - **Rationale:** Remove fragile git repo resolution and merge scripts; replace with atomic change logging in `changes.md`.
 - **Description:** Retired `merge-ai` skill and removed machine-specific hardcoded paths. All upstream improvements are now recorded atomically in `changes.md`.
 - **Domain Filter Verification:** Verified 100% generic.
+
+### [2026-09-25] Harden CLI, achieve 100% test coverage gates, add multi-OS CI workflow, and TypeScript declarations
+- **Category:** CLI
+- **Target File(s):** bin/azcodr.js, lib/scaffold.js, lib/index.d.ts, .github/workflows/ci.yml
+- **Rationale:** Fulfill 100.00% test coverage mandate, cross-platform CI matrix, and library type safety
+- **Description:** Remediate gap assessment findings: add --dry-run and --silent flags, enforce 100.00% line/branch/function coverage gates, add GitHub Actions CI matrix across Node 18/20/22/24 and Linux/macOS/Windows, add .editorconfig template item, and export ambient TypeScript typings.
+- **Domain Filter Verification:** Verified 100% generic; purged of all project-specific business entities and models.
+
+### [2026-09-25] Resolve macOS/Windows Git Case-Collision and Cross-Version CI Matrix Coverage
+- **Category:** Infrastructure & CI
+- **Target File(s):** .gitignore, lib/scaffold.js, scripts/test_coverage.js, validate_agentic_configs.sh
+- **Rationale:** Ensure flawless cross-platform and multi-version Node execution across macOS, Windows, and Linux on Node 18, 20, 22, 24.
+- **Description:** Untracked agents.md from Git to prevent cyclic symlink overwrite on case-insensitive filesystems; hardened ensureSymlink with isSameCaseInsensitiveFile check; added cross-version test coverage runner script; updated npm test runner to use native discovery.
+- **Domain Filter Verification:** Verified 100% generic; purged of all project-specific business entities and models.
+
+### [2026-09-25] Problem-First Architecture, Evolutionary Tipping Points, and Incremental Nano-Cycle TDD
+- **Category:** Architecture, Rule & Skill
+- **Target File(s):** `AGENTS.md`, `docs/rules/clean_code.md`, `docs/rules/domain_driven_design.md`, `docs/rules/test_driven_development.md`, `.agents/skills/lets-build/SKILL.md`, `.agents/skills/lets-build/references/architecture_interview_matrix.md`, `.agents/skills/lets-build/scripts/bootstrap_workspace.sh`, `memory.md`
+- **Rationale:** Eliminate tool-first bias ("Solution-in-Search-of-a-Problem"), stop accidental complexity (as seen in `force-dark-light` where Chrome extension received Kubernetes and OpenAPI specs), prevent AI-accelerated architectural drift, and halt the "Test-First Waterfall" batch-test anti-pattern.
+- **Description:** 
+  1. Enforced Problem Space vs Solution Space decoupling with zero tool bias.
+  2. Made scaffolding strictly topology-aware (Web SaaS, Browser Extension, Game/Engine, CLI, Library) with zero speculative bloat.
+  3. Codified Evolutionary Architecture, the 5 Architectural Tipping Points, and Kent Beck's "Refactor-Before-Add" protocol.
+  4. Codified Uncle Bob's Three Laws of TDD, banned batch-test dumps, and introduced the Incremental Nano-Cycle and Ping-Pong Pair Programming protocol.
+- **Domain Filter Verification:** Verified 100% generic; applicable across any language, stack, and project topology.
+

package/docs/rules/api_versioning.md

@@ -111,18 +111,3 @@ specs/
 │       └── openapi.yaml
 ```
 
----
-
-## 5. Invariants, DO's & DONT's
-
-### DO's:
-- **DO:** Prefix all public REST endpoints with major version identifiers (`/api/v1/`, `/api/v2/`).
-- **DO:** Bump MAJOR and cut a new `/api/v2/` prefix whenever request or response breaking changes occur.
-- **DO:** Inject RFC 8594 `Sunset` and `Deprecation` headers on all retired endpoints and provide a 90-day grace period.
-- **DO:** Organize specs into versioned folders (`specs/openapi/v1/`, `v2/`) with an interactive Swagger selector.
-
-### DONT's:
-- **DONT:** Never expose minor or patch numbers in the URL path (e.g. `/api/v1.2/`).
-- **DONT:** Never introduce breaking schema or status code changes within an existing major version.
-- **DONT:** Never delete an active endpoint without a formal deprecation lifecycle.
-

package/docs/rules/clean_code.md

@@ -23,3 +23,40 @@
 - **Orthogonality**: Eliminate coupling between unrelated modules. Changing one component must not cascade unexpected side effects into another.
 - **Broken Windows Theory**: Never leave bad code, failing lint checks, or out-of-date documentation unfixed. Fix defects immediately before entropy normalizes.
 - **Design by Contract (DbC)**: Define explicit preconditions (runtime boundary validation), postconditions (guaranteed response envelopes), and domain invariants.
+
+---
+
+## 3. Evolutionary Architecture & Architectural Tipping Points (Ford, Parsons & Fowler)
+
+Architecture is not a static Day 1 monument; it evolves incrementally as complexity grows. AI coding tools naturally take the path of least resistance (local token minimization), repeatedly appending code to simple files until they rot into a Big Ball of Mud. To eliminate **AI-Accelerated Architectural Drift**, the agent must pause and execute an architectural upgrade whenever code hits a **Deterministic Tipping Point**:
+
+| Simple Baseline (Day 1) | Tipping Point / Mutation Trigger | Required Architectural Upgrade |
+|---|---|---|
+| **Flat Script / Single File** | File exceeds **250 lines**, or coordinates **>2 distinct I/O resources**, or is imported by **>3 distinct callers**. | **Extract Modular Subsystems:** Decouple domain logic from platform I/O; split into dedicated, focused submodules. |
+| **Inline `if/else` or `switch` Cascades** | **Rule of Three:** The 3rd branching variant, payment provider, or protocol format is introduced. | **Strategy Pattern / Registry:** Replace conditional branching with a polymorphic Strategy interface or handler registry; update `memory.md`. |
+| **In-Memory Store / Global State** | State requires **concurrent mutations**, **persistence across process restarts**, or **transactional rollback**. | **Repository Pattern & Persistence Port:** Introduce an explicit storage port contract; swap in-memory mock for a persistent database adapter. |
+| **Direct Platform / Third-Party Calls** | External SDK or platform API is called from **>2 places**, or SDK throws untyped exceptions across boundaries. | **Adapter Pattern (Anti-Corruption Layer):** Wrap external SDK inside an application-owned port interface; mock only the owned interface in tests. |
+| **Monolithic Domain Model** | The same business noun represents divergent lifecycles or definitions across workflows (e.g. `User` in Auth vs `User` in Billing). | **Bounded Context Split:** Separate into isolated domain contexts with explicit DTO / Anti-Corruption translation between them. |
+
+---
+
+## 4. The "Refactor-Before-Add" Protocol (Kent Beck's Rule)
+
+> *"Make the change easy (warning: this may be hard), then make the easy change."* — Kent Beck
+
+Before writing production code for any new feature or user story, the agent must execute the **Refactor-Before-Add Check**:
+1. **Assess Tipping Points**: Will adding this requirement cause any module, function, or data structure to cross an architectural tipping point?
+2. **Phase A — Structural Refactoring (Under Green)**: If yes, refactor the existing architecture *first* while existing test suites remain 100% green. Zero behavioral changes; purely structural evolution.
+3. **Phase B — ADR Mutation**: When an architectural tipping point is crossed, log a Lightweight Architectural Decision Record in `memory.md` summarizing the new structural boundary and trade-off.
+4. **Phase C — Feature Implementation (Inner TDD)**: Only once the architecture cleanly accommodates the new capability, write the failing micro-test and implement the feature.
+
+---
+
+## 5. Architectural Fitness Functions (Automated Tripwires)
+
+Prevent AI-generated code rot using automated fitness functions integrated into linting and continuous verification:
+- **File Length Gates**: Maximum 250–300 lines per file (ESLint `max-lines`).
+- **Function Length Gates**: Maximum 20–30 lines per function (ESLint `max-lines-per-function`).
+- **Dependency Direction Gates**: Enforce unidirectional import rules (e.g. `import/no-restricted-paths`, `dependency-cruiser`, `ArchUnit`) ensuring domain core never imports infrastructure or transport adapters.
+- **Complexity Budgets**: Enforce cyclomatic complexity limits (maximum 10 per function).
+If an AI attempt to add code violates any fitness function, the build fails immediately, blocking completion until the architecture is refactored.

package/docs/rules/continuous_learning.md

@@ -1,29 +1,30 @@
 # Continuous Learning & Automated Rule Ingestion
 
-> **Core Mandate:** Automatically log development defects, post-mortems, and lessons learned into workspace memory, dynamically updating or generating atomic rules to permanently prevent recurrence.
+> **Core Mandate:** Automatically capture development defects, analyze root causes, and directly update domain rules or skills to permanently prevent recurrence without intermediate bloat.
 
 ---
 
-## 1. The Automated Rule Ingestion Loop
+## 1. The Direct Rule Ingestion Loop
 
-Whenever an error, test failure, build friction, or architectural anti-pattern occurs during development, immediately execute the 5-step loop:
+Whenever an error, test failure, build friction, or architectural anti-pattern occurs during development, immediately execute the 4-step loop:
 
 ```
-1. Capture Defect ──► 2. Root Cause Analysis ──► 3. Log Post-Mortem ──► 4. Synthesize Rule ──► 5. Update Rulebase
+1. Capture Defect ──► 2. Root Cause Analysis ──► 3. Synthesize Invariant ──► 4. Update Rule / Skill
 ```
 
-1. **Capture Defect**: Record the failure symptoms and stack trace.
+1. **Capture Defect**: Record the failure symptoms, stack trace, and failing test case.
 2. **Root Cause Analysis**: Identify the fundamental architectural or operational gap (not just the surface symptom).
-3. **Log Post-Mortem**: Append an entry to [`docs/knowledge/issue_log.md`](../knowledge/issue_log.md) documenting Symptom, Root Cause, Anti-Pattern, and Resolution.
-4. **Synthesize Rule**: Formulate the preventative DO and DONT directives and add them to [`docs/knowledge/dos_and_donts.md`](../knowledge/dos_and_donts.md).
-5. **Update Rulebase**:
-   - If the issue falls under an existing domain rule in `docs/rules/<domain>.md`, update that rule immediately.
-   - If it represents a new domain, author a new atomic rule file and index it in [`AGENTS.md`](../../AGENTS.md).
-   - Run the configuration validation script to ensure integrity.
+3. **Synthesize Invariant**: Formulate a concrete, positive architectural invariant and code example showing the correct implementation.
+4. **Update Rule / Skill**:
+   - Update the governing domain rule in `docs/rules/<domain>.md` or specialized skill in `.agents/skills/` directly.
+   - If the lesson introduces an architectural trade-off or paradigm shift, record a lightweight ADR in [`memory.md`](../../memory.md).
+   - If it unlocks a new domain, author a new atomic rule file and index it in [`AGENTS.md`](../../AGENTS.md).
+   - Run verification (`npm test && npm run validate`) to ensure 100% integrity.
 
 ---
 
 ## 2. Institutional Memory Maintenance
 
-- **ADR Synchronization**: Major technical decisions must be logged in [`memory.md`](../../memory.md) before or immediately upon implementation.
-- **Knowledge Graph Updates**: Keep [`docs/knowledge/knowledge_graph.md`](../knowledge/knowledge_graph.md) synchronized with new services, database models, or adapters to avoid repetitive token-expensive codebase discovery in future sessions.
+- **Lightweight ADR Ledger**: Major technical decisions and invariant shifts are logged in [`memory.md`](../../memory.md) linking directly to the governing rule or skill.
+- **System Knowledge Graph**: Keep [`docs/knowledge/knowledge_graph.md`](../knowledge/knowledge_graph.md) synchronized with new services, ports, or adapters to avoid repetitive token-expensive codebase discovery in future sessions.
+- **Living Glossary**: Keep [`docs/knowledge/ubiquitous_language.md`](../knowledge/ubiquitous_language.md) updated with canonical domain terminology and forbidden synonyms.

package/docs/rules/database_integrity.md

@@ -69,20 +69,12 @@ Pure financial ledgers (e.g. `PaymentLedgerEntry`, `JournalEntry`) and event out
 
 ---
 
-## 6. Invariants, DO's & DONT's
-
-### DO's:
-- **DO:** Include the canonical total audit fields (`createdAt`, `createdBy`, `updatedAt`, `updatedBy`, `deletedAt`, `deletedBy`) on every mutable entity model.
-- **DO:** Populate `createdBy`, `updatedBy`, and `deletedBy` from the verified session actor (`req.user.id`), falling back explicitly to `'SYSTEM'` only for background daemons or public bootstrap.
-- **DO:** Default foreign keys to `RESTRICT` for root aggregates and financial ledgers to prevent accidental cascading data loss.
-- **DO:** Enforce foreign key validation in use cases before persistence, returning RFC 7807 problem details if referenced records do not exist.
-- **DO:** Render foreign key associations using relational selectors (`shadcn/ui` `<Select>`) showing human-readable business metadata (names, labels, numbers, emails).
-- **DO:** Ensure every entity/feature implements full lifecycle CRUD (Create, Read/Detail, Update/Status Transition, Delete/Archive) before considering it complete.
-- **DO:** Filter active records with `WHERE deleted_at IS NULL` and pair uniqueness with partial indexes (`WHERE deleted_at IS NULL`).
-
-### DONT's:
-- **DONT:** Never create a database table or entity without `createdAt` and `createdBy`.
-- **DONT:** Never omit `updatedBy` or `deletedBy` on mutable tables. Every mutation and deletion must have an accountable actor.
-- **DONT:** Never expose raw string text inputs for foreign key identifiers in the user interface.
-- **DONT:** Never consider a feature complete if it only implements creation or listing without update, transition, or deletion capabilities.
-- **DONT:** Never allow cascading deletes on master entities with dependent transactional history.
+## 6. Semi-Structured Evolution & Cryptographic Audit Trails
+
+- **Non-Destructive Schema Evolution via JSON**: For contractual covenants, dynamic conditions, or variable metadata subject to rapid domain iteration, employ semi-structured JSON fields (`termsJson`, `metadataJson`) validated against JSON Schema rather than premature table migrations.
+- **Cryptographic Electronic Signatures & Execution Auditing**: Legal agreements and execution records require defensible evidence beyond a boolean `isSigned` flag. All executed agreements must capture:
+  1. Typed signer legal name and designated role.
+  2. ISO 8601 UTC execution timestamp.
+  3. Authenticated actor ID (`userId`).
+  4. Client network IP address and User-Agent string.
+  5. Deterministic cryptographic checksum / hash of the executed terms.

package/docs/rules/design_patterns.md

@@ -10,6 +10,7 @@
 - **Factory Method**: Encapsulate complex collaborator instantiation (e.g. tenant-specific payment gateways or notification dispatchers) behind factory functions.
 - **Facade Pattern**: Expose a unified, simplified interface to complex underlying multi-service subsystems.
 - **Decorator / Middleware**: Compose cross-cutting concerns (observability, authentication, tenant context resolution, rate limiting) via middleware pipelines.
+- **Dependency Injection & Composition Hygiene**: Application factories (`createApp(deps)`) must accept an explicit composite container (`AppDependencies`). Never provide silent default fallback instances inside factories that instantiate disconnected repositories or services when partial dependencies are passed (the Split-Brain Anti-Pattern). Assemble the full dependency graph explicitly at the composition root.
 
 ---
 

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.