azcodr 1.3.0 → 1.5.0

package/.agents/skills/lets-build/references/hexagonal_bootstrap_scaffolds.md

@@ -6,20 +6,29 @@
 
 ## 1. Universal Directory Topology
 
-Regardless of language, all bootstrapped projects must follow this high-level separation:
+Depending on whether the project target is a **Fullstack Web SaaS** (Frontend + Backend) or a **Headless Service** (API only), projects follow these standard layouts:
 
+### Fullstack Web SaaS Topology (Web Frontend + Hexagonal Backend)
 ```
 <project-root>/
 ├── .agents/skills/                   # Specialized agentic workflows (carried from azcodr template)
 ├── docs/
 │   ├── knowledge/                    # Domain knowledge & living ubiquitous language glossary
-│   └── rules/                        # 41 atomic single-responsibility domain rules
+│   └── rules/                        # 28 cohesive single-responsibility domain rules
 ├── specs/                            # Canonical contract specifications
-│   ├── protobuf/                     # gRPC service definitions (*.proto)
 │   ├── openapi/                      # OpenAPI 3.1 REST specifications (*.yaml)
 │   ├── schemas/                      # Universal JSON Schema Draft 2020-12 (*.json)
 │   └── tokens/                       # W3C DTCG Design Tokens (tokens.json)
-├── src/                              # Application source code
+├── client/                           # Web Frontend Application (Vite + React / SPA)
+│   ├── src/
+│   │   ├── components/
+│   │   │   ├── layout/               # Persistent Shell (Sidebar, Header, Breadcrumbs)
+│   │   │   └── ui/                   # Accessible Headless Primitives (Radix / shadcn)
+│   │   ├── pages/                    # Dynamic Canvas Route Views
+│   │   ├── hooks/                    # Server-State Cache & URL State Synchronization
+│   │   └── services/                 # Inbound API Client Adapters
+│   └── public/                       # Static web assets
+├── src/                              # Backend Application (Hexagonal Architecture)
 │   ├── domain/                       # Core Invariant Domain (Entities, Value Objects, Invariants)
 │   ├── ports/                        # Primary (driving) and Secondary (driven) Ports
 │   │   ├── primary/                  # Inbound Use Cases, Commands, and Queries
@@ -31,6 +40,7 @@ Regardless of language, all bootstrapped projects must follow this high-level se
 │   ├── unit/                         # Fast unit tests using test doubles
 │   ├── integration/                  # Adapter integration tests with transactional rollback
 │   ├── contracts/                    # Pact / OpenAPI contract verification
+│   ├── client/                       # Frontend component and interaction tests
 │   └── acceptance/                   # BDD Gherkin / Cucumber end-to-end features
 ├── deploy/                           # Deployment & Infrastructure as Code
 │   ├── docker/                       # Minimal OCI Distroless/Scratch Dockerfiles
@@ -43,10 +53,46 @@ Regardless of language, all bootstrapped projects must follow this high-level se
 └── README.md                         # Project documentation
 ```
 
+### Headless Service Topology (Backend API Only)
+```
+<project-root>/
+├── .agents/skills/                   # Specialized agentic workflows
+├── docs/                             # Domain knowledge & 28 domain rules
+├── specs/                            # OpenAPI 3.1 & Schema contracts
+├── src/                              # Domain, Ports, Adapters
+├── tests/                            # Unit, Integration, Contracts, Acceptance
+├── deploy/                           # Docker, Compose
+├── AGENTS.md
+└── memory.md
+```
+
 ---
 
 ## 2. Language-Specific Source Layouts
 
+### TypeScript Fullstack Scaffold (`client/` + `src/` via `package.json` / `pnpm`)
+```
+client/                               # Web Frontend (Vite + React / Vue / Svelte)
+├── src/
+│   ├── components/
+│   │   ├── layout/                   # Persistent App Shell (Header, Collapsible Sidebar)
+│   │   └── ui/                       # Accessible Headless Primitives (Radix / shadcn)
+│   ├── pages/                        # Dynamic Canvas Route Views
+│   ├── hooks/                        # Server-State Cache & URL State Synchronization
+│   └── services/                     # Inbound API Client Adapters
+└── public/
+src/                                  # Core Backend (Hexagonal Ports & Adapters)
+├── domain/
+│   ├── entities/user.ts
+│   └── value-objects/tenant-id.ts
+├── ports/
+│   ├── primary/create-user.usecase.ts
+│   └── secondary/user-repository.port.ts
+└── adapters/
+    ├── primary/fastify-router.ts
+    └── secondary/kysely-user-repository.ts
+```
+
 ### Go Scaffold (`go.mod`)
 ```
 src/
@@ -89,7 +135,7 @@ src/
     └── secondary/asyncpg_repository.py
 ```
 
-### TypeScript Scaffold (`package.json` / `pnpm`)
+### TypeScript Backend-Only Scaffold (`package.json` / `pnpm`)
 ```
 src/
 ├── domain/
@@ -107,7 +153,8 @@ src/
 
 ## 3. Foundational Scaffold Invariants
 
-1. **Domain Isolation**: Code in `src/domain/` must have **zero imports** from `src/adapters/`, external web frameworks, or database drivers.
+1. **Domain Isolation**: Code in `src/domain/` must have **zero imports** from `src/adapters/`, `client/`, external web frameworks, or database drivers.
 2. **Ports as Pure Contracts**: Code in `src/ports/` contains abstract interfaces, Command DTOs, Query DTOs, and Result containers.
 3. **Adapters Depend on Ports**: `src/adapters/` implements ports defined in `src/ports/`. Adapters never depend directly on other adapters.
 4. **Contract-First Synchronization**: Whenever an API or event interface changes, the canonical contract in `specs/` must be updated and validated before adapter code is generated or modified.
+5. **Frontend Decoupling via Contract**: The frontend in `client/` consumes backend driving ports strictly via canonical OpenAPI contracts (`specs/openapi`) and W3C Design Tokens (`specs/tokens/tokens.json`). It follows the 7-Pillar Design Architecture Triage Gate ([docs/rules/ui_ux_architecture.md](../../../../docs/rules/ui_ux_architecture.md)) and accessible headless primitives ([docs/rules/frontend_architecture.md](../../../../docs/rules/frontend_architecture.md)).

package/.agents/skills/lets-build/references/project_readme_template.md

@@ -37,7 +37,7 @@
 │   ├── contracts/                    # Consumer contract tests (Pact)
 │   └── acceptance/                   # BDD Gherkin / Cucumber features
 ├── deploy/                           # OCI Distroless Dockerfiles & Compose manifests
-├── docs/rules/                       # 41 atomic single-responsibility architectural rules
+├── docs/rules/                       # 28 cohesive single-responsibility architectural rules
 ├── memory.md                         # Master memory hub & Lightweight ADR ledger
 └── AGENTS.md                         # Lean agentic directives (< 120 lines)
 ```
@@ -74,6 +74,6 @@ cp .env.example .env
 
 ## 🏛️ Architecture Governance & Decisions
 
-This project is governed by the **41 Atomic Domain Rules** located in [`docs/rules/`](./docs/rules/) and Architectural Decision Records in [`memory.md`](./memory.md):
-- **ADR Ledger:** See [`memory.md`](./memory.md) for ADR-001 through ADR-006.
-- **Architectural Rules:** See [`docs/rules/`](./docs/rules/) for TDD, Clean Code, Multi-Tenancy, Database Integrity, and DevSecOps directives.
+This project is governed by the **28 Cohesive Domain Rules** located in `docs/rules/` and Architectural Decision Records in `memory.md`:
+- **ADR Ledger:** See `memory.md` for project-specific Architectural Decision Records.
+- **Architectural Rules:** See `docs/rules/` for TDD, Clean Code, Multi-Tenancy, Database Design, and DevSecOps directives.

package/.agents/skills/lets-build/scripts/bootstrap_workspace.sh

@@ -15,66 +15,129 @@ echo "🏗️ Target Topology: ${TOPOLOGY}"
 echo "📦 Target Language Profile: ${LANGUAGE}"
 echo "--------------------------------------------------------------"
 
+# Helper to create leaf directory with .gitkeep to ensure Git tracks empty structures
+create_leaf() {
+  local dir="$1"
+  mkdir -p "${dir}"
+  if [[ -z "$(ls -A "${dir}" 2>/dev/null)" ]]; then
+    touch "${dir}/.gitkeep"
+  fi
+}
+
 case "${TOPOLOGY}" in
   extension)
     echo "1. Scaffolding Browser Extension Source Tree (src/)..."
-    mkdir -p "${WORKSPACE_ROOT}/src/background"
-    mkdir -p "${WORKSPACE_ROOT}/src/content"
-    mkdir -p "${WORKSPACE_ROOT}/src/popup"
-    mkdir -p "${WORKSPACE_ROOT}/src/shared"
-    mkdir -p "${WORKSPACE_ROOT}/public"
+    create_leaf "${WORKSPACE_ROOT}/src/background"
+    create_leaf "${WORKSPACE_ROOT}/src/content"
+    create_leaf "${WORKSPACE_ROOT}/src/popup"
+    create_leaf "${WORKSPACE_ROOT}/src/shared"
+    create_leaf "${WORKSPACE_ROOT}/public"
     
     echo "2. Scaffolding Extension Test Suites (tests/)..."
-    mkdir -p "${WORKSPACE_ROOT}/tests/unit"
-    mkdir -p "${WORKSPACE_ROOT}/tests/e2e"
+    create_leaf "${WORKSPACE_ROOT}/tests/unit"
+    create_leaf "${WORKSPACE_ROOT}/tests/e2e"
     ;;
 
   game|engine)
     echo "1. Scaffolding Game/Engine Source Tree (src/)..."
-    mkdir -p "${WORKSPACE_ROOT}/src/core"
-    mkdir -p "${WORKSPACE_ROOT}/src/ecs"
-    mkdir -p "${WORKSPACE_ROOT}/src/renderer"
-    mkdir -p "${WORKSPACE_ROOT}/src/assets"
+    create_leaf "${WORKSPACE_ROOT}/src/core"
+    create_leaf "${WORKSPACE_ROOT}/src/ecs"
+    create_leaf "${WORKSPACE_ROOT}/src/renderer"
+    create_leaf "${WORKSPACE_ROOT}/src/assets"
     
     echo "2. Scaffolding Game/Engine Test Suites (tests/)..."
-    mkdir -p "${WORKSPACE_ROOT}/tests/unit"
-    mkdir -p "${WORKSPACE_ROOT}/tests/benchmarks"
+    create_leaf "${WORKSPACE_ROOT}/tests/unit"
+    create_leaf "${WORKSPACE_ROOT}/tests/benchmarks"
     ;;
 
   cli)
     echo "1. Scaffolding CLI Source Tree (src/)..."
-    mkdir -p "${WORKSPACE_ROOT}/src/cmd"
-    mkdir -p "${WORKSPACE_ROOT}/src/core"
-    mkdir -p "${WORKSPACE_ROOT}/src/io"
+    create_leaf "${WORKSPACE_ROOT}/src/cmd"
+    create_leaf "${WORKSPACE_ROOT}/src/core"
+    create_leaf "${WORKSPACE_ROOT}/src/io"
     
     echo "2. Scaffolding CLI Test Suites (tests/)..."
-    mkdir -p "${WORKSPACE_ROOT}/tests/unit"
-    mkdir -p "${WORKSPACE_ROOT}/tests/integration"
+    create_leaf "${WORKSPACE_ROOT}/tests/unit"
+    create_leaf "${WORKSPACE_ROOT}/tests/integration"
     ;;
 
-  backend|web|saas)
+  web|saas|fullstack)
     echo "1. Scaffolding Backend / Enterprise Source Tree (src/)..."
-    mkdir -p "${WORKSPACE_ROOT}/src/domain/entities"
-    mkdir -p "${WORKSPACE_ROOT}/src/domain/value_objects"
-    mkdir -p "${WORKSPACE_ROOT}/src/domain/services"
-    mkdir -p "${WORKSPACE_ROOT}/src/ports/primary"
-    mkdir -p "${WORKSPACE_ROOT}/src/ports/secondary"
-    mkdir -p "${WORKSPACE_ROOT}/src/adapters/primary"
-    mkdir -p "${WORKSPACE_ROOT}/src/adapters/secondary"
+    create_leaf "${WORKSPACE_ROOT}/src/domain/entities"
+    create_leaf "${WORKSPACE_ROOT}/src/domain/value_objects"
+    create_leaf "${WORKSPACE_ROOT}/src/domain/services"
+    create_leaf "${WORKSPACE_ROOT}/src/ports/primary"
+    create_leaf "${WORKSPACE_ROOT}/src/ports/secondary"
+    create_leaf "${WORKSPACE_ROOT}/src/adapters/primary"
+    create_leaf "${WORKSPACE_ROOT}/src/adapters/secondary"
+
+    echo "2. Scaffolding Web Frontend Client Source Tree (client/)..."
+    create_leaf "${WORKSPACE_ROOT}/client/src/components/layout"
+    create_leaf "${WORKSPACE_ROOT}/client/src/components/ui"
+    create_leaf "${WORKSPACE_ROOT}/client/src/pages"
+    create_leaf "${WORKSPACE_ROOT}/client/src/hooks"
+    create_leaf "${WORKSPACE_ROOT}/client/src/services"
+    create_leaf "${WORKSPACE_ROOT}/client/public"
+    
+    echo "3. Scaffolding Specifications (specs/)..."
+    create_leaf "${WORKSPACE_ROOT}/specs/openapi"
+    create_leaf "${WORKSPACE_ROOT}/specs/tokens"
+    
+    echo "4. Scaffolding Fullstack Test Suites (tests/)..."
+    create_leaf "${WORKSPACE_ROOT}/tests/unit"
+    create_leaf "${WORKSPACE_ROOT}/tests/integration"
+    create_leaf "${WORKSPACE_ROOT}/tests/contracts"
+    create_leaf "${WORKSPACE_ROOT}/tests/client"
+    create_leaf "${WORKSPACE_ROOT}/tests/acceptance"
+    
+    echo "5. Scaffolding Deployment Infrastructure (deploy/)..."
+    create_leaf "${WORKSPACE_ROOT}/deploy/docker"
+    create_leaf "${WORKSPACE_ROOT}/deploy/compose"
+
+    TOKEN_SPEC="${WORKSPACE_ROOT}/specs/tokens/tokens.json"
+    if [[ ! -f "${TOKEN_SPEC}" ]]; then
+      cat << 'EOF' > "${TOKEN_SPEC}"
+{
+  "color": {
+    "brand": {
+      "primary": { "$value": "#2563eb", "$type": "color" },
+      "secondary": { "$value": "#475569", "$type": "color" },
+      "accent": { "$value": "#f59e0b", "$type": "color" }
+    }
+  },
+  "dimension": {
+    "radius": {
+      "base": { "$value": "6px", "$type": "dimension" }
+    }
+  }
+}
+EOF
+    fi
+    ;;
+
+  backend)
+    echo "1. Scaffolding Headless Backend Source Tree (src/)..."
+    create_leaf "${WORKSPACE_ROOT}/src/domain/entities"
+    create_leaf "${WORKSPACE_ROOT}/src/domain/value_objects"
+    create_leaf "${WORKSPACE_ROOT}/src/domain/services"
+    create_leaf "${WORKSPACE_ROOT}/src/ports/primary"
+    create_leaf "${WORKSPACE_ROOT}/src/ports/secondary"
+    create_leaf "${WORKSPACE_ROOT}/src/adapters/primary"
+    create_leaf "${WORKSPACE_ROOT}/src/adapters/secondary"
     
     echo "2. Scaffolding Specifications (specs/)..."
-    mkdir -p "${WORKSPACE_ROOT}/specs/openapi"
-    mkdir -p "${WORKSPACE_ROOT}/specs/tokens"
+    create_leaf "${WORKSPACE_ROOT}/specs/openapi"
+    create_leaf "${WORKSPACE_ROOT}/specs/tokens"
     
     echo "3. Scaffolding Backend Test Suites (tests/)..."
-    mkdir -p "${WORKSPACE_ROOT}/tests/unit"
-    mkdir -p "${WORKSPACE_ROOT}/tests/integration"
-    mkdir -p "${WORKSPACE_ROOT}/tests/contracts"
-    mkdir -p "${WORKSPACE_ROOT}/tests/acceptance"
+    create_leaf "${WORKSPACE_ROOT}/tests/unit"
+    create_leaf "${WORKSPACE_ROOT}/tests/integration"
+    create_leaf "${WORKSPACE_ROOT}/tests/contracts"
+    create_leaf "${WORKSPACE_ROOT}/tests/acceptance"
     
     echo "4. Scaffolding Deployment Infrastructure (deploy/)..."
-    mkdir -p "${WORKSPACE_ROOT}/deploy/docker"
-    mkdir -p "${WORKSPACE_ROOT}/deploy/compose"
+    create_leaf "${WORKSPACE_ROOT}/deploy/docker"
+    create_leaf "${WORKSPACE_ROOT}/deploy/compose"
 
     TOKEN_SPEC="${WORKSPACE_ROOT}/specs/tokens/tokens.json"
     if [[ ! -f "${TOKEN_SPEC}" ]]; then
@@ -97,12 +160,94 @@ EOF
     fi
     ;;
 
+  frontend)
+    echo "1. Scaffolding Frontend Client Source Tree (src/)..."
+    create_leaf "${WORKSPACE_ROOT}/src/components/layout"
+    create_leaf "${WORKSPACE_ROOT}/src/components/ui"
+    create_leaf "${WORKSPACE_ROOT}/src/pages"
+    create_leaf "${WORKSPACE_ROOT}/src/hooks"
+    create_leaf "${WORKSPACE_ROOT}/src/services"
+    create_leaf "${WORKSPACE_ROOT}/public"
+    
+    echo "2. Scaffolding Specifications (specs/)..."
+    create_leaf "${WORKSPACE_ROOT}/specs/tokens"
+    
+    echo "3. Scaffolding Frontend Test Suites (tests/)..."
+    create_leaf "${WORKSPACE_ROOT}/tests/unit"
+    create_leaf "${WORKSPACE_ROOT}/tests/acceptance"
+    ;;
+
   *)
     echo "1. Scaffolding Generic / Library Source Tree (src/)..."
-    mkdir -p "${WORKSPACE_ROOT}/src"
-    mkdir -p "${WORKSPACE_ROOT}/tests/unit"
+    create_leaf "${WORKSPACE_ROOT}/src"
+    create_leaf "${WORKSPACE_ROOT}/tests/unit"
     ;;
 esac
 
+# Ensure memory.md in fresh projects starts with a clean ADR slate (ADR-001)
+MEMORY_FILE="${WORKSPACE_ROOT}/memory.md"
+if [[ -f "${MEMORY_FILE}" ]]; then
+  if grep -qE "ADR-00[2-9]|ADR-0[1-9][0-9]" "${MEMORY_FILE}"; then
+    echo "🧹 Sanitizing memory.md: Resetting legacy template ADRs to clean slate (ADR-001)..."
+    cat << 'EOF' > "${MEMORY_FILE}"
+# Workspace Memory, Architecture Decisions & Knowledge Hub
+
+> **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
+
+- 📖 **[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.
+
+---
+
+## 2. Consolidated Architectural Decision Records (ADRs)
+
+### ADR Master Index
+
+| ID | Title | Date | Status | Governing Rule / Skill |
+|---|---|---|---|---|
+| *(No decisions recorded yet)* | *Record initial architecture decisions during Phase 3 of /lets-build.* | *YYYY-MM-DD* | *ACCEPTED* | *e.g. [`clean_code.md`](./docs/rules/clean_code.md)* |
+
+---
+
+### Lightweight Decision Summaries
+
+<!--
+Record project Architectural Decision Records (ADRs) below as decisions are finalized.
+Format:
+
+#### ADR-001: [Imperative Title]
+- **Date:** YYYY-MM-DD | **Status:** ACCEPTED
+- **Context:** Problem space, constraints, and operational context requiring a decision.
+- **Decision:** Chosen architecture, invariants, and implementation patterns.
+- **Consequences:** Positive benefits and deliberate trade-offs accepted.
+- **Enforced In:** Relevant rule files in docs/rules/ or code paths.
+-->
+EOF
+  fi
+fi
+
+# Deterministically generate boundary verification smoke test script (Phase 5 requirement)
+SMOKE_TEST="${WORKSPACE_ROOT}/scripts/smoke_test.sh"
+if [[ ! -f "${SMOKE_TEST}" ]]; then
+  echo "5. Generating boundary smoke test verification script (scripts/smoke_test.sh)..."
+  mkdir -p "${WORKSPACE_ROOT}/scripts"
+  cat << 'EOF' > "${SMOKE_TEST}"
+#!/usr/bin/env bash
+# ==============================================================================
+# Boundary Verification Smoke Test (Phase 5 Verification Gate)
+# ==============================================================================
+set -euo pipefail
+
+echo "Running boundary smoke verification..."
+# Extend with project-specific runtime health checks (e.g. ping health endpoint, CLI --help)
+echo "✅ Boundary smoke verification passed!"
+EOF
+  chmod +x "${SMOKE_TEST}"
+fi
+
 echo "--------------------------------------------------------------"
 echo "✅ Topology '${TOPOLOGY}' scaffolded with strict YAGNI (0 speculative folders)!"

package/.agents/skills/product-analyst/SKILL.md

@@ -53,7 +53,17 @@ Ensure every user story conforms to Bill Wake's **INVEST** criteria:
 - **Small:** Sized to be completable in 1–2 development days.
 - **Testable:** Accompanied by executable, unambiguous Gherkin acceptance criteria.
 
-**The Multi-Layer Cake Rule:** Never slice horizontally (e.g. "Create database schema only"). Always slice vertically through the full stack so that every story delivers working software.
+**The Multi-Layer Cake Rule & UI Integration:**
+- **Never slice horizontally** (e.g. *"Create database schema only"* or *"Create backend API only"*). Always slice vertically through the full stack so that every story delivers working software.
+- **Mandatory UI/UX Triage Gate for User-Facing Applications:** If the project has a frontend or user interface (Fullstack Web SaaS, Extension, Desktop), execute the **7-Pillar Design Architecture Triage Gate** ([`ui_ux_architecture.md`](../../../docs/rules/ui_ux_architecture.md)) before finalizing stories:
+  1. *Role & Identity:* Define who the user is and their operational boundary.
+  2. *Information Architecture:* Define how the view fits into the Persistent App Shell vs Dynamic Canvas.
+  3. *Experience Duality:* Clarify whether the screen belongs to an Enterprise Operator Workspace or Consumer Portal.
+  4. *Navigation & Wayfinding:* Specify sidebar route, active tab, breadcrumbs, and command palette entries.
+  5. *State & URL Synchronization:* Specify query params (`?tab=`, `?q=`, `?page=`, `?modal=`).
+  6. *Access Control:* Specify route guards and permission checks.
+  7. *Accessibility & Feedback:* Specify accessible notifications, focus trapping, and zero native alerts.
+- **Every user-facing story MUST specify:** (1) The UI view/component & user interaction, (2) The API Command/Query DTO, (3) The core domain invariant, and (4) The persistence change.
 
 ### Step 5: Decompose Stories into SMART Developer Tasks
 For engineering execution, translate INVEST user stories into Bill Wake's **SMART** developer tasks:
@@ -71,7 +81,8 @@ Map all failure paths to HTTP status codes (`400`, `401`, `403`, `404`, `409`, `
 ## 3. Gotchas & What NOT to Do
 
 - **DO NOT** confuse output (features shipped, story points burned) with outcome (value delivered, satisfaction gap closed).
-- **DO NOT** write horizontal, technical user stories (e.g., *"As a developer, I want a database table"*).
+- **DO NOT** write horizontal, technical user stories (e.g., *"As a developer, I want a database table"* or *"As an API, I want a REST endpoint"*).
+- **DO NOT** author backend-only user stories or ignore the UI when analyzing a user-facing system. If the system has a web frontend or client interface, slicing must start with user interactions and views.
 - **DO NOT** force technical constraints, security policies, or infrastructure upgrades into user story syntax. Treat them as non-story requirements or architectural spikes.
 - **DO NOT** omit the Out-of-Scope ("Won't Have this time") section. Lack of negative boundaries causes runaway scope bloat.
 - **DO NOT** allow developer tasks to be open-ended without a measurable time-box. If a task exceeds 4 hours, it must be split or paired.

package/.agents/skills/relentless-questioner/SKILL.md

@@ -37,6 +37,7 @@ Upon receiving a user task or feature prompt, classify the functional archetype
 - **Archetype C: Asynchronous & Event Streaming** (background jobs, webhooks, queues, pub/sub)
 - **Archetype D: 3rd-Party & External Integrations** (external APIs, payment gateways, mailers)
 - **Archetype E: Read Performance & Search** (dashboards, aggregations, high-scale read traffic)
+- **Archetype F: User Interface, Experience Duality & Interaction Flows** (personas, app shell, screen journeys, URL synchronization, WCAG accessibility per [`ui_ux_architecture.md`](../../../docs/rules/ui_ux_architecture.md) and [`frontend_architecture.md`](../../../docs/rules/frontend_architecture.md))
 
 ---
 
@@ -58,10 +59,12 @@ Do NOT dump a massive 20-question static checklist. Execute the interview in **d
 ---
 
 ### Phase 3: Architectural Friction & Rule Reconciliation
-Check the user's proposed answers against the **47 Atomic Domain Rules** in `docs/rules/`:
-- If the user proposes writing to the database and publishing an event sequentially ➔ **Flag the dual-write anti-pattern** and mandate the Transactional Outbox pattern ([`database_transactions.md`](../../../docs/rules/database_transactions.md)).
-- If the user proposes storing tenant data without an isolation mechanism ➔ **Flag the tenant leak risk** and mandate an isolation model ([`multitenancy_isolation.md`](../../../docs/rules/multitenancy_isolation.md)).
-- If the user proposes arbitrary untrusted script execution ➔ **Flag the host security vulnerability** and mandate Wasm sandboxing ([`tenant_pluggable_logic.md`](../../../docs/rules/tenant_pluggable_logic.md)).
+Check the user's proposed answers against the **28 Cohesive Domain Rules** in `docs/rules/`:
+- If the user proposes writing to the database and publishing an event sequentially ➔ **Flag the dual-write anti-pattern** and mandate the Transactional Outbox pattern ([`database_design.md`](../../../docs/rules/database_design.md)).
+- If the user proposes storing tenant data without an isolation mechanism ➔ **Flag the tenant leak risk** and mandate an isolation model ([`multitenancy_architecture.md`](../../../docs/rules/multitenancy_architecture.md)).
+- If the user proposes arbitrary untrusted script execution ➔ **Flag the host security vulnerability** and mandate Wasm sandboxing ([`multitenancy_architecture.md`](../../../docs/rules/multitenancy_architecture.md)).
+- If the user proposes a fullstack feature but ignores user workflows or screens ➔ **Flag the Anemic Core anti-pattern** and mandate Outside-In interaction discovery ([`frontend_architecture.md`](../../../docs/rules/frontend_architecture.md)).
+- If the user proposes ad-hoc modal alerts or unstructured page navigation ➔ **Flag UX debt** and enforce the 7-Pillar Design Architecture Triage Gate ([`ui_ux_architecture.md`](../../../docs/rules/ui_ux_architecture.md)).
 - Reconcile the conflict collaboratively before proceeding.
 
 ---
@@ -78,7 +81,7 @@ Synthesize the answers into an unambiguous **Feature Alignment Specification (FA
 - **DO NOT** ask 10+ questions at once. Keep batches small (2–3 questions) to maintain a collaborative conversation.
 - **DO NOT** start coding or planning in parallel while the interrogation is in progress.
 - **DO NOT** let the user bypass critical failure branches (e.g. *"we'll handle errors later"*). Insist on defining failure states.
-- **DO NOT** compromise on the 41 atomic rules. If a user request introduces an architectural violation, surface it immediately.
+- **DO NOT** compromise on the 28 cohesive domain rules. If a user request introduces an architectural violation, surface it immediately.
 
 ---
 
@@ -118,3 +121,8 @@ Synthesize the answers into an unambiguous **Feature Alignment Specification (FA
   ```
 - **Test Strategy:** [Contract / Integration / Unit tests required for 100% coverage]
 ```
+
+---
+
+## 5. Subdirectories & Progressive Resources
+- [references/adaptive_question_trees.md](./references/adaptive_question_trees.md): Contextual branching trees for state mutations, multi-tenancy, integrations, and caching.

package/.agents/skills/relentless-questioner/references/adaptive_question_trees.md

@@ -70,6 +70,24 @@ flowchart TD
 
 ---
 
+## Decision Tree 5: User Interface, Experience Duality & Interaction Flows
+
+```mermaid
+flowchart TD
+  Q1["Does the feature introduce or modify a user interface?"]
+  Q1 -->|Yes| Q2["Who is the primary actor and operational persona?"]
+  
+  Q2 -->|Operator / Admin| Q_Op["1. Information Density: Dense tabular grid with filters?\n2. Persistent App Shell: Left collapsible sidebar route?\n3. Actions: Inline row actions or full-page drawer?"]
+  Q2 -->|Consumer / Member| Q_Member["1. Experience Duality: Consumer portal (/portal)?\n2. Touch Ergonomics: Clean cards & mobile drawer?\n3. Simplified self-service actions?"]
+
+  Q_Op --> Q3["Navigation & State Synchronization"]
+  Q_Member --> Q3
+
+  Q3 --> Q_State["1. URL State: Deep-link query params (?tab=, ?q=, ?page=, ?modal=)?\n2. Server Cache: TanStack Query hook with automated invalidation?\n3. Accessibility: Accessible headless dialogs & ARIA live regions?"]
+```
+
+---
+
 ## Contextual Follow-Up Patterns
 
 When conducting the interview, use this exact syntax pattern to chain questions adaptively:

package/.gitignore

@@ -3,6 +3,8 @@ node_modules/
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+*.log
+*.log.*
 
 # Test coverage
 coverage/

package/AGENTS.md

@@ -1,10 +1,11 @@
 # AGENTS.md
 
-> **Operating Framework & Agent Directives**  
+> **azcodr: Enterprise Architecture & Agentic Engineering Starter Template**  
+> **Workspace Mission:** Problem-first, topology-aligned production architectures governed by strict systemic atomicity, 100% open-source standards, true incremental TDD nano-cycles, and zero speculative bloat.  
+> **Runtime & Tools:** Node.js (`>=18.0.0`), npm (`>=10.0.0`) | `npm test` (test runner), `npm run test:coverage` (100% gate), `npm run lint`, `npm run validate`.  
 > **Rule Zero:** Assume nothing. Every action must be grounded in verified evidence from this workspace or direct instructions from the user.  
-> **Open-Source Mandate:** Always utilize 100% open-source tools, frameworks, libraries, and packages across all architectural domains.  
-> **Atomicity Mandate:** All rules, skills, code units, migrations, and transactions must be strictly atomic (indivisible, self-contained, and composable with full ACID safety).  
-> **Architecture Mandate:** Architecture emerges strictly from problem constraints and execution targets (Problem-First; zero tool/platform bias). Match architectural style to problem topology (Hexagonal for enterprise backends, Platform Scripting for extensions, Data-Oriented Design for game engines, Command Pipeline for CLIs, Game Loop for canvas games). Never force premature abstractions or universal templates.
+> **Atomicity Mandate:** All rules, skills, code units, migrations, and transactions must be strictly atomic (indivisible, self-contained, composable with full ACID safety).  
+> **Architecture Mandate:** Architecture emerges strictly from problem constraints and execution targets (Problem-First; zero tool/platform bias). Match architectural style to problem topology (Hexagonal for backends, Platform Scripting for extensions, Data-Oriented Design for game engines, Command Pipeline for CLIs, Game Loop for canvas games).
 
 ---
 
@@ -56,50 +57,34 @@ To prevent context bloat and keep prompt overhead minimal, detailed engineering
 
 | Domain | Rule Reference File | When to Consult |
 |---|---|---|
-| **TDD Double Loop** | [docs/rules/test_driven_development.md](./docs/rules/test_driven_development.md) | Outside-In TDD (London School), collaborator discovery, mock ownership. |
-| **Test Coverage & Isolation** | [docs/rules/test_isolation.md](./docs/rules/test_isolation.md) | 100.00% full-stack coverage, status codes, transactional DB rollback. |
+| **TDD & Isolation** | [docs/rules/test_driven_development.md](./docs/rules/test_driven_development.md) | Outside-In TDD, Uncle Bob's 3 Laws, 100% coverage, test isolation & DB rollback. |
 | **Clean Code** | [docs/rules/clean_code.md](./docs/rules/clean_code.md) | Naming, small functions, CQS, SLAP, DRY, DbC, zero side-effects. |
-| **Design Patterns** | [docs/rules/design_patterns.md](./docs/rules/design_patterns.md) | Adapter, Factory, Strategy, Result `<T, E>`, and complete 23 GoF catalog. |
-| **Type Safety** | [docs/rules/typescript.md](./docs/rules/typescript.md) | Compiler strictness, branded nominal types, type safety, static sound invariants. |
-| **ADRs** | [docs/rules/architecture_decision_records.md](./docs/rules/architecture_decision_records.md) | Authoring Lightweight Architectural Decision Records in `memory.md`. |
+| **Design Patterns** | [docs/rules/design_patterns.md](./docs/rules/design_patterns.md) | Adapter, Factory, Strategy, Result `<T, E>`, and GoF pattern catalog. |
+| **Type Safety** | [docs/rules/type_safety.md](./docs/rules/type_safety.md) | Compiler strictness, branded nominal types, type discriminators across polyglot languages. |
 | **Authentication** | [docs/rules/authentication.md](./docs/rules/authentication.md) | In-memory access tokens, refresh token rotation (RTR), WebAuthn passkeys. |
 | **Authorization** | [docs/rules/authorization.md](./docs/rules/authorization.md) | CASL, OPA Rego policy engines, OpenFGA ReBAC, server guards. |
-| **Multi-Tenancy Isolation** | [docs/rules/multitenancy_isolation.md](./docs/rules/multitenancy_isolation.md) | Tenant context resolution, 4 universal data isolation models, RLS/interceptor safety. |
-| **REST API Conventions** | [docs/rules/rest_api_conventions.md](./docs/rules/rest_api_conventions.md) | Standard HTTP status codes, enumeration masking, subresource endpoints. |
-| **Advanced API Patterns** | [docs/rules/advanced_api_patterns.md](./docs/rules/advanced_api_patterns.md) | Allowed Actions (`_actions`), Idempotency keys, cursor pagination, OCC. |
-| **API Versioning** | [docs/rules/api_versioning.md](./docs/rules/api_versioning.md) | URI versioning (`/v1/`), RFC 8594 Sunset/Deprecation headers, 90-day window. |
-| **Tenant Dynamic Schemas** | [docs/rules/tenant_dynamic_schemas.md](./docs/rules/tenant_dynamic_schemas.md) | Hybrid core + JSON/document storage, JSON Schema Draft 2020-12, meta-schemas. |
-| **Tenant Pluggable Logic** | [docs/rules/tenant_pluggable_logic.md](./docs/rules/tenant_pluggable_logic.md) | Common Expression Language (CEL), Wasm sandboxing, durable workflows (Temporal/BPMN). |
-| **Server-Driven UI** | [docs/rules/server_driven_ui.md](./docs/rules/server_driven_ui.md) | Client-agnostic layout schemas, multi-renderer component registries, DTCG tokens. |
-| **Database Transactions** | [docs/rules/database_transactions.md](./docs/rules/database_transactions.md) | ACID atomicity, isolation levels, defensive timeouts, transactional outbox. |
-| **Database Migrations** | [docs/rules/database_migrations.md](./docs/rules/database_migrations.md) | Declarative/versioned migrations (Atlas/Flyway), zero-downtime expand-contract. |
-| **Database Integrity** | [docs/rules/database_integrity.md](./docs/rules/database_integrity.md) | Foreign keys, domain CHECK constraints, interval EXCLUDE, soft-delete indexes. |
-| **Database Operations** | [docs/rules/database_operations.md](./docs/rules/database_operations.md) | Continuous PITR, autovacuum/defrag tuning, connection pooling, role separation. |
-| **Database Performance** | [docs/rules/database_performance.md](./docs/rules/database_performance.md) | Eliminating N+1 queries, DataLoader batching, composite tenant indexes. |
-| **Caching** | [docs/rules/caching.md](./docs/rules/caching.md) | Cache Port semantics, Cache-Aside, jittered TTLs, XFetch stampede defense. |
-| **Application Security** | [docs/rules/application_security.md](./docs/rules/application_security.md) | OWASP Top 10 defenses, cryptographic rigor, token bucket rate limiting. |
-| **Regulatory Compliance** | [docs/rules/compliance.md](./docs/rules/compliance.md) | SOC 2 Type II controls, ISO/IEC 27001 ISMS, GDPR data erasure rights. |
-| **DevSecOps** | [docs/rules/devsecops.md](./docs/rules/devsecops.md) | Secretlint pre-commit gating, CycloneDX SBOM generation, Trivy/Grype scanning. |
+| **Multi-Tenancy** | [docs/rules/multitenancy_architecture.md](./docs/rules/multitenancy_architecture.md) | Tenant context, 4 isolation models, RLS, dynamic schemas, pluggable logic & YAGNI gates. |
+| **API Architecture** | [docs/rules/api_architecture.md](./docs/rules/api_architecture.md) | HTTP status codes, sync vs async (202), `_actions`, idempotency keys, cursor pagination, OCC, versioning. |
+| **Server-Driven UI** | [docs/rules/server_driven_ui.md](./docs/rules/server_driven_ui.md) | Backend-driven layout schemas, multi-renderer component registries, DTCG tokens & YAGNI gate. |
+| **Database Design** | [docs/rules/database_design.md](./docs/rules/database_design.md) | Relational integrity, FKs, CHECK constraints, Canonical 6 audit fields, ACID transactions, Outbox CDC. |
+| **Database Operations** | [docs/rules/database_operations.md](./docs/rules/database_operations.md) | Zero-downtime expand-contract migrations, N+1 elimination, DataLoader, indexing, pooling, PITR. |
+| **Caching** | [docs/rules/caching.md](./docs/rules/caching.md) | Cache Port semantics, Cache-Aside, jittered TTLs, XFetch stampede defense & YAGNI gate. |
+| **Security & Compliance** | [docs/rules/security_compliance.md](./docs/rules/security_compliance.md) | OWASP Top 10 defenses, rate limiting, crypto, SOC 2 Type II, ISO 27001, GDPR data erasure. |
+| **DevOps & CI/CD** | [docs/rules/devops_ci_cd.md](./docs/rules/devops_ci_cd.md) | Shift-left trunk-based CI, OCI distroless containers, Secretlint/Trivy DevSecOps, zero-downtime CD. |
+| **Cloud-Native 12-Factor** | [docs/rules/cloud_native.md](./docs/rules/cloud_native.md) | 12-Factor (2026 Edition), OpenTelemetry (OTel), stateless isolates. |
 | **Error Architecture** | [docs/rules/error_handling.md](./docs/rules/error_handling.md) | Fail-fast schema validation, structured OTel/Pino tracing, RFC 7807 envelopes. |
-| **Feature Flags** | [docs/rules/feature_flags.md](./docs/rules/feature_flags.md) | OpenFeature standard, Flipt/Unleash backends, targeting, kill switches. |
-| **Continuous Integration** | [docs/rules/continuous_integration.md](./docs/rules/continuous_integration.md) | Shift-left automated pipelines, trunk-based development, build caching. |
-| **Continuous Deployment** | [docs/rules/continuous_deployment.md](./docs/rules/continuous_deployment.md) | Zero-downtime rollouts, Cosign container signing, container minimization. |
-| **Container Infrastructure** | [docs/rules/container_infrastructure.md](./docs/rules/container_infrastructure.md) | Unified gateway, minimal OCI distroless/scratch containers, non-root user security. |
+| **Feature Flags** | [docs/rules/feature_flags.md](./docs/rules/feature_flags.md) | OpenFeature standard, Flipt/Unleash backends, targeting, kill switches & YAGNI gate. |
 | **Transactional Email** | [docs/rules/transactional_email.md](./docs/rules/transactional_email.md) | Declarative templates (MJML/JSON), safe interpolation, SMTP integration testing. |
-| **Accessibility** | [docs/rules/accessibility.md](./docs/rules/accessibility.md) | WCAG 2.2 AA compliance, accessible primitives, focus trapping, ARIA live regions. |
-| **UI Navigation** | [docs/rules/ui_navigation.md](./docs/rules/ui_navigation.md) | Bidirectional URL state synchronization, deep linking, search params. |
-| **UI/UX Architecture** | [docs/rules/ui_ux_architecture.md](./docs/rules/ui_ux_architecture.md) | Design triage, persistent app shell, collapsible sidebar, dual-experience portals. |
-| **React & Frontend** | [docs/rules/react.md](./docs/rules/react.md) | Modern React, shadcn/ui, TanStack Query, React Hook Form, and Zod validation. |
+| **UI/UX Architecture** | [docs/rules/ui_ux_architecture.md](./docs/rules/ui_ux_architecture.md) | Design triage gate, persistent app shell, collapsible sidebar, dual-experience portals, dev persona. |
+| **Frontend Architecture** | [docs/rules/frontend_architecture.md](./docs/rules/frontend_architecture.md) | Accessible headless primitives, WCAG 2.2 AA, server cache sync, form validation, 5-tier state, URL navigation. |
 | **Requirements Engineering** | [docs/rules/requirements_engineering.md](./docs/rules/requirements_engineering.md) | User stories vs requirements, 3 C's, INVEST vertical cake slicing, Gherkin. |
 | **Product Ownership** | [docs/rules/product_ownership.md](./docs/rules/product_ownership.md) | Product Backlog Management, OKRs, Kano/MoSCoW/RICE, Product Value, empiricism. |
-| **Domain-Driven Design** | [docs/rules/domain_driven_design.md](./docs/rules/domain_driven_design.md) | Ubiquitous Language, Bounded Contexts, Aggregates, Capability Mapping. |
-| **Workflow State Machines** | [docs/rules/workflow_state_machines.md](./docs/rules/workflow_state_machines.md) | Configurable workflows, in-aggregate invariant FSMs, transition guards & audit logs. |
-| **Cloud-Native 12-Factor** | [docs/rules/cloud_native.md](./docs/rules/cloud_native.md) | 12-Factor (2026 Edition), OpenTelemetry (OTel), stateless isolates. |
-| **Agentic Config & Skills** | [docs/rules/agentic_configuration.md](./docs/rules/agentic_configuration.md) | Progressive disclosure architecture, skill inquiry branches, refinement loop. |
 | **Project Management** | [docs/rules/project_management.md](./docs/rules/project_management.md) | Work-In-Progress limits (WIP = 1), SMART developer tasks, Definition of Done. |
+| **Domain-Driven Design** | [docs/rules/domain_driven_design.md](./docs/rules/domain_driven_design.md) | Ubiquitous Language, Bounded Contexts, Aggregates, Capability Mapping. |
+| **CQRS & Projections** | [docs/rules/cqrs.md](./docs/rules/cqrs.md) | Evolutionary CQRS spectrum, YAGNI defense, read projections, outbox CDC. |
+| **Workflow State Machines** | [docs/rules/workflow_state_machines.md](./docs/rules/workflow_state_machines.md) | Configurable workflows, in-aggregate invariant FSMs, transition guards & audit logs & YAGNI gate. |
+| **Agentic Governance** | [docs/rules/agentic_configuration.md](./docs/rules/agentic_configuration.md) | Progressive disclosure, ADR ledger, workspace sovereignty, continuous learning, YAGNI gate triad. |
 | **Relentless Questioning** | [docs/rules/relentless_questioning.md](./docs/rules/relentless_questioning.md) | Dynamic context-aware interrogation loops, adaptive decision trees. |
-| **Workspace Isolation** | [docs/rules/workspace_isolation.md](./docs/rules/workspace_isolation.md) | Strict workspace sovereignty, zero global contamination, local ground truth. |
-| **Continuous Learning** | [docs/rules/continuous_learning.md](./docs/rules/continuous_learning.md) | Direct rule ingestion, root-cause analysis, dynamic invariant updates. |
 ---
 
 ## 4. Agent Configuration & Workspace Architecture
@@ -114,4 +99,4 @@ To prevent context bloat and keep prompt overhead minimal, detailed engineering
   - [`relentless-questioner`](.agents/skills/relentless-questioner/SKILL.md): Dynamic context-aware interrogation loops before planning and coding.
 - **Relentless Skill Architecture Inquiry:** Never author or update skills on assumptions. Interrogate all 7 inquiry branches (placement, trigger intent, domain truth, gotchas/anti-patterns, determinism, progressive bloat, verification loop) defined in [docs/rules/agentic_configuration.md](./docs/rules/agentic_configuration.md) before writing `SKILL.md`.
 - **Workspace Memory & Knowledge Hub:** Consult [`memory.md`](./memory.md) for ADRs, and [`docs/knowledge/ubiquitous_language.md`](./docs/knowledge/ubiquitous_language.md) for domain glossaries.
-- **Harness Parity & Symlinks:** `AGENTS.md`, `CLAUDE.md`, and `agents.md` must remain identical via filesystem symbolic links to eliminate configuration divergence across different agent harnesses.
+- **Harness Parity & Symlinks:** `AGENTS.md`, `CLAUDE.md`, `agents.md`, `GEMINI.md`, `.cursorrules`, `.windsurfrules`, and `.github/copilot-instructions.md` must remain identical via filesystem symbolic links to eliminate configuration divergence across different agent harnesses.