azcodr 1.1.0 → 1.2.0

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.

package/memory.md

@@ -1,262 +1,128 @@
 # Workspace Memory, Architecture Decisions & Knowledge Hub
 
-> **Core Purpose:** Authoritative persistent memory ledger for the workspace repository (`./`), maintaining Lightweight Architectural Decision Records (ADRs), system topologies, issue logs, and institutional lessons.
+> **Core Purpose:** Authoritative persistent memory ledger for the workspace repository (`./`), maintaining Lightweight Architectural Decision Records (ADRs), system topologies, and living domain contracts.
 
 ---
 
 ## 1. Quick Navigation & Knowledge Repositories
 
 - 🗺️ **[System Knowledge Graph](./docs/knowledge/knowledge_graph.md)**: Architectural subsystems, Mermaid topologies, entity relationships, and fast-lookup matrices.
-- 📋 **[Consolidated DO's & DONT's](./docs/knowledge/dos_and_donts.md)**: High-impact rules, anti-patterns to avoid, and coding invariants.
-- 🐛 **[Coding Issue Log](./docs/knowledge/issue_log.md)**: Defect post-mortems, root causes, and synthesized preventing rules.
-- 💡 **[Institutional Lessons Learned](./docs/knowledge/lessons_learned.md)**: Strategic engineering takeaways and optimization insights.
+- 📖 **[Living Ubiquitous Language Glossary](./docs/knowledge/ubiquitous_language.md)**: Authoritative, single-name domain vocabulary contract.
+- 📜 **[Lightweight ADR Master Index](#adr-master-index)**: Summary of all architectural decisions and direct links to governing rules.
+- 📝 **[Upstream Changes Ledger](./changes.md)**: Ledger of candidate improvements and generic patterns for upstream azcodr.
 
 ---
 
-## 2. Architectural Decision Records (ADRs)
+## 2. Consolidated Architectural Decision Records (ADRs)
+
+### ADR Master Index
+
+| ID | Title | Date | Status | Governing Rule / Skill |
+|---|---|---|---|---|
+| **ADR-001** | 100% Open-Source Tooling & Framework Mandate | 2026-09-16 | ACCEPTED | [`compliance.md`](./docs/rules/compliance.md), [`devsecops.md`](./docs/rules/devsecops.md) |
+| **ADR-002** | Progressive Disclosure Architecture for Agentic Context | 2026-09-16 | ACCEPTED | [`agentic_configuration.md`](./docs/rules/agentic_configuration.md), [`agentic-architect`](./.agents/skills/agentic-architect/SKILL.md) |
+| **ADR-003** | Dual-Layer Multi-Tenancy Isolation with PostgreSQL RLS | 2026-09-16 | ACCEPTED | [`multitenancy_isolation.md`](./docs/rules/multitenancy_isolation.md) |
+| **ADR-004** | Systemic Atomicity & Pure Single-Responsibility Rule Decomposition | 2026-09-16 | ACCEPTED | [`agentic_configuration.md`](./docs/rules/agentic_configuration.md) |
+| **ADR-005** | Universal Technology, Language, and Stack Agnosticism | 2026-09-18 | ACCEPTED | [`clean_code.md`](./docs/rules/clean_code.md), [`lets-build`](./.agents/skills/lets-build/SKILL.md) |
+| **ADR-006** | Mandatory Full Lifecycle CRUD & Relational FK Selector Pattern | 2026-09-18 | ACCEPTED | [`database_integrity.md`](./docs/rules/database_integrity.md), [`rest_api_conventions.md`](./docs/rules/rest_api_conventions.md), [`ui_ux_architecture.md`](./docs/rules/ui_ux_architecture.md) |
+| **ADR-007** | Decoupling Project Bootstrapping from Domain Analysis | 2026-09-18 | ACCEPTED | [`lets-build`](./.agents/skills/lets-build/SKILL.md), [`product-analyst`](./.agents/skills/product-analyst/SKILL.md) |
+| **ADR-008** | Non-Negotiable 5-Phase Agile Domain Lifecycle & Outside-In TDD | 2026-09-18 | ACCEPTED | [`test_driven_development.md`](./docs/rules/test_driven_development.md), [`test_isolation.md`](./docs/rules/test_isolation.md) |
+| **ADR-009** | Many-to-Many Skill Composability & Orthogonal Pipelines | 2026-09-18 | ACCEPTED | [`agentic_configuration.md`](./docs/rules/agentic_configuration.md), [`agentic-architect`](./.agents/skills/agentic-architect/SKILL.md) |
+| **ADR-011** | Canonical 6 Total Audit Fields Architecture & Modern React Stack | 2026-09-19 | ACCEPTED | [`database_integrity.md`](./docs/rules/database_integrity.md), [`react.md`](./docs/rules/react.md) |
+| **ADR-012** | State Machine Lifecycle Configurability & Ubiquitous Language Contract | 2026-09-19 | ACCEPTED | [`workflow_state_machines.md`](./docs/rules/workflow_state_machines.md), [`domain_driven_design.md`](./docs/rules/domain_driven_design.md) |
+| **ADR-013** | Design Architecture Triage, Persistent Shell & Dev Persona Isolation | 2026-09-20 | ACCEPTED | [`ui_ux_architecture.md`](./docs/rules/ui_ux_architecture.md), [`authentication.md`](./docs/rules/authentication.md) |
+| **ADR-014** | Product Ownership, Prioritization Models, SMART Tasks & INVEST Slicing | 2026-09-21 | ACCEPTED | [`product_ownership.md`](./docs/rules/product_ownership.md), [`requirements_engineering.md`](./docs/rules/requirements_engineering.md), [`project_management.md`](./docs/rules/project_management.md) |
+| **ADR-015** | Problem-First Architecture, Topology Scaffolding, Tipping Points & Nano-TDD | 2026-09-25 | ACCEPTED | [`clean_code.md`](./docs/rules/clean_code.md), [`domain_driven_design.md`](./docs/rules/domain_driven_design.md), [`test_driven_development.md`](./docs/rules/test_driven_development.md), [`lets-build`](./.agents/skills/lets-build/SKILL.md) |
 
-### ADR-001: 100% Open-Source Tooling & Framework Mandate
+---
+
+### Lightweight Decision Summaries
+
+#### ADR-001: 100% Open-Source Tooling & Framework Mandate
 - **Date:** 2026-09-16 | **Status:** ACCEPTED
 - **Context:** Proprietary SaaS dependencies introduce vendor lock-in, recurring operational costs, and black-box security risks.
-- **Decision:** Standardize exclusively on open-source solutions across all domains (PostgreSQL, Redis, Trivy, Semgrep, Gitleaks, OpenTelemetry, Vitest, Playwright, Radix UI).
-- **Consequences:** Maximizes infrastructure control, auditable security compliance, and zero license encumbrances.
+- **Decision:** Standardize exclusively on open-source solutions across all architectural domains (PostgreSQL, Redis, Trivy, Semgrep, Gitleaks, OpenTelemetry, Vitest, Playwright, Radix UI).
+- **Enforced In:** Root [`AGENTS.md`](./AGENTS.md), [`compliance.md`](./docs/rules/compliance.md), [`devsecops.md`](./docs/rules/devsecops.md).
 
-### ADR-002: Progressive Disclosure Architecture for Agentic Context
+#### ADR-002: Progressive Disclosure Architecture for Agentic Context
 - **Date:** 2026-09-16 | **Status:** ACCEPTED
-- **Context:** Injecting large monolithic documentation files on every AI prompt exhausts token windows and degrades attention and reasoning.
-- **Decision:** Keep root `AGENTS.md` lean (≤ 120 lines), decoupling specialized engineering manuals into modular files under `docs/rules/`.
-- **Consequences:** Eliminates prompt token bloat while ensuring deep domain guidance is loaded strictly on demand.
+- **Context:** Injecting large monolithic documentation files on every AI prompt exhausts token windows and degrades model attention.
+- **Decision:** Keep root `AGENTS.md` lean (≤ 120 lines), decoupling specialized engineering manuals into modular files under `docs/rules/` and skills under `.agents/skills/`.
+- **Enforced In:** Root [`AGENTS.md`](./AGENTS.md), [`agentic_configuration.md`](./docs/rules/agentic_configuration.md), [`agentic-architect`](./.agents/skills/agentic-architect/SKILL.md).
 
-### ADR-003: Dual-Layer Multi-Tenancy Isolation with PostgreSQL RLS
+#### ADR-003: Dual-Layer Multi-Tenancy Isolation with PostgreSQL RLS
 - **Date:** 2026-09-16 | **Status:** ACCEPTED
 - **Context:** Application-level `where: { tenantId }` filtering is prone to human error, risking catastrophic cross-tenant data leaks.
 - **Decision:** Combine application middleware context resolution with database-level PostgreSQL Row-Level Security (RLS) policies as an immutable backstop.
-- **Consequences:** Physical isolation at the database layer; prevents cross-tenant data access even if application code forgets a filter.
+- **Enforced In:** [`multitenancy_isolation.md`](./docs/rules/multitenancy_isolation.md).
 
-### ADR-004: Systemic Atomicity & Pure Single-Responsibility Rule Decomposition
+#### ADR-004: Systemic Atomicity & Pure Single-Responsibility Rule Decomposition
 - **Date:** 2026-09-16 | **Status:** ACCEPTED
 - **Context:** Composite rules with conjunction names (`this_and_that.md`) mix disparate technical concerns, creating documentation bloat and ambiguity.
 - **Decision:** Decompose all rules into strictly atomic, single-topic rule files with zero conjunction names, enforcing Single Responsibility Principle across skills, rules, and database operations.
-- **Consequences:** 37 highly modular, composable, and maintainable domain rules with zero cross-leakage.
+- **Enforced In:** Root [`AGENTS.md`](./AGENTS.md), [`agentic_configuration.md`](./docs/rules/agentic_configuration.md).
 
-### ADR-005: Universal Technology, Language, and Stack Agnosticism
+#### ADR-005: Universal Technology, Language, and Stack Agnosticism
 - **Date:** 2026-09-18 | **Status:** ACCEPTED
-- **Context:** Tightly coupling architecture rules and specifications to a single programming language (TypeScript), runtime (Node.js), ORM (Prisma), or database engine (PostgreSQL) creates technical lock-in and prevents polyglot implementation.
-- **Decision:** Adopt a Two-Tier Hexagonal / Ports-and-Adapters model across the entire system. Tier 1 mandates 100% technology-, language-, and stack-agnostic invariant domain capabilities and open standard specifications (Protocol Buffers v3, OpenAPI 3.1, JSON Schema Draft 2020-12, AsyncAPI, CloudEvents, W3C DTCG Design Tokens, CEL, Wasm/WASI, OPA/OpenFGA) with zero language bias or primary reference designation. Tier 2 encapsulates interchangeable polyglot adapters (Go, Rust, Python, Java, TypeScript, etc.).
-- **Consequences:** Eliminates language and framework lock-in, enables polyglot microservice implementation, future-proofs the enterprise architecture, and enforces pure boundary decoupling.
+- **Context:** Coupling architecture rules to a single programming language or database creates technical lock-in and prevents polyglot implementation.
+- **Decision:** Adopt a Two-Tier Hexagonal / Ports-and-Adapters model across the entire system: Tier 1 mandates 100% technology-, language-, and stack-agnostic invariant domain capabilities and open standard specifications; Tier 2 encapsulates interchangeable polyglot adapters.
+- **Enforced In:** Root [`AGENTS.md`](./AGENTS.md), [`clean_code.md`](./docs/rules/clean_code.md), [`lets-build`](./.agents/skills/lets-build/SKILL.md).
 
-### ADR-006: Mandatory Full Lifecycle CRUD and Relational Foreign Key Selector Pattern
+#### ADR-006: Mandatory Full Lifecycle CRUD & Relational Foreign Key Selector Pattern
 - **Date:** 2026-09-18 | **Status:** ACCEPTED
+- **Context:** Prototypes often provide partial CRUD, leaving entities un-editable or undeletable. Exposing foreign keys as raw text inputs causes severe relational errors.
+- **Decision:** Every feature must implement complete lifecycle CRUD (Create, Read/Detail, Update/Transition, Delete/Archive) with 100.00% test coverage. Foreign keys must never be exposed as raw string inputs; they must be resolved via accessible relational dropdown selectors displaying contextual business metadata.
+- **Enforced In:** [`database_integrity.md`](./docs/rules/database_integrity.md), [`rest_api_conventions.md`](./docs/rules/rest_api_conventions.md), [`ui_ux_architecture.md`](./docs/rules/ui_ux_architecture.md).
 
-#### 1. Context & Problem Statement
-Prototypes often provide only partial read and create actions, leaving entities unable to be edited, status-transitioned, or archived/deleted. Furthermore, foreign key associations (such as `parentEntityId`, `resourceId`) are frequently exposed as raw text inputs where users must manually know and type string/UUID identifiers. This creates significant relational failure rates (400 Bad Request, foreign key violations) and breaks standard user experience.
-
-#### 2. Decision Drivers
-- Every feature must support its complete lifecycle CRUD (Create, Read/Detail, Update/Transition, Delete/Archive) before being considered feature-complete.
-- Foreign keys must never be exposed as raw text fields in the UI. Relational references must be resolved and selected via structured UI primitives (e.g. `<Select>`) displaying human-readable contextual metadata (e.g. names, titles, codes, labels, and status).
-- Domain and use case layers must strictly validate foreign key existence before persisting child entities, returning RFC 7807 problem details if referenced records do not exist.
-
-#### 3. Decision Outcome & Consequences
-- **Chosen Pattern:** 
-  1. Primary and secondary ports support comprehensive CRUD operations (`update`, `delete`, catalog queries).
-  2. Use cases enforce foreign key invariants with parent record existence checks prior to child entity mutation.
-  3. Presentation layer replaces all raw identifier text inputs with accessible relational dropdown selectors backed by dynamic API queries.
-  4. Test suites maintain 100.00% test coverage gate across all CRUD methods, branches, and error paths.
-- **Positive Consequences:**
-  - Complete elimination of relational integrity errors caused by typos or non-existent IDs.
-  - Richer user experience displaying contextual business metadata during association.
-  - Strict compliance with workspace definitions of done and 100.00% coverage gates.
-
-### ADR-007: Strict Decoupling of Project Bootstrapping from Domain Analysis and Feature Engineering
+#### ADR-007: Strict Decoupling of Project Bootstrapping from Domain Analysis
 - **Date:** 2026-09-18 | **Status:** ACCEPTED
+- **Context:** Agents running `/lets-build` frequently fabricate domain entities on sheer assumptions during technical bootstrapping, skipping requirements discovery.
+- **Decision:** Project bootstrapping terminates strictly after technical skeleton creation and health probe verification (`Phase 5`). A mandatory Handover Gate halts coding and directs the agent to initiate Domain Analysis via `product-analyst` and `relentless-questioner` before domain models or schemas are authored.
+- **Enforced In:** [`lets-build`](./.agents/skills/lets-build/SKILL.md), [`product-analyst`](./.agents/skills/product-analyst/SKILL.md), [`requirements_engineering.md`](./docs/rules/requirements_engineering.md), [`domain_driven_design.md`](./docs/rules/domain_driven_design.md).
 
-#### 1. Context & Problem Statement
-During initial project execution with `/lets-build`, technical infrastructure bootstrapping (stack selection, monorepo setup, package manifests, build toolchains) is frequently conflated with application domain modeling. Agents tend to fabricate business entities without engaging the user in thorough domain discovery, Ubiquitous Language alignment, Bounded Context mapping, or INVEST user story decomposition. This violates Rule Zero ("Assume nothing") and skips the foundational requirements engineering lifecycle.
-
-#### 2. Decision Drivers
-- Project bootstrapping must be strictly scoped to technical plumbing (workspace configuration, package manifests, ports/adapters skeletons, build commands, Docker/Compose, and a minimal `/healthz` probe).
-- Domain modeling and feature engineering must never be assumed or generated by an agent during bootstrapping.
-- Domain features must emerge exclusively through structured stakeholder interviews using `product-analyst`, `relentless-questioner`, `docs/rules/domain_driven_design.md`, and `docs/rules/requirements_engineering.md`.
-
-#### 3. Decision Outcome & Consequences
-- **Chosen Pattern:** 
-  1. `/lets-build` strictly terminates after technical skeleton creation and health probe verification (`Phase 5`).
-  2. A mandatory Handover Gate halts further coding and directs the agent to initiate Domain Analysis.
-  3. Domain models, database schemas, and API resources are authored iteratively only after user stories and Gherkin criteria are approved.
-- **Positive Consequences:**
-  - Prevents premature code generation and hallucinated domain structures.
-  - Aligns software design with real stakeholder requirements rather than AI guesses.
-  - Ensures proper Outside-In Double-Loop TDD execution.
-
-### ADR-008: Non-Negotiable 5-Phase Agile Domain Lifecycle & Outside-In TDD Invariant
+#### ADR-008: Non-Negotiable 5-Phase Agile Domain Lifecycle & Outside-In TDD Invariant
 - **Date:** 2026-09-18 | **Status:** ACCEPTED
+- **Context:** Writing production code before tests or domain understanding leads to brittle code, regressions, and "toy prototypes."
+- **Decision:** Enforce an immutable 5-Phase Agile Domain Lifecycle across all tasks (Requirements ➔ Domain Analysis ➔ Outer Acceptance RED ➔ Inner Unit TDD RED-GREEN-REFACTOR ➔ Outer GREEN & DoD). Writing production code without a failing test is strictly prohibited.
+- **Enforced In:** Root [`AGENTS.md`](./AGENTS.md), [`test_driven_development.md`](./docs/rules/test_driven_development.md), [`test_isolation.md`](./docs/rules/test_isolation.md).
 
-#### 1. Context & Problem Statement
-Engineering practices frequently suffer from shortcutting: writing production code before writing tests, writing tests before understanding domain models, and designing domain models without engaging stakeholders. This leads to brittle software, high defect rates, mismatched requirements, and the "toy prototype blunder" where foreign key relationships, validation rules, and proxy transports are improperly implemented.
-
-#### 2. Decision Drivers
-- Need for a mathematically rigorous, repeatable, and non-negotiable software engineering process.
-- Guarantee that all production code is justified by an existing, failing automated test (Red-Green-Refactor).
-- Guarantee that tests assert real business invariants derived from rigorous domain analysis rather than arbitrary syntax.
-- Guarantee that requirements are decomposed into vertically sliced, testable INVEST user stories and Gherkin scenarios.
-
-#### 3. Decision Outcome & Consequences
-- **Chosen Pattern:** Enforce an immutable 5-Phase Agile Domain Lifecycle across all tasks:
-  1. **Phase 1: Requirements Engineering** (INVEST user stories + executable Gherkin Given/When/Then scenarios + Negative Scope).
-  2. **Phase 2: Tactical Domain Analysis** (Ubiquitous Language definitions + Bounded Contexts + Aggregate Roots with invariants + State Machines).
-  3. **Phase 3: Outer-Loop Acceptance Test (RED)** (Failing UI component interaction test via Playwright/React Testing Library, or black-box HTTP route contract test).
-  4. **Phase 4: Inner-Loop TDD & Collaborator Discovery (RED-GREEN-REFACTOR)** (Collaborators discovered by outer loop unit-tested in isolation, minimal code written to pass, strict refactoring under green).
-  5. **Phase 5: Outer Acceptance Resolution & Definition of Done** (Outer test turns GREEN, cross-package boundary smoke tests pass, 100.00% coverage verified).
-- **Zero-Deviation Mandate:**
-  - Writing production code without a failing test is strictly prohibited.
-  - Generating domain entities without stakeholder requirements analysis is strictly prohibited.
-  - Committing code without 100.00% full-stack test coverage and boundary verification is strictly prohibited.
-- **Positive Consequences:**
-  - Eliminates regression bugs and defect escapes to production.
-  - Ensures clean, maintainable architecture with small functions (< 30 lines) adhering to SLAP, CQS, and DRY.
-  - Guarantees complete alignment between user intent, domain models, tests, and deployed code.
-
-### ADR-009: Many-to-Many Skill Composability & Orthogonal Pipeline Architecture
+#### ADR-009: Many-to-Many Skill Composability & Orthogonal Pipeline Architecture
 - **Date:** 2026-09-18 | **Status:** ACCEPTED
+- **Context:** Complex engineering tasks require multiple orthogonal skills; coupling skills into monolithic bundles causes context bloat and cross-contamination.
+- **Decision:** Codify Many-to-Many skill composability via three formal patterns: Sequential Pipeline Chaining, Dynamic Skill Stacking, and Multi-Agent Subagent Delegation, with standardized output contracts, pure function semantics, and zero cross-contamination.
+- **Enforced In:** [`agentic_configuration.md`](./docs/rules/agentic_configuration.md), [`agentic-architect`](./.agents/skills/agentic-architect/SKILL.md).
 
-#### 1. Context & Problem Statement
-In agentic software engineering, a naive assumption is that a single skill corresponds 1:1 to a single task or development phase. In reality, software development exhibits an explicit Many-to-Many ($M:N$) relationship between coding tasks and agentic capabilities:
-1. A single coding task simultaneously requires multiple specialized skills: domain requirement decomposition, invariant modeling, security compliance auditing, and clean code refactoring.
-2. A single skill (e.g. `clean-code-refactor` or `relentless-questioner`) is orthogonal to any specific domain and must be reused across widely diverse scenarios (database transactions, HTTP middleware, UI components, and background queues).
-If skills are designed as monolithic, coupled bundles, agent contexts suffer prompt bloat, cognitive dilution, and cross-contamination.
-
-#### 2. Decision Drivers
-- Need for high reusability and atomic modularity across agent skills without prompt token bloat.
-- Need for predictable, deterministic execution when multiple skills are required for a single complex engineering task.
-- Need for clean input/output contracts so skills can be piped or composed sequentially, contextually, or across subagents without side effects.
-- Strict adherence to Rule Zero ("Assume nothing"), Systemic Atomicity, and the Single Responsibility Principle.
-
-#### 3. Decision Outcome & Consequences
-- **Chosen Pattern:** Codify and enforce the Many-to-Many Skill Composability Architecture across three formal composition patterns:
-  1. **Pattern 1: Sequential Pipeline Chaining (Workflow Composition):** Upstream skills produce structured, standardized artifacts (FAS, INVEST stories, Gherkin blocks, OpenAPI contracts) serving as the direct input contract for downstream skills.
-  2. **Pattern 2: Dynamic Skill Stacking (Contextual Composition):** An agent dynamically loads multiple orthogonal skills into its working memory based on task needs, adhering to Progressive Disclosure without polluting base prompts.
-  3. **Pattern 3: Multi-Agent Subagent Delegation (Division of Labor):** A coordinator agent spawns specialized subagents equipped with specific atomic skills, synthesizing findings into a single coordinated action.
-- **Architectural Invariants for Valid Skill Composition:**
-  - **Standardized Output Contracts:** Every skill emits standardized, machine- and human-readable artifacts.
-  - **Zero Cross-Contamination:** A skill must never write or mutate code outside its declared functional boundary.
-  - **Pure Function Semantics:** Analytical, audit, and questioning skills must remain read-only and side-effect free.
-- **Positive Consequences:**
-  - Skills remain strictly atomic, modular, and reusable across unlimited domains and stacks.
-  - Eliminates prompt bloat by loading only the exact skills needed for the current lifecycle step.
-  - Supports complex end-to-end workflows through deterministic artifact piping.
-
-### ADR-011: The Canonical 6 Total Audit Fields Architecture & Modern React Stack
+#### ADR-011: The Canonical 6 Total Audit Fields Architecture & Modern React Stack
 - **Date:** 2026-09-19 | **Status:** ACCEPTED
+- **Context:** Inconsistent audit tracking risks SOC 2 / ISO 27001 non-compliance. Frontend `useEffect` fetch loops cause stale states and race conditions.
+- **Decision:** Every mutable stateful table must implement the Canonical 6 Total Audit Fields (`createdAt`, `createdBy`, `updatedAt`, `updatedBy`, `deletedAt`, `deletedBy`), with append-only ledgers omitting update/delete fields. Standardize frontend on TanStack Query, React Hook Form + Zod, and headless Radix primitives.
+- **Enforced In:** [`database_integrity.md`](./docs/rules/database_integrity.md), [`react.md`](./docs/rules/react.md).
 
-#### 1. Context & Problem Statement
-Stateful entities across databases and domain models frequently suffer from inconsistent audit accountability—omitting actor attribution (`createdBy`, `updatedBy`) or destructive deletion tracking (`deletedAt`, `deletedBy`). Furthermore, frontend state management often defaults to ad-hoc `useEffect` fetch loops and unvalidated forms without structured caching, automated mutation invalidation, or sound schema contracts.
-
-#### 2. Decision Drivers
-- Universal Total Audit Accountability: Every stateful database table, ORM entity, and domain aggregate must implement **The Canonical 6 Total Audit Fields**: `createdAt`, `createdBy`, `updatedAt`, `updatedBy`, `deletedAt`, and `deletedBy`.
-- Strictly Immutable Ledger Invariant: Append-only financial ledgers and event outboxes must enforce strict immutability, prohibiting `updatedAt`, `updatedBy`, `deletedAt`, and `deletedBy`.
-- Non-Destructive Soft-Delete: All delete operations must mark `deletedAt` and `deletedBy` with actor attribution, and queries for active records must strictly filter `WHERE deletedAt IS NULL`.
-- Modern React Architecture: Standardize on `@tanstack/react-query` for asynchronous server state, caching, and optimistic mutations; standardize on `react-hook-form` / `tanstack-form` + `zod` for type-safe form contracts; mandate accessible headless primitives (`shadcn/ui` + `@radix-ui`) with zero native alerts.
-
-#### 3. Decision Outcome & Consequences
-- Codified Section 5 & 6 in [`docs/rules/database_integrity.md`](./docs/rules/database_integrity.md) mandating the Canonical 6 Total Audit Fields and append-only ledger invariants.
-- Authored [`docs/rules/react.md`](./docs/rules/react.md) codifying TanStack Query, React Hook Form + Zod, TanStack Table, and accessible `<ConfirmDialog>` primitives.
-- Upgraded `lets-build` architecture interview matrix (Dimensions 6 & 13) to interrogate audit fields and form state management during scaffolding.
-- **Positive Consequences:**
-  - Complete compliance with SOC 2 / ISO 27001 auditability controls.
-  - Permanent prevention of accidental data loss via soft deletion.
-  - Predictable, type-safe frontend state management with zero stale cache bugs.
-
-### ADR-012: State Machine Lifecycle Configurability & Living Ubiquitous Language Contract
+#### ADR-012: State Machine Lifecycle Configurability & Living Ubiquitous Language Contract
 - **Date:** 2026-09-19 | **Status:** ACCEPTED
+- **Context:** Unconstrained state configurability causes the "Inner Platform Effect." Linguistic drift between business terms and code identifiers breaks domain models.
+- **Decision:** Bifurcate state into Core Invariant States (Hard FSM in compiled aggregate roots) and Operational Workflow Stages (Soft FSM in declarative JSON state transition matrices evaluated via CEL/Temporal). Maintain a living, single-name Ubiquitous Language Glossary contract.
+- **Enforced In:** [`workflow_state_machines.md`](./docs/rules/workflow_state_machines.md), [`domain_driven_design.md`](./docs/rules/domain_driven_design.md), [`ubiquitous_language.md`](./docs/knowledge/ubiquitous_language.md).
 
-#### 1. Context & Problem Statement
-Two recurring systemic questions arise during enterprise architecture evolution:
-1. *State Configurability Paradox:* Should all status fields and business logic be user/tenant-configurable? Unconstrained configurability leads to the "Inner Platform Effect" anti-pattern, where core domain invariants collapse.
-2. *Linguistic Drift & Agreement:* How can domain-code language agreement be maintained deterministically across product requirements, code, tests, and database tables without vocabulary divergence?
-
-#### 2. Decision Drivers
-- Invariant Integrity: Core business invariants (e.g. accounting balance, executed orders) must be non-negotiable and protected inside compiled Aggregate Roots.
-- Operational Customization: Multi-tenant platforms require configurable review stages, approval funnels, and sub-statuses.
-- Guaranteed Linguistic Alignment: Establish a binding, living contract between business vocabulary and source code identifiers, backed by AST linter rules and branded nominal types.
-
-#### 3. Decision Outcome & Consequences
-- **The Dual-State Architecture ([`docs/rules/workflow_state_machines.md`](./docs/rules/workflow_state_machines.md)):**
-  - Bifurcated state into:
-    1. *Core Invariant States (Hard FSM)*: Enforced strictly inside compiled Aggregate Roots using Discriminated Unions or the GoF State Pattern.
-    2. *Operational Workflow Stages (Soft FSM)*: Managed via Declarative State Transition Matrices stored in JSON/metadata, evaluated via Common Expression Language (CEL) or durable workflow engines (Temporal / BPMN 2.0).
-  - Enforced a mandatory append-only State Transition Log (`transitionId`, `entityType`, `entityId`, `fromState`, `toState`, `actorId`, `event`, `timestamp`).
-- **Domain-Code Language Agreement ([`docs/rules/domain_driven_design.md`](./docs/rules/domain_driven_design.md) & [`docs/knowledge/ubiquitous_language.md`](./docs/knowledge/ubiquitous_language.md)):**
-  - Codified the "Single Name Rule" and zero-tolerance for synonyms.
-  - Established the living glossary template and AST linter denylist patterns.
-- **Upgraded Skills & References:**
-  - Enhanced `product-analyst` and `lets-build` (Dimensions 19 & 20) to interrogate state taxonomy and verify glossary alignment.
-- **Positive Consequences:**
-  - Complete architectural clarity: aggregate invariants remain inviolate while operational workflows gain full tenant configurability.
-  - Elimination of linguistic drift across domain models, APIs, and UI layers.
-
-### ADR-013: Formal Design Architecture Triage Framework, Persistent Navigation Shell, Dual-Experience Portals, and Strict Isolation of Development Personas from Production Authentication
+#### ADR-013: Design Architecture Triage Framework, Persistent Shell & Dev Persona Isolation
 - **Date:** 2026-09-20 | **Status:** ACCEPTED
+- **Context:** Conflating developer demo personas with production auth creates toy-like prototypes. Untriaged UI produces layout shifts and broken navigation.
+- **Decision:** Mandate the 7-Pillar Design Architecture Triage Gate before writing UI code; separate Enterprise Operator Workspace (`/`) from Consumer Portal (`/portal`); standardize on a persistent shell with 64px collapsible icon rail and bidirectional URL state sync; strictly isolate developer demo personas into a dev-only floating toolbar (`import.meta.env.DEV`).
+- **Enforced In:** [`ui_ux_architecture.md`](./docs/rules/ui_ux_architecture.md), [`authentication.md`](./docs/rules/authentication.md), [`ui_navigation.md`](./docs/rules/ui_navigation.md).
 
-#### 1. Context & Problem Statement
-UI development without upfront design architecture triage creates severe user experience and security failure modes:
-1. Conflating developer demo/mock personas with end-user sign-in flows, producing a toy-like prototype that confuses real users.
-2. Mixing operator-dense navigation with consumer self-service workflows into a single chaotic layout.
-3. Lack of a persistent application shell and collapsible sidebar, causing disruptive layout shifts and broken navigation state on page transitions.
-4. Missing deep-linkable URL synchronization for active tabs, search queries, and drawers.
-
-#### 2. Decision Drivers
-- Need for a mandatory upfront design gate before writing UI code.
-- Strict physical separation between developer test harnesses and production authentication.
-- Strict architectural duality between enterprise operator workspaces and consumer/member portals.
-- Persistent app shell with collapsible 64px icon rail mode, persistent state in `localStorage`, and bidirectional URL search parameter synchronization.
-
-#### 3. Decision Outcome & Consequences
-- **The 7-Pillar Design Architecture Triage Gate ([`docs/rules/ui_ux_architecture.md`](./docs/rules/ui_ux_architecture.md)):**
-  - Mandated 7 triage pillars (Role Triage, Information Architecture, Duality, Wayfinding, URL Sync, Route Guards, Accessibility) before building UI increments.
-- **Strict Decoupling of Developer Personas ([`docs/rules/authentication.md`](./docs/rules/authentication.md)):**
-  - Developer demo personas are completely isolated into a dev-only floating toolbar (`import.meta.env.DEV`), completely excluded from production bundles.
-  - Production sign-in enforces clean, dedicated forms with Zod schema validation and role-based post-login redirection.
-- **Dual-Experience Model & Persistent Shell:**
-  - Separated Enterprise Operator Workspace (`/`) from Consumer / Member Self-Service Portal (`/portal`).
-  - Standardized persistent header, contextual breadcrumbs, collapsible sidebar with 64px icon rail, and URL search param state sync.
-- **Positive Consequences:**
-  - Eliminates toy-like demo persona leaks in production.
-  - Clean separation between dense administrative workflows and consumer self-service.
-  - Fully accessible, deep-linkable web applications conforming to WCAG 2.2 AA.
-
-### ADR-014: Product Ownership, Backlog Prioritization Models, SMART Developer Tasks, and INVEST Slicing
+#### ADR-014: Product Ownership, Backlog Prioritization Models, SMART Developer Tasks & INVEST Slicing
 - **Date:** 2026-09-21 | **Status:** ACCEPTED
-
-#### 1. Context & Problem Statement
-Agile teams frequently suffer from the "Feature Factory" anti-pattern: measuring output (story points burned, code volume) instead of outcome (customer value realized, satisfaction gap closed). Additional failure modes include:
-1. Conflating user stories with formal requirements rather than treating them as conversational placeholders (the 3 C's) and pidgin language bridges.
-2. Forcing system invariants, security controls, and architectural spikes into artificial `"As a user..."` syntax.
-3. Slicing stories horizontally (e.g. database migration only or UI mock only) delivering zero usable software to customers.
-4. Open-ended developer tasks lacking measurable pass/fail boundaries, leading to multi-day task drift.
-5. Arbitrary backlog prioritization driven by executive gut feeling rather than quantitative value models.
-
-#### 2. Decision Drivers
-- Ground product development in empiricism (Build-Measure-Learn) and clear Product Goals.
-- Connect strategic Objectives and Key Results (OKRs) to backlog ordering.
-- Standardize objective prioritization frameworks (Kano Model, MoSCoW, RICE, Buy a Feature).
-- Mandate Bill Wake's INVEST criteria and vertical cake slicing (UI ➔ API ➔ Domain ➔ DB).
-- Standardize Bill Wake's SMART framework for decomposing user stories into bounded developer tasks (2–4 hours).
-
-#### 3. Decision Outcome & Consequences
-- **Dedicated Rule & Skill ([`docs/rules/product_ownership.md`](./docs/rules/product_ownership.md), [`.agents/skills/product-analyst/`](./.agents/skills/product-analyst/)):**
-  - Codified Product Owner accountabilities, the satisfaction gap, and outcome vs. output discipline.
-  - Added reference guides for Kano, MoSCoW, RICE scoring, and OKR alignment.
-- **Requirements Engineering & Vertical Cake Slicing ([`docs/rules/requirements_engineering.md`](./docs/rules/requirements_engineering.md)):**
-  - Clarified that user stories are tokens for conversation (Ron Jeffries' 3 C's: Card, Conversation, Confirmation).
-  - Explicitly decoupled non-story requirements (system invariants, NFRs, architectural spikes) from story syntax.
-  - Enforced multi-layer cake vertical slicing across all layers.
-- **SMART Developer Task Breakdown ([`docs/rules/project_management.md`](./docs/rules/project_management.md)):**
-  - Required decomposing INVEST stories into Specific, Measurable, Achievable, Relevant, and Time-boxed (2–4h) developer tasks.
-- **Positive Consequences:**
-  - Guarantees working software in every vertical increment.
-  - Eliminates horizontal stubs and open-ended technical drift.
-  - Objective backlog ranking minimizes stakeholder friction.
-
-
-
+- **Context:** Teams frequently measure output (lines of code, story points) rather than outcome (customer value), leading to the "Feature Factory" anti-pattern.
+- **Decision:** Ground backlog ordering in quantitative prioritization (Kano, MoSCoW, RICE) aligned with OKRs; decompose epics into vertically sliced INVEST user stories; decompose user stories into bounded SMART developer tasks (2–4 hours).
+- **Enforced In:** [`product_ownership.md`](./docs/rules/product_ownership.md), [`requirements_engineering.md`](./docs/rules/requirements_engineering.md), [`project_management.md`](./docs/rules/project_management.md), [`product-analyst`](./.agents/skills/product-analyst/SKILL.md).
+
+#### ADR-015: Problem-First Architecture, Topology Scaffolding, Evolutionary Tipping Points & Incremental Nano-Cycle TDD
+- **Date:** 2026-09-25 | **Status:** ACCEPTED
+- **Context:** Tool-first planning (asking for languages, databases, and microservices upfront) creates accidental complexity and forces non-backend projects (such as Chrome extensions, game engines, or CLIs) into heavy enterprise templates (as observed in `force-dark-light`). Furthermore, AI assistants naturally accelerate architectural drift by appending code without structural evolution, and fake TDD by batch-generating 15 tests and implementations at once.
+- **Decision:**
+  1. Enforce **Problem-First Architecture**: Strictly separate Problem Space from Solution Space (Evans, Vernon, Brooks). Derive tools and runtimes from problem constraints (latency budget, GC tolerance, memory, execution target).
+  2. Implement **Topology-Aware Scaffolding**: Eliminate universal templates. Match architectural styles to system topologies (Platform Scripting for extensions, Data-Oriented Design for game engines, Command Pipeline for CLIs, Hexagonal for enterprise backends).
+  3. Codify **Evolutionary Architecture & Architectural Tipping Points**: Enforce Kent Beck's "Refactor-Before-Add" protocol and 5 explicit tipping points to halt AI-generated code rot.
+  4. Mandate **True Incremental TDD & Nano-Cycles**: Prohibit batch-test dumps ("Test-First Waterfall"); enforce Uncle Bob's Three Laws (especially Law #2) and Ping-Pong pair programming with verified RED failure proofs.
+- **Enforced In:** [`AGENTS.md`](./AGENTS.md), [`clean_code.md`](./docs/rules/clean_code.md), [`domain_driven_design.md`](./docs/rules/domain_driven_design.md), [`test_driven_development.md`](./docs/rules/test_driven_development.md), [`lets-build`](./.agents/skills/lets-build/SKILL.md), [`architecture_interview_matrix.md`](./.agents/skills/lets-build/references/architecture_interview_matrix.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azcodr",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Enterprise Multi-Tenant Architecture & Agentic Engineering Starter Template",
   "bin": {
     "azcodr": "bin/azcodr.js"