azcodr 1.4.0 → 1.5.0

package/.agents/hooks.json.example

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "./scripts/safety_guard.sh",
+            "command": "./.agents/scripts/safety_guard.sh",
             "timeout": 15
           }
         ]
@@ -34,7 +34,7 @@
     "Stop": [
       {
         "type": "command",
-        "command": "./scripts/verify_completion.sh",
+        "command": "./.agents/scripts/verify_completion.sh",
         "timeout": 15
       }
     ]

package/.agents/scripts/safety_guard.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# safety_guard.sh
+# Example PreToolUse hook for agent commands
+# ==============================================================================
+set -euo pipefail
+
+COMMAND="${1:-}"
+
+# Reject destructive system commands targeting root or home
+if [[ "${COMMAND}" =~ (rm[[:space:]]+-[rf]{1,2}[[:space:]]+(/|\$HOME|~)) ]]; then
+  echo "🚨 Safety Guard: Destructive command rejected: ${COMMAND}" >&2
+  exit 1
+fi
+
+exit 0

package/.agents/scripts/verify_completion.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# verify_completion.sh
+# Example Stop hook ensuring tests and validation pass before agent exit
+# ==============================================================================
+set -euo pipefail
+
+# Run project validation script if configured in package.json
+if [[ -f "package.json" ]] && grep -q '"validate"' "package.json"; then
+  npm run validate
+fi
+
+exit 0

package/.agents/skills/agentic-architect/SKILL.md

@@ -27,7 +27,7 @@ Before writing a single line of a skill or rule, execute the **7 Core Inquiry Br
 3. **Domain Ground Truth:** Have all generic textbook tutorials been purged? Is this grounded in verified codebase evidence?
 4. **Gotchas & Anti-Patterns:** What exact mistakes has the AI repeatedly made in this domain that must be forbidden?
 5. **Determinism vs. LLM:** Can brittle tasks be converted into deterministic scripts under `scripts/`?
-6. **Progressive Bloat:** Is `SKILL.md` strictly under 500 lines, offloading deep manuals to `references/` and templates to `assets/`?
+6. **Progressive Bloat:** Is `SKILL.md` strictly under 500 lines, offloading deep manuals to `references/` and templates to `resources/`?
 7. **Verification & Proof:** What structured response template and self-validation checklist will prove success?
 *Rule:* If any branch is unanswered or ambiguous, **STOP and ask the user** (or inspect workspace files). Never fill gaps with assumptions.
 

package/.agents/skills/agentic-architect/scripts/validate_agentic_configs.sh

@@ -6,7 +6,21 @@
 
 set -euo pipefail
 
-WORKSPACE_ROOT="${1:-$(pwd)}"
+WORKSPACE_ROOT=""
+FIX_MODE=false
+
+for arg in "$@"; do
+  if [[ "${arg}" == "--fix" ]]; then
+    FIX_MODE=true
+  elif [[ -z "${WORKSPACE_ROOT}" ]]; then
+    WORKSPACE_ROOT="${arg}"
+  fi
+done
+
+if [[ -z "${WORKSPACE_ROOT}" ]]; then
+  WORKSPACE_ROOT="$(pwd)"
+fi
+
 ERRORS=0
 WARNINGS=0
 
@@ -77,7 +91,12 @@ if [[ "${IS_CASE_INSENSITIVE}" == "true" ]]; then
   log_pass "agents.md is satisfied natively by AGENTS.md (case-insensitive filesystem)."
 else
   if [[ ! -L "${AGENTS_LOWER}" ]] && [[ ! -e "${AGENTS_LOWER}" ]] && [[ -f "${AGENTS_FILE}" ]]; then
-    ln -sf "AGENTS.md" "${AGENTS_LOWER}"
+    if [[ "${FIX_MODE}" == "true" ]]; then
+      ln -sf "AGENTS.md" "${AGENTS_LOWER}"
+      log_pass "Created agents.md symlink to AGENTS.md (--fix mode)."
+    else
+      log_fail "agents.md is missing. Run with --fix to automatically repair symlinks."
+    fi
   fi
   if [[ -L "${AGENTS_LOWER}" ]]; then
     TARGET=$(readlink "${AGENTS_LOWER}")
@@ -86,6 +105,10 @@ else
     else
       log_fail "agents.md points to '${TARGET}' instead of 'AGENTS.md'."
     fi
+  elif [[ -f "${AGENTS_LOWER}" ]] && is_valid_text_pointer "${AGENTS_LOWER}"; then
+    log_pass "agents.md is a text pointer to AGENTS.md (symlink fallback)."
+  elif [[ ! -e "${AGENTS_LOWER}" ]] && [[ "${FIX_MODE}" == "true" ]]; then
+    : # Handled above
   else
     log_fail "agents.md is not a symbolic link."
   fi
@@ -153,6 +176,14 @@ if [[ -d "${WORKSPACE_ROOT}/.github" ]]; then
   fi
 fi
 
+# Check .gitignore exists
+GITIGNORE_FILE="${WORKSPACE_ROOT}/.gitignore"
+if [[ -f "${GITIGNORE_FILE}" ]]; then
+  log_pass ".gitignore exists."
+else
+  log_fail "Missing .gitignore at ${GITIGNORE_FILE}"
+fi
+
 # 2. Checking Progressive Disclosure Rules (docs/rules)
 echo ""
 echo "2. Checking Progressive Disclosure Rules..."

package/.agents/skills/lets-build/SKILL.md

@@ -45,7 +45,7 @@ Do NOT guess or assume any technology or stack choice. Execute the relentless in
 #### Batch 1: Problem Space & System Topology
 1. **Domain & Problem Statement:** What real-world problem or capability does this system solve? What data moves, and what transformations occur?
 2. **System Topology Classification:** Which topology best matches the execution target?
-   - Topology A: Web SaaS / Cloud Microservices
+   - Topology A: Web SaaS / Cloud Applications (Fullstack Web App vs Headless API)
    - Topology B: Browser Extension (Manifest V3)
    - Topology C: Game Engine / High-Performance Simulator (Bare metal, GPU)
    - Topology D: Browser / Canvas Game (HTML5 Canvas / WebGL / WebGPU)
@@ -70,7 +70,10 @@ Do NOT guess or assume any technology or stack choice. Execute the relentless in
 
 #### Batch 4: Targeted Invariants (Topology-Scoped, 100% YAGNI)
 Inquire *only* into the dimensions relevant to the selected topology:
-- *If Web SaaS / Backend:* API protocol (REST/gRPC), DB migration engine (Atlas/Flyway), tenancy isolation model, authentication, and OCI distroless containers.
+- *If Web SaaS / Cloud Application:*
+  - **Interface Scope:** Headless API service only vs Fullstack Web Application (API + Web Frontend).
+  - **If Fullstack Web Application:** Frontend framework & build tool (React + Vite, Vue 3, Svelte 5), styling & accessible headless component primitives (Tailwind CSS, Radix UI / shadcn/ui per [`frontend_architecture.md`](../../../docs/rules/frontend_architecture.md)), client directory structure (`client/` + `src/` backend), and persistent app shell layout per [`ui_ux_architecture.md`](../../../docs/rules/ui_ux_architecture.md).
+  - **Backend & Data:** API protocol (REST/OpenAPI 3.1 vs gRPC), DB migration engine (Atlas/Flyway), tenancy isolation model, authentication, and OCI distroless containers.
 - *If Browser Extension:* MV3 content script isolation (IIFE bundle), `chrome.storage.sync` flow, permissions. (Zero Docker/K8s/OpenAPI!).
 - *If Game Engine:* Graphics backend (Vulkan/DirectX/wgpu), memory allocators (arena/frame), ECS archetype model. (Zero Docker/SQL!).
 - *If CLI:* Arg parsing library, POSIX exit codes, streaming I/O, `--json` formatting. (Zero Docker/SQL!).
@@ -79,7 +82,7 @@ Inquire *only* into the dimensions relevant to the selected topology:
 
 ### Phase 3: Synthesize (Architecture Blueprint & User Sign-Off)
 1. Consolidate the user's answers into a formal **Consolidated Architectural Blueprint** (using Section 4 template).
-2. Author an Architectural Decision Record in `memory.md` (e.g. `ADR-025: Target Technology Stack & Scaffolding Baseline` or next sequential ADR).
+2. Author the project's foundational Architectural Decision Record in `memory.md`, strictly starting with **`ADR-001: Target Technology Stack & Scaffolding Baseline`**. For a freshly initialized or bootstrapped project, `memory.md` must be a clean slate (zero prior decisions). If `memory.md` contains any legacy template ADRs from `azcodr`, sanitize and reset them so the new project starts from `ADR-001`.
 3. **STOP AND ASK FOR EXPLICIT CONFIRMATION**: Present the blueprint and ADR to the user. Do NOT write scaffolding code until the user approves the blueprint.
 
 ---
@@ -91,7 +94,8 @@ Upon user confirmation:
    bash .agents/skills/lets-build/scripts/bootstrap_workspace.sh . <topology> <language>
    ```
 2. Generate base infrastructure strictly for the selected topology (zero speculative bloat) using layouts from [references/hexagonal_bootstrap_scaffolds.md](./references/hexagonal_bootstrap_scaffolds.md):
-   - *Backend:* `specs/openapi/v1/openapi.yaml`, `specs/tokens/tokens.json`, `deploy/docker`, `deploy/compose`.
+   - *Fullstack Web SaaS:* Backend in `src/`, Web Client in `client/` (`client/src/components/layout`, `client/src/components/ui`, `client/src/pages`, `client/src/hooks`, `client/src/services`), `specs/openapi/v1/openapi.yaml`, `specs/tokens/tokens.json`, `deploy/docker`, `deploy/compose`.
+   - *Headless Backend:* `src/domain/`, `src/ports/`, `src/adapters/`, `specs/openapi/v1/openapi.yaml`, `specs/tokens/tokens.json`, `deploy/docker`, `deploy/compose`.
    - *Extension:* `manifest.json`, `src/background/index.ts`, `src/content/index.ts`, `src/popup/index.html`.
    - *Game / Engine:* `src/core/`, `src/ecs/`, asset manifest, frame loop entrypoint.
    - *CLI:* `src/cmd/`, `src/core/`, CLI entrypoint with exit code handling.
@@ -113,11 +117,14 @@ Upon user confirmation:
    - **`lets-build` IS NOW COMPLETE.** Do NOT proceed to write domain business entities, repositories, or application features.
    - Present the bootstrapped technical skeleton to the user.
    - Instruct the user to invoke `product-analyst` and `relentless-questioner` to initiate the **Domain Discovery & Requirements Engineering Phase** (Ubiquitous Language, Bounded Contexts, Aggregate Boundaries, INVEST User Stories, and Gherkin Acceptance Criteria) before any domain feature code is written.
+   - For applications with a user interface (Fullstack Web SaaS, Extensions, Desktop), the handover must explicitly instruct the user and agent to execute the **7-Pillar Design Architecture Triage Gate** ([`ui_ux_architecture.md`](../../../docs/rules/ui_ux_architecture.md)) to define user personas, persistent app shell navigation, and user journeys.
 
 ---
 
 ## 3. Gotchas & What NOT to Do
 
+- **MAJOR DONT: NEVER carry over template-internal ADRs from azcodr into a new project.** When scaffolding or bootstrapping a new project, `memory.md` must be a clean slate and start at `ADR-001`. Do NOT number the first architecture decision as ADR-025 or ADR-028 based on azcodr's template development history.
+- **MAJOR DONT: NEVER silently drop the frontend or treat Fullstack Web SaaS as a headless backend API!** If the user selects a Fullstack Web application with a UI, you MUST scaffold both the client (`client/`) and backend (`src/`) baselines, configure build manifests for both, execute the 7-Pillar Design Architecture Triage Gate, and ensure user stories slice vertically across both UI and API layers.
 - **MAJOR DONT: DO NOT invent, assume, or scaffold application domain entities, business logic, or feature pages during `/lets-build`.** The `lets-build` skill is strictly an infrastructure and technical stack bootstrapper. Fabricating business domain features without dedicated domain analysis and relentless questioning of the user is a fatal architectural defect.
 - **DO NOT** assume the stack. Never start writing Go, Rust, Python, or TypeScript before asking the user.
 - **DO NOT** scaffold universal web boilerplate (Docker, Kubernetes, OpenAPI, Postgres migrations) for non-backend projects (Browser Extensions, CLIs, Game Engines, Desktop apps).

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

@@ -16,7 +16,7 @@
 
 ### Dimension 2: System Topology Classification
 Classify the system into its primary operational topology:
-1. **Topology A — Web SaaS / Cloud Microservices:** Network-facing HTTP/gRPC services with multi-tenant data persistence and web/mobile clients.
+1. **Topology A — Web SaaS / Cloud Applications:** Network-facing systems with multi-tenant data persistence, ranging from Fullstack Web Applications (API Backend + Web Frontend) to Headless Microservices (API-only).
 2. **Topology B — Browser Extension:** Client-side sandboxed extension (Chrome/Firefox MV3) orchestrating content scripts, background service workers, and popup UI.
 3. **Topology C — Game Engine / High-Performance Simulator:** Low-level, frame-budgeted application directly interfacing with GPU APIs (Vulkan, DirectX, Metal) and system memory.
 4. **Topology D — Browser / Canvas Game:** Sandboxed web game running inside the browser DOM/Canvas via Canvas2D, WebGL, or WebGPU.
@@ -86,7 +86,13 @@ Derive the programming language, runtime, and package manager strictly from the
 
 Inquire *only* into the dimensions relevant to the selected topology. **Never ask non-backend projects about databases, containers, or API versioning!**
 
-### For Web SaaS & Enterprise Backends ONLY:
+### For Web SaaS & Enterprise Cloud Applications ONLY:
+- **Application Interface Scope:** Headless API service (no UI) vs Fullstack Web Application (API Backend + Web Frontend Client).
+- **Frontend UI Stack (If Fullstack Web Application):**
+  - **Framework & Runtime:** React + Vite, Vue 3, Svelte 5, Next.js.
+  - **Component Primitives & Styling:** Tailwind CSS + Accessible Headless Primitives (Radix UI / shadcn/ui) per [docs/rules/frontend_architecture.md](../../../../docs/rules/frontend_architecture.md).
+  - **Client Structure:** Paired Client (`client/` + `src/` backend) vs Monorepo (`apps/web` + `apps/api`).
+  - **Design Triage & App Shell:** Persistent App Shell (collapsible sidebar, global header) vs Dynamic Canvas per [docs/rules/ui_ux_architecture.md](../../../../docs/rules/ui_ux_architecture.md).
 - **API Protocols:** REST (OpenAPI 3.1) vs gRPC (Protobuf v3 via Buf) vs GraphQL.
 - **Database Migrations:** Declarative (Atlas) vs Versioned SQL (Flyway, Goose).
 - **Multi-Tenancy Isolation:** AST Query Interceptor vs Database RLS vs Schema-per-tenant.

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

@@ -6,8 +6,9 @@
 
 ## 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)
@@ -15,11 +16,19 @@ Regardless of language, all bootstrapped projects must follow this high-level se
 │   ├── knowledge/                    # Domain knowledge & living ubiquitous language glossary
 │   └── 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/scripts/bootstrap_workspace.sh

@@ -61,7 +61,7 @@ case "${TOPOLOGY}" in
     create_leaf "${WORKSPACE_ROOT}/tests/integration"
     ;;
 
-  backend|web|saas)
+  web|saas|fullstack)
     echo "1. Scaffolding Backend / Enterprise Source Tree (src/)..."
     create_leaf "${WORKSPACE_ROOT}/src/domain/entities"
     create_leaf "${WORKSPACE_ROOT}/src/domain/value_objects"
@@ -70,6 +70,60 @@ case "${TOPOLOGY}" in
     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/)..."
     create_leaf "${WORKSPACE_ROOT}/specs/openapi"
@@ -106,6 +160,23 @@ 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/)..."
     create_leaf "${WORKSPACE_ROOT}/src"
@@ -113,6 +184,52 @@ EOF
     ;;
 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

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))
 
 ---
 
@@ -62,6 +63,8 @@ Check the user's proposed answers against the **28 Cohesive Domain Rules** in `d
 - 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.
 
 ---

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

@@ -99,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`, `agents.md`, `GEMINI.md`, `.cursorrules`, and `.windsurfrules` 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.

package/bin/azcodr.js

@@ -97,6 +97,9 @@ async function runCli(rawArgs = process.argv.slice(2), io = {}) {
       return exit(1);
     } else if (!targetDir) {
       targetDir = arg;
+    } else {
+      err(`❌ Error: Unexpected argument '${arg}'. Run 'npx azcodr --help' for available options.`);
+      return exit(1);
     }
   }
 
@@ -181,18 +184,20 @@ async function runCli(rawArgs = process.argv.slice(2), io = {}) {
       out('  ✅ Workspace knowledge hub and ADR ledger copied (docs/knowledge/, memory.md)');
       out('  ✅ Specialized agentic skills copied (.agents/skills/)');
       out('  ✅ Editor formatting standards initialized (.editorconfig)');
-      out('  ✅ Agent directives and harness symlinks established (AGENTS.md, CLAUDE.md, agents.md, GEMINI.md, .cursorrules, .windsurfrules)');
+      out('  ✅ Agent directives and harness symlinks established (AGENTS.md, CLAUDE.md, agents.md, GEMINI.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md)');
+      out('  ✅ Project configuration initialized (package.json)');
       if (result.gitInitialized) {
         out('  ✅ Git repository initialized');
       }
 
       out('\n🎉 azcodr initialized successfully!\n');
       out('Next steps:');
+      let step = 1;
       if (targetDir !== '.' && targetDir !== './') {
-        out(`  1. cd ${targetDir}`);
+        out(`  ${step++}. cd ${targetDir}`);
       }
-      out('  2. Open the project in your AI coding assistant (Antigravity, Claude Code, Cursor, OpenHands)');
-      out('  3. Run /lets-build to start the architectural interview and scaffold your application stack!\n');
+      out(`  ${step++}. Open the project in your AI coding assistant (Antigravity, Claude Code, Cursor, OpenHands)`);
+      out(`  ${step++}. Run /lets-build to start the architectural interview and scaffold your application stack!\n`);
     }
     return exit(0);
   } catch (error) {

package/docs/rules/agentic_configuration.md

@@ -40,6 +40,7 @@ Different AI agents and IDE harnesses look for different configuration filenames
 - Google Antigravity & Gemini CLI: `GEMINI.md`
 - Cursor: `.cursorrules`
 - Windsurf: `.windsurfrules`
+- GitHub Copilot: `.github/copilot-instructions.md`
 
 **Standard:** Maintain identical configuration across all harnesses by establishing filesystem symbolic links:
 ```bash
@@ -48,6 +49,7 @@ ln -sf AGENTS.md CLAUDE.md
 ln -sf AGENTS.md GEMINI.md
 ln -sf AGENTS.md .cursorrules
 ln -sf AGENTS.md .windsurfrules
+mkdir -p .github && ln -sf ../AGENTS.md .github/copilot-instructions.md
 ```
 Never duplicate content into separate files.
 
@@ -253,4 +255,5 @@ Significant architectural, technical stack, or invariant decisions must be captu
 ### Numbering & Immutability:
 - ADR numbers are monotonically increasing (`ADR-001`, `ADR-002`, ...).
 - ADR entries are **immutable history**. Never edit past accepted ADRs to represent new decisions; author a new ADR that explicitly supersedes the former.
+- **Fresh Project Baseline (ADR Clean Slate):** When starting or bootstrapping a new project from this starter template, the memory ledger in [`memory.md`](../../memory.md) must be a clean slate with zero prior decisions recorded. The initial technical foundation derived during `/lets-build` must always be recorded as **`ADR-001`**. Template development history from `azcodr` must never bleed into downstream project memory ledgers.
 

package/docs/rules/relentless_questioning.md

@@ -39,6 +39,10 @@ Questions must dynamically pivot depending on the technical archetype:
 *Trigger:* The feature interacts with external SaaS, webhooks, or cloud services.
 - *Adaptive Inquiries:* What is the project-owned Port/Adapter boundary interface? What are the rate-limiting and circuit-breaking parameters? How are mock test doubles constructed without mocking third-party types directly?
 
+### Branch E: User Interface, Experience Duality & Interaction Flows
+*Trigger:* The feature introduces or modifies user interfaces, web pages, screen layouts, form mutations, or navigation.
+- *Adaptive Inquiries:* Who is the target user persona (Operator/Admin dense workspace vs Consumer/Member portal)? How does the view fit into the Persistent App Shell (collapsible sidebar, global header) vs Dynamic Canvas? What is the URL state synchronization strategy (`useSearchParams` for `?tab=`, `?q=`, `?page=`, `?modal=`)? What server-state cache manager synchronizes data (TanStack Query)? How are validation feedback and errors displayed (RFC 7807 inline/toast alerts, WCAG 2.2 live regions, zero native `window.alert()`)?
+
 ---
 
 ## 3. Anti-Assumption Guardrails

package/docs/rules/test_driven_development.md

@@ -66,6 +66,7 @@ Deviating from this lifecycle introduces catastrophic defects and architectural
 | **Skipping Domain Analysis** | Hallucinated entities, missing business invariants, wrong data models. | "The Toy Prototype Blunder": Foreign key string inputs, unvalidated states, costly migrations. |
 | **Writing Code Before Tests** | Untested edge cases, unfalsifiable code, confirmation bias in test design. | Hidden bugs in production, regressions during refactoring, brittle codebases. |
 | **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. |
+| **Dropping the UI in Fullstack TDD** | Developer plunges into internal domain units, leaving the application headless with no web UI. | "The Headless Fallacy": User requests a fullstack web app but receives pure headless backend libraries. |
 | **Skipping the Refactor Phase** | Technical debt accumulates immediately behind green tests. | Code rot, duplicated logic, bloated monolithic functions (> 30 lines), violated DRY/SLAP. |
 
 ---

package/lib/scaffold.js

@@ -11,7 +11,8 @@ const TEMPLATE_ITEMS = [
   'docs',
   '.agents',
   '.gitignore',
-  '.editorconfig'
+  '.editorconfig',
+  'LICENSE'
 ];
 
 /**
@@ -93,7 +94,7 @@ function ensureSymlink(targetDir, linkName, targetFileName, dryRun = false) {
     return true;
   } catch {
     // Fallback if environment (e.g., certain Windows configs) prevents symlink creation
-    const sourceFile = path.join(targetDir, targetFileName);
+    const sourceFile = path.resolve(targetDir, targetFileName);
     if (fs.existsSync(sourceFile)) {
       fs.copyFileSync(sourceFile, linkPath);
     }
@@ -102,10 +103,29 @@ function ensureSymlink(targetDir, linkName, targetFileName, dryRun = false) {
 }
 
 /**
- * Ensures all bash scripts in skill directories have executable permissions (0o755).
+ * Ensures all bash scripts in agent and skill directories have executable permissions (0o755).
  */
 function makeScriptsExecutable(targetDir, dryRun = false) {
   const modified = [];
+
+  const agentScriptsDir = path.join(targetDir, '.agents', 'scripts');
+  if (fs.existsSync(agentScriptsDir) && fs.statSync(agentScriptsDir).isDirectory()) {
+    const files = fs.readdirSync(agentScriptsDir);
+    for (const file of files) {
+      if (file.endsWith('.sh')) {
+        const filePath = path.join(agentScriptsDir, file);
+        modified.push(filePath);
+        if (!dryRun) {
+          try {
+            fs.chmodSync(filePath, 0o755);
+          } catch {
+            // Non-critical if filesystem does not support POSIX permissions
+          }
+        }
+      }
+    }
+  }
+
   const skillsDir = path.join(targetDir, '.agents', 'skills');
   if (!fs.existsSync(skillsDir)) return modified;
 
@@ -146,7 +166,13 @@ function copyTemplate(targetDir, templateDir = getTemplateDir(), options = {}) {
   }
 
   for (const item of TEMPLATE_ITEMS) {
-    const srcPath = path.join(resolvedTemplate, item);
+    let srcPath = path.join(resolvedTemplate, item);
+    if (item === '.gitignore' && !fs.existsSync(srcPath)) {
+      const npmIgnorePath = path.join(resolvedTemplate, '.npmignore');
+      if (fs.existsSync(npmIgnorePath)) {
+        srcPath = npmIgnorePath;
+      }
+    }
     if (!fs.existsSync(srcPath)) continue;
 
     const destPath = path.join(resolvedTarget, item);
@@ -173,6 +199,36 @@ function copyTemplate(targetDir, templateDir = getTemplateDir(), options = {}) {
   actions.push(`symlink: .windsurfrules -> AGENTS.md`);
   ensureSymlink(resolvedTarget, '.windsurfrules', 'AGENTS.md', dryRun);
 
+  // GitHub Copilot harness parity
+  const githubDir = path.join(resolvedTarget, '.github');
+  if (!dryRun && !fs.existsSync(githubDir)) {
+    fs.mkdirSync(githubDir, { recursive: true });
+  }
+  actions.push(`symlink: .github/copilot-instructions.md -> ../AGENTS.md`);
+  ensureSymlink(githubDir, 'copilot-instructions.md', '../AGENTS.md', dryRun);
+
+  // Starter package.json for project scripts validation
+  const pkgJsonPath = path.join(resolvedTarget, 'package.json');
+  if (!fs.existsSync(pkgJsonPath)) {
+    actions.push('create: package.json');
+    if (!dryRun) {
+      const projectName = path.basename(resolvedTarget) || 'my-project';
+      const starterPkg = {
+        name: projectName,
+        version: '0.1.0',
+        private: true,
+        description: 'Scaffolded with azcodr enterprise architecture template',
+        scripts: {
+          test: 'node --test',
+          'test:coverage': 'node --test --experimental-test-coverage',
+          lint: 'echo "No linter configured yet. Run /lets-build to configure toolchain."',
+          validate: 'bash .agents/skills/agentic-architect/scripts/validate_agentic_configs.sh'
+        }
+      };
+      fs.writeFileSync(pkgJsonPath, JSON.stringify(starterPkg, null, 2) + '\n', 'utf-8');
+    }
+  }
+
   // Ensure scripts are executable
   const inspectDir = dryRun ? resolvedTemplate : resolvedTarget;
   const scripts = makeScriptsExecutable(inspectDir, dryRun);
@@ -183,6 +239,23 @@ function copyTemplate(targetDir, templateDir = getTemplateDir(), options = {}) {
   return actions;
 }
 
+/**
+ * Detects whether targetDir is already inside an existing Git worktree.
+ */
+function isInsideGitWorkTree(targetDir) {
+  try {
+    const checkDir = fs.existsSync(targetDir) ? targetDir : path.dirname(targetDir);
+    const out = cp.execSync('git rev-parse --is-inside-work-tree', {
+      cwd: checkDir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf-8'
+    });
+    return out.trim() === 'true';
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Initializes a git repository in the target directory if not already inside one.
  */
@@ -193,12 +266,41 @@ function initGit(targetDir, options = {}) {
   const gitDir = path.join(targetDir, '.git');
   if (fs.existsSync(gitDir)) return false;
 
+  if (isInsideGitWorkTree(targetDir)) return false;
+
   if (dryRun) {
     return true;
   }
 
   try {
-    cp.execSync('git init -q', { cwd: targetDir, stdio: 'ignore' });
+    try {
+      cp.execSync('git init -b main -q', { cwd: targetDir, stdio: 'ignore' });
+    } catch {
+      cp.execSync('git init -q', { cwd: targetDir, stdio: 'ignore' });
+      try {
+        cp.execSync('git branch -m main', { cwd: targetDir, stdio: 'ignore' });
+      } catch {
+        // Non-critical if branch rename fails
+      }
+    }
+
+    try {
+      cp.execSync('git add -A', { cwd: targetDir, stdio: 'ignore' });
+      try {
+        cp.execSync('git commit -q -m "chore: initial scaffold from azcodr template"', {
+          cwd: targetDir,
+          stdio: 'ignore'
+        });
+      } catch {
+        cp.execSync('git -c user.name="azcodr" -c user.email="azcodr@local" commit -q -m "chore: initial scaffold from azcodr template"', {
+          cwd: targetDir,
+          stdio: 'ignore'
+        });
+      }
+    } catch {
+      // Non-critical if initial commit fails
+    }
+
     return true;
   } catch {
     return false;
@@ -242,6 +344,7 @@ module.exports = {
   ensureSymlink,
   isSameCaseInsensitiveFile,
   makeScriptsExecutable,
+  isInsideGitWorkTree,
   initGit,
   getTemplateDir,
   TEMPLATE_ITEMS

package/memory.md

@@ -17,273 +17,20 @@
 
 | ID | Title | Date | Status | Governing Rule / Skill |
 |---|---|---|---|---|
-| **ADR-001** | 100% Open-Source Tooling & Framework Mandate | 2026-09-16 | ACCEPTED | [`security_compliance.md`](./docs/rules/security_compliance.md), [`devops_ci_cd.md`](./docs/rules/devops_ci_cd.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_architecture.md`](./docs/rules/multitenancy_architecture.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_design.md`](./docs/rules/database_design.md), [`api_architecture.md`](./docs/rules/api_architecture.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) |
-| **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_design.md`](./docs/rules/database_design.md), [`frontend_architecture.md`](./docs/rules/frontend_architecture.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-016** | Elimination of Static Markdown Knowledge Graph | 2026-09-25 | ACCEPTED | [`clean_code.md`](./docs/rules/clean_code.md), [`agentic_configuration.md`](./docs/rules/agentic_configuration.md) |
-| **ADR-017** | Progressive Rules Consolidation (DDD & GoF Patterns) | 2026-09-25 | ACCEPTED | [`domain_driven_design.md`](./docs/rules/domain_driven_design.md), [`design_patterns.md`](./docs/rules/design_patterns.md) |
-| **ADR-018** | Elimination of Upstream Changes Ledger and Sync Tooling | 2026-09-25 | ACCEPTED | [`clean_code.md`](./docs/rules/clean_code.md), [`agentic_configuration.md`](./docs/rules/agentic_configuration.md) |
-| **ADR-019** | Evolutionary CQRS Spectrum & Strict YAGNI Tipping Points | 2026-09-26 | ACCEPTED | [`cqrs.md`](./docs/rules/cqrs.md), [`database_design.md`](./docs/rules/database_design.md) |
-| **ADR-020** | Universal YAGNI Gate Triad Architecture | 2026-09-26 | ACCEPTED | [`agentic_configuration.md`](./docs/rules/agentic_configuration.md), [`.agents/skills/agentic-architect/SKILL.md`](./.agents/skills/agentic-architect/SKILL.md) |
-| **ADR-021** | Language-Agnostic Core Rules Generalization & Toolchain Zero-Rule Policy | 2026-09-26 | ACCEPTED | [`type_safety.md`](./docs/rules/type_safety.md), [`frontend_architecture.md`](./docs/rules/frontend_architecture.md) |
-| **ADR-022** | Vendor-Agnostic Frontend Architecture & Library-as-a-Skill Anti-Pattern Defense | 2026-09-26 | ACCEPTED | [`frontend_architecture.md`](./docs/rules/frontend_architecture.md), [`agentic_configuration.md`](./docs/rules/agentic_configuration.md) |
-| **ADR-023** | Architectural Cohesion Consolidation (Synthesis of 28 Cohesive Domain Rules) | 2026-09-26 | ACCEPTED | All 28 rules in [`docs/rules/`](./docs/rules/) |
-| **ADR-024** | Outside-In Interaction Discovery vs. Inside-Out Invariants & Headless UI Testing | 2026-09-26 | ACCEPTED | [`frontend_architecture.md`](./docs/rules/frontend_architecture.md), [`test_driven_development.md`](./docs/rules/test_driven_development.md) |
-| **ADR-025** | Automated Markdown Link Integrity, Scaffolding Boundary Decoupling & Prepublish Quality Gates | 2026-09-26 | ACCEPTED | [`.agents/skills/agentic-architect/scripts/validate_agentic_configs.sh`](./.agents/skills/agentic-architect/scripts/validate_agentic_configs.sh), [`agentic_configuration.md`](./docs/rules/agentic_configuration.md) |
-| **ADR-026** | Multi-Harness Parity, Agentic Skill Taxonomy & Deterministic Governance Hardening | 2026-09-26 | ACCEPTED | [`agentic_configuration.md`](./docs/rules/agentic_configuration.md), [`agentic-architect`](./.agents/skills/agentic-architect/SKILL.md) |
-
+| *(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
 
-#### 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 architectural domains (PostgreSQL, Redis, Trivy, Semgrep, Gitleaks, OpenTelemetry, Vitest, Playwright, Radix UI).
-- **Enforced In:** Root [`AGENTS.md`](./AGENTS.md), [`security_compliance.md`](./docs/rules/security_compliance.md), [`devops_ci_cd.md`](./docs/rules/devops_ci_cd.md).
-
-#### 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 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
-- **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.
-- **Enforced In:** [`multitenancy_architecture.md`](./docs/rules/multitenancy_architecture.md).
-
-#### 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.
-- **Enforced In:** Root [`AGENTS.md`](./AGENTS.md), [`agentic_configuration.md`](./docs/rules/agentic_configuration.md).
-
-#### ADR-005: Universal Technology, Language, and Stack Agnosticism
-- **Date:** 2026-09-18 | **Status:** ACCEPTED
-- **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 & 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_design.md`](./docs/rules/database_design.md), [`api_architecture.md`](./docs/rules/api_architecture.md), [`ui_ux_architecture.md`](./docs/rules/ui_ux_architecture.md).
-
-#### 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).
-
-#### 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).
-
-#### 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).
-
-#### 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_design.md`](./docs/rules/database_design.md), [`frontend_architecture.md`](./docs/rules/frontend_architecture.md).
-
-#### 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).
-
-#### 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), [`frontend_architecture.md`](./docs/rules/frontend_architecture.md).
-
-#### ADR-014: Product Ownership, Backlog Prioritization Models, SMART Developer Tasks & INVEST Slicing
-- **Date:** 2026-09-21 | **Status:** ACCEPTED
-- **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).
-
-#### ADR-016: Elimination of Static Markdown Knowledge Graph in Favor of Code-as-Truth & Living Glossary
-- **Date:** 2026-09-25 | **Status:** ACCEPTED
-- **Context:** Template repositories often maintain static markdown files containing Mermaid diagrams, ERDs, and component topologies (`docs/knowledge/knowledge_graph.md`). In practice, these static artifacts suffer from rapid maintenance drift, violate the Problem-First mandate by pre-fabricating multi-tenant web backend models before the user defines their project, duplicate existing domain rules and memory records, and become stale tokens consumed on every context load.
-- **Decision:** Permanently delete `docs/knowledge/knowledge_graph.md`. Treat executable code, strict type definitions, and versioned database migrations as the sole source of truth for architectural topologies. Retain `docs/knowledge/ubiquitous_language.md` as the lightweight, living domain vocabulary contract.
-- **Enforced In:** [`AGENTS.md`](./AGENTS.md), [`clean_code.md`](./docs/rules/clean_code.md), [`agentic_configuration.md`](./docs/rules/agentic_configuration.md), [`memory.md`](./memory.md).
-
-#### ADR-017: Progressive Rules Consolidation (DDD & GoF Design Patterns)
-- **Date:** 2026-09-25 | **Status:** ACCEPTED
-- **Context:** Multiple domain rules exhibited redundant overlaps: `domain_expertise.md` duplicated strategic capability mapping and tactical aggregate invariants already governed by `domain_driven_design.md`, while `gof_design_patterns_reference.md` artificially fragmented design patterns into a separate satellite file from `design_patterns.md`. This fragmentation caused token bloat in `AGENTS.md` and scattered domain invariants.
-- **Decision:**
-  1. Merge business capability tiering (Core/Supporting/Generic) and the Aggregate Root Gatekeeper invariant example into [`domain_driven_design.md`](./docs/rules/domain_driven_design.md). Delete redundant `domain_expertise.md`.
-  2. Consolidate the 23 Gang of Four patterns catalog directly into [`design_patterns.md`](./docs/rules/design_patterns.md). Delete redundant `gof_design_patterns_reference.md`.
-  3. Streamline rule catalog across `AGENTS.md` and `README.md` to 45 lean, single-responsibility, non-overlapping rules.
-- **Enforced In:** [`AGENTS.md`](./AGENTS.md), [`README.md`](./README.md), [`domain_driven_design.md`](./docs/rules/domain_driven_design.md), [`design_patterns.md`](./docs/rules/design_patterns.md).
-
-#### ADR-018: Elimination of Upstream Changes Ledger and Upstream Sync Tooling
-- **Date:** 2026-09-25 | **Status:** ACCEPTED
-- **Context:** Maintaining a manual `changes.md` ledger duplicated state already captured across Git commit history and formal ADR records in `memory.md`. Furthermore, scaffolding `changes.md` into downstream derived projects contaminated them with meta-tooling baggage about the upstream template, violating Problem-First Architecture and Workspace Sovereignty. Accompanying CLI subcommands (`npx azcodr change`) and rule files (`upstream_synchronization.md`) added over 200 lines of accidental maintenance complexity.
-- **Decision:**
-  1. Permanently delete `changes.md` and retire `docs/rules/upstream_synchronization.md`.
-  2. Remove `changes.md` from scaffolded `TEMPLATE_ITEMS` and package manifests.
-  3. Purge `logChange` functions, types, and CLI subcommands, restoring `azcodr` CLI as a clean, single-purpose project bootstrapper.
-  4. Standardize exclusively on Git commits for historical revision logs and `memory.md` for architectural decision records.
-- **Enforced In:** [`AGENTS.md`](./AGENTS.md), [`README.md`](./README.md), `lib/scaffold.js`, `bin/azcodr.js`, [`memory.md`](./memory.md).
-
-#### ADR-019: CQRS (Command Query Responsibility Segregation) & YAGNI Defense
-- **Date:** 2026-09-25 | **Status:** ACCEPTED
-- **Context:** Command Query Responsibility Segregation (CQRS) is frequently adopted prematurely across whole applications, violating the YAGNI (You Aren't Gonna Need It) principle and introducing immense accidental complexity: eventual consistency lag, dual schema maintenance, projection drift, loss of ACID transactions, and distributed outbox pipelines. However, segregating read projections from write aggregates is essential for high-contention or high read/write asymmetry bounded contexts.
-- **Decision:**
-  1. Mandate the **YAGNI Defense**: Default to a Single Model / Single Database architecture for all applications and generic subdomains. CQRS is strictly forbidden as a global, top-level system architecture.
-  2. Define an **Evolutionary 4-Tier CQRS Spectrum**:
-     - *Level 0 (Method CQS)*: Commands mutate state; queries return values. Zero overhead; mandatory everywhere.
-     - *Level 1 (Segregated Handlers)*: Single database/schema. Command Handlers load Aggregates to enforce business invariants; Query Handlers bypass domain entities and query direct SQL projections into flat DTOs.
-     - *Level 2 (Segregated Read Models / Materialized Views)*: Single database. Synchronously updated read tables or materialized views for multi-table join optimization.
-     - *Level 3 (Polyglot Multi-Store CQRS)*: Dual databases (PostgreSQL write + Elasticsearch/Redis read) synchronized strictly via the Transactional Outbox Pattern and CDC. Permitted only when explicit empirical tipping points (Read:Write > 50:1, search engine requirement, or read starvation) are proven.
-  3. Prohibit common anti-patterns: Conflating CQRS with Event Sourcing, dual-write projections without an outbox, and exposing users to eventual consistency lag on their own mutations (enforce Read-Your-Own-Writes consistency via optimistic UI or version headers).
-- **Enforced In:** [`AGENTS.md`](./AGENTS.md), [`README.md`](./README.md), [`docs/rules/cqrs.md`](./docs/rules/cqrs.md), [`docs/rules/clean_code.md`](./docs/rules/clean_code.md), [`docs/rules/database_design.md`](./docs/rules/database_design.md), [`memory.md`](./memory.md).
-
-#### ADR-020: Universal YAGNI Gate Architecture, Tipping Points & Foundational Library Leverage
-- **Date:** 2026-09-25 | **Status:** ACCEPTED
-- **Context:** LLM coding agents suffer from a known statistical failure mode—"Instruction Creep" and "Eager Pattern Application"—where introducing an advanced architectural rule (e.g. distributed caching, state machines, feature flag servers, server-driven UI) prompts the agent to reflexively implement complex infrastructure across all tasks, even for 50-line CLIs or low-traffic prototypes. Conversely, developers sometimes misinterpret YAGNI as forbidding battle-tested libraries (shadcn/ui, Tailwind CSS, Zod, Lombok), leading to Not-Invented-Here (NIH) syndrome and massive hand-rolled accidental complexity.
-- **Decision:**
-  1. Codify the **YAGNI Gate Triad** across all architectural pattern rules and skills:
-     - *Part 1: The Simple Baseline (Day 1)*: Zero-overhead default (single DB before CQRS; relational indexes before Redis; simple enums before State Machines; standard React before Server-Driven UI; env vars before Flipt).
-     - *Part 2: The Anti-Triggers*: Explicit negative scenarios where the pattern is forbidden as premature over-engineering.
-     - *Part 3: The Empirical Tipping Point*: Measurable threshold (latency SLA, state count, asymmetry ratio, external scripts) required to graduate.
-  2. Clarify **Foundational Leverage vs. Speculative Over-Engineering**: Adopting standard open-source primitives (`shadcn/ui`, `Tailwind CSS`, `Zod`, `TanStack Query`, `Lombok`) to solve concrete present requirements with minimal code is YAGNI-compliant foundational leverage. YAGNI strictly attacks speculative custom code and premature multi-tier distributed architectures.
-  3. Retrofit explicit YAGNI Gates across high-risk rules: [`caching.md`](./docs/rules/caching.md), [`workflow_state_machines.md`](./docs/rules/workflow_state_machines.md), [`feature_flags.md`](./docs/rules/feature_flags.md), [`server_driven_ui.md`](./docs/rules/server_driven_ui.md), [`multitenancy_architecture.md`](./docs/rules/multitenancy_architecture.md).
-#### ADR-021: Language-Agnostic Core Rules Generalization (`type_safety.md` & `frontend_architecture.md`) and Deferred Project-Specific Specialization via `/lets-build`
-- **Date:** 2026-09-26 | **Status:** ACCEPTED
-- **Context:** Naming rules after specific technologies (`typescript.md`, `react.md`) in a foundational template workspace creates false tool/platform bias, violating Problem-First Architecture and confusing developers initializing Python, Java, Go, Rust, or C# systems. Furthermore, procedural package management rules (e.g. creating rules for `venv` vs `uv` vs `poetry`, or `maven` vs `gradle`) is a severe YAGNI violation and prompt anti-pattern, because LLMs already possess parametric toolchain knowledge and should derive execution commands from native workspace manifests (`pom.xml`, `pyproject.toml`).
-- **Decision:**
-  1. Generalize technology-specific rule filenames into polyglot architectural disciplines:
-     - Rename `typescript.md` ➔ [`type_safety.md`](./docs/rules/type_safety.md): Codifies sound type systems, branded nominal typing, and fail-fast boundary validation across TypeScript, Python (`mypy`/`pydantic`), Java (records), C# (nullable), Rust (newtype), and Go.
-     - Rename `react.md` ➔ [`frontend_architecture.md`](./docs/rules/frontend_architecture.md): Codifies headless accessible primitives, server-state cache synchronization and deduplication, declarative schema form validation, 5-tier state separation hierarchy, and design tokens across modern web clients.
-  2. Maintain a strict **Zero Toolchain Rule Policy**: Package managers (`uv`, `maven`, `gradle`, `composer`, `cargo`) shall never have dedicated rule files. Instead, `/lets-build` inquires into preferred toolchains during the interview, scaffolds native manifests, and stamps a concise 4-line execution contract into `AGENTS.md` (`## 2. Runtime & Core Scripts`).
-  3. Defer project-specific pruning to `/lets-build`: Projects without a frontend (e.g. headless Python backends or Rust CLIs) prune frontend rules during bootstrapping to ensure minimal token footprint.
-- **Enforced In:** [`AGENTS.md`](./AGENTS.md), [`README.md`](./README.md), [`docs/rules/type_safety.md`](./docs/rules/type_safety.md), [`docs/rules/frontend_architecture.md`](./docs/rules/frontend_architecture.md), [`.agents/skills/lets-build/SKILL.md`](./.agents/skills/lets-build/SKILL.md), [`memory.md`](./memory.md).
-
-#### ADR-022: Vendor-Agnostic Frontend Architecture & The "Library-as-a-Skill" Anti-Pattern Defense
-- **Date:** 2026-09-26 | **Status:** ACCEPTED
-- **Context:** Hardcoding a specific library (e.g. `TanStack Query`) as a mandatory requirement in `frontend_architecture.md` violates Problem-First Topology Alignment when building applications with Vue, SvelteKit, Angular, Solid, or React Server Components. Furthermore, a recurring temptation during domain analysis is to dynamically generate dedicated agent "skills" for every chosen library (e.g. `skills/react`, `skills/tanstack`, `skills/shadcn`, `skills/zustand`, `skills/testing-library`).
-- **Decision:**
-  1. **Vendor-Agnostic Architectural Invariants**: Decouple `frontend_architecture.md` from specific libraries. Codify universal architectural patterns (Headless Accessible Primitives, Server-State Cache Synchronization & Invalidation, Declarative Schema Form Validation, 5-Tier State Separation, and Token Symmetry) illustrated across frameworks (React, Vue, Svelte, Angular).
-  2. **Defend Against the "Library-as-a-Skill" Anti-Pattern**: Do NOT generate skills for standard commodity open-source libraries:
-     - *Prompt Bloat & Re-explanation Tax:* Skill descriptions are injected into every prompt. Adding 15 library skills floods the context window with parametric knowledge the LLM already knows.
-     - *Trigger Collision & Agent Paralysis:* A single UI prompt (e.g. "Create a profile form with data fetch") collides across multiple library skills (`react`, `tanstack`, `shadcn`, `testing-library`), causing wasteful subagent hops.
-     - *Passive Libraries vs. Active Workflows:* A skill is an active multi-step procedure (e.g. `/lets-build`, `product-analyst`, `compliance-audit`). A library is passive code whose usage is derived from code manifests (`package.json`, `components.json`), local component directories (`components/ui`), and CLI tools (`npx shadcn@latest add`).
-  3. **The 4-Layer Resolution Standard for Project Stack Knowledge**:
-     - *Layer 1 (Ground Truth Manifests):* `package.json`, `tsconfig.json`, `components.json`.
-     - *Layer 2 (Stack Contract in `AGENTS.md`):* 3–5 line declaration in project entrypoint stamped by `/lets-build`.
-     - *Layer 3 (Universal Domain Rules):* `frontend_architecture.md`, `test_driven_development.md`, `api_architecture.md`.
-     - *Layer 4 (Tool & CLI Execution):* Direct execution of package CLIs (`npx shadcn@latest add`) or MCP servers.
-- **Enforced In:** [`frontend_architecture.md`](./docs/rules/frontend_architecture.md), [`agentic_configuration.md`](./docs/rules/agentic_configuration.md), [`memory.md`](./memory.md).
-
-#### ADR-023: Architectural Cohesion Consolidation (Synthesis of 28 Cohesive Domain Rules)
-- **Date:** 2026-09-26 | **Status:** ACCEPTED
-- **Context:** The workspace rules had suffered from micro-rule fragmentation (45 separate files, with 15 files under 35 lines), creating high cognitive discovery overhead, duplicated directives, and split concerns across closely related domains (e.g. 5 UI files, 5 database files, 4 DevOps files, 3 multi-tenancy files, 3 API files).
-- **Decision:**
-  Consolidate fragmented micro-rules into 28 cohesive, single-responsibility domain rules:
-  1. **Frontend & UI**: Merge `accessibility.md` and `ui_navigation.md` into [`frontend_architecture.md`](./docs/rules/frontend_architecture.md). Retain [`ui_ux_architecture.md`](./docs/rules/ui_ux_architecture.md) for system design/layout and [`server_driven_ui.md`](./docs/rules/server_driven_ui.md) for backend schemas.
-  2. **API Architecture**: Merge `rest_api_conventions.md`, `advanced_api_patterns.md`, and `api_versioning.md` into [`api_architecture.md`](./docs/rules/api_architecture.md) (covering HTTP status codes, sync vs async 202 processing, `_actions`, idempotency keys, cursor pagination, OCC, and RFC 8594 lifecycle deprecation).
-  3. **Multi-Tenancy**: Merge `multitenancy_isolation.md`, `tenant_dynamic_schemas.md`, and `tenant_pluggable_logic.md` into [`multitenancy_architecture.md`](./docs/rules/multitenancy_architecture.md) (unifying context resolution, 4 isolation models, RLS, dynamic schemas, and pluggable logic with YAGNI gates).
-  4. **Database Architecture**: Consolidate into 2 atomic rules: [`database_design.md`](./docs/rules/database_design.md) (relational integrity, FKs, CHECKs, Canonical 6 Audit Fields, ACID transactions, Outbox pattern) and [`database_operations.md`](./docs/rules/database_operations.md) (zero-downtime expand-contract migrations, N+1 elimination, DataLoader, indexing, connection pooling, PITR).
-  5. **DevOps & CI/CD**: Merge `continuous_integration.md`, `continuous_deployment.md`, `container_infrastructure.md`, and `devsecops.md` into [`devops_ci_cd.md`](./docs/rules/devops_ci_cd.md).
-  6. **Security & Compliance**: Merge `application_security.md` and `compliance.md` into [`security_compliance.md`](./docs/rules/security_compliance.md).
-  7. **Testing**: Merge `test_isolation.md` into [`test_driven_development.md`](./docs/rules/test_driven_development.md).
-  8. **Agent Governance**: Merge `workspace_isolation.md`, `continuous_learning.md`, and `architecture_decision_records.md` into [`agentic_configuration.md`](./docs/rules/agentic_configuration.md).
-- **Consequences:** Eliminates 22 fragmented micro-files, reduces `AGENTS.md` table from 45 to 28 rows, and aligns every rule with True Single Responsibility.
-#### ADR-024: Outside-In Interaction Discovery vs. Inside-Out Domain Invariants, Headless UI Testing Architecture for AI Agents, and Universal Mermaid Diagram Standards
-- **Date:** 2026-09-26 | **Status:** ACCEPTED
-- **Context:**
-  1. The classic software dichotomy: "Does UI (CLI, GUI, API) dictate logic or vice versa?" Misunderstanding this relationship causes teams to either tightly couple business rules to UI frameworks (fat UI components) or build ivory-tower domain models detached from real customer journeys.
-  2. Autonomous AI agents operate in headless execution environments with zero visual eyesight. Standard engineering workflows frequently neglect UI testing or rely on fragile manual browser inspection that AI agents cannot execute or verify.
-  3. Workspace rules previously contained ad-hoc ASCII art diagrams that render inconsistently across markdown viewports, violate the user formatting directive, and cannot be dynamically rendered by modern Git platforms.
-- **Decision:**
-  1. **Outside-In Interaction Discovery vs. Inside-Out Domain Invariants Law**:
-     - *Phase 1 & 2 (Outside-In Discovery)*: UI, CLI, and client interaction models guide *what capabilities are needed* early. The customer journey discovers input command payloads, output presentation DTOs, and state requirements.
-     - *Phase 3 & 4 (Inside-Out Execution & Invariants)*: Domain entities enforce *how business rules operate*. Core business invariants are 100% agnostic to presentation frameworks, decoupled via Driving Ports (Use Cases).
-     - *Headless / Zero-UI Topologies*: In systems without a graphical interface (microservices, daemons, developer CLIs), the external API schema (OpenAPI, gRPC) or CLI command pipeline IS the UI. The identical Outside-In discovery law applies.
-  2. **The 4-Tier Headless UI Testing Pyramid for Autonomous AI Agents**:
-     - *Tier 1 (Accessible Component Tests)*: `@testing-library` + `user-event`. Query elements strictly by accessible ARIA roles (`getByRole`), ensuring semantic accessibility and banning brittle CSS selectors.
-     - *Tier 2 (Network Interception & Universal UI States)*: `MSW` (Mock Service Worker). Test all 4 universal UI states (Loading, Success, Error, Empty) deterministically in memory without live backends.
-     - *Tier 3 (Zero-Eyesight Automated Accessibility)*: `axe-core` (`vitest-axe` / `@axe-core/playwright`). Execute programmatic WCAG 2.2 AA assertions providing empirical pass/fail proof without visual eyesight.
-     - *Tier 4 (Headless E2E Smoke Tests)*: Headless Playwright CLI runs. Validate critical user journeys with traces, screenshots, and video recordings captured automatically upon test failure.
-  3. **Universal Mermaid Diagram Standard**:
-     - Standardize exclusively on GitHub-Flavored Markdown Mermaid diagrams (`flowchart`, `sequenceDiagram`, `classDiagram`) across all workspace rules, replacing all legacy ASCII box drawings.
-- **Enforced In:** [`docs/rules/frontend_architecture.md`](./docs/rules/frontend_architecture.md), [`docs/rules/test_driven_development.md`](./docs/rules/test_driven_development.md), [`docs/rules/api_architecture.md`](./docs/rules/api_architecture.md), all 28 domain rules in [`docs/rules/`](./docs/rules/), [`memory.md`](./memory.md).
-
-#### ADR-025: Automated Markdown Link Integrity, Scaffolding Boundary Decoupling & Prepublish Quality Gates
-- **Date:** 2026-09-26 | **Status:** ACCEPTED
-- **Context:**
-  1. As rules are refactored or consolidated, internal relative links across markdown documentation (`memory.md`, `README.md`, skills, rules) risk breaking silently without automated CI detection.
-  2. Scaffolding templates that reference repository-internal files (`lib/`, `bin/`) fail when evaluated in downstream isolated workspaces, violating Workspace Sovereignty.
-  3. Prepublish hooks omitted linting, risking publishing untested syntax.
-- **Decision:**
-  1. **Automated Cross-Reference & Link Integrity Enforcement**: Embed a deterministic link validator into `validate_agentic_configs.sh` that scans all markdown files across the workspace and asserts that 100% of internal links resolve to valid files on disk.
-  2. **Scaffolding Boundary Decoupling**: Sanitize all documentation and memory records to format internal packaging files (`lib/`, `bin/`) in code font rather than relative markdown links, ensuring scaffolded projects pass validation with zero broken links.
-  3. **Prepublish Quality Gate**: Expand `prepublishOnly` in `package.json` to enforce `npm run lint && npm run test:coverage && npm run validate` prior to distribution.
-- **Enforced In:** [`.agents/skills/agentic-architect/scripts/validate_agentic_configs.sh`](./.agents/skills/agentic-architect/scripts/validate_agentic_configs.sh), [`docs/rules/agentic_configuration.md`](./docs/rules/agentic_configuration.md), `package.json`, [`memory.md`](./memory.md).
-
-#### ADR-026: Multi-Harness Parity, Agentic Skill Taxonomy & Deterministic Governance Hardening
-- **Date:** 2026-09-26 | **Status:** ACCEPTED
-- **Context:**
-  1. The repository's harness parity previously only symlinked `CLAUDE.md` and `agents.md`, omitting Google Antigravity & Gemini CLI (`GEMINI.md`), Cursor (`.cursorrules`), and Windsurf (`.windsurfrules`), leading to configuration discovery divergence across different AI coding environments.
-  2. Root `AGENTS.md` omitted required top-level Workspace Identity, Mission, and Runtime Environment contracts mandated by `agentic_configuration.md`.
-  3. Skill subdirectories used non-standard terminology (`assets/` instead of `resources/` / `examples/`), and skills (`lets-build`, `relentless-questioner`) lacked explicit `## 5. Subdirectories & Progressive Resources` catalogs, leaving reference files orphaned.
-  4. The deterministic configuration validator omitted checks for closing frontmatter delimiters, negative boundary trigger phrasing in skill descriptions, and additional harness symlinks.
-- **Decision:**
-  1. **Omni-Harness Parity**: Expand harness parity to establish and assert symlinks across all 5 major AI coding harnesses: `CLAUDE.md`, `agents.md`, `GEMINI.md`, `.cursorrules`, and `.windsurfrules` pointing to root `AGENTS.md`. Update `lib/scaffold.js` to automatically stamp all 5 symlinks during scaffolding.
-  2. **Standardized Skill Folder Taxonomy**: Align skill subdirectory architecture strictly with standard Agent Skills and Antigravity specifications: `scripts/` (executable tools), `references/` (documentation), `resources/` (schemas/templates), and `examples/` (reference patterns), permanently retiring `assets/`.
-  3. **Progressive Resource Discoverability**: Ensure 100% of skills in `.agents/skills/` catalog all sub-resources and scripts under a standardized `## 5. Subdirectories & Progressive Resources` section with active links.
-  4. **Rigorous Configuration Validator Gates**: Enhance `validate_agentic_configs.sh` to validate all 5 harness symlinks, assert YAML frontmatter closure, verify negative boundary phrasing in skill descriptions, and handle `file://` URIs without false positives.
-  5. **Polyglot Skill Neutrality**: Purge hardcoded language-specific assumptions from `clean-code-refactor` and `compliance-audit`, generalizing to universal code health and type safety contracts.
-- **Enforced In:** [`AGENTS.md`](./AGENTS.md), [`docs/rules/agentic_configuration.md`](./docs/rules/agentic_configuration.md), [`.agents/skills/agentic-architect/SKILL.md`](./.agents/skills/agentic-architect/SKILL.md), [`.agents/skills/agentic-architect/scripts/validate_agentic_configs.sh`](./.agents/skills/agentic-architect/scripts/validate_agentic_configs.sh), `lib/scaffold.js`, `bin/azcodr.js`, [`memory.md`](./memory.md).
-
-#### ADR-027: Enterprise Agentic Hardening — Lifecycle Hooks, MCP Blueprints, Topology Tracking & Verification Smokes
-- **Date:** 2026-09-26 | **Status:** ACCEPTED
-- **Context:**
-  1. The 5-iteration relentless agentic audit identified missing out-of-the-box working schemas for Antigravity Lifecycle Hooks (`hooks.json`) and vendor-neutral Model Context Protocol servers (`mcp_config.json`), leaving users to manually divine JSON schemas for safety guards and MCP tools.
-  2. Scaffolding scripts (`bootstrap_workspace.sh`) created empty directory topologies without `.gitkeep`, causing Git to ignore empty leaf folders upon commit and silently dropping scaffolded architecture trees.
-  3. Projects scaffolded via `lets-build` lacked a deterministic starter for the required Phase 5 Boundary Verification Smoke Test (`scripts/smoke_test.sh`).
-  4. Configuration validation symlink checks strictly matched `"AGENTS.md"`, failing if a symlink used `./AGENTS.md` or absolute paths.
-- **Decision:**
-  1. **Lifecycle Hooks & MCP Schema Blueprints**: Provide `.agents/hooks.json.example` (configuring `PreToolUse`, `PostToolUse`, `Stop` with `"enabled": false`) and `.agents/mcp_config.json.example` (Stdio and SSE server blueprints) out-of-the-box in the template root for zero-guesswork integration.
-  2. **Topology Git Preservation**: Update `bootstrap_workspace.sh` with a `create_leaf` helper that automatically places `.gitkeep` inside empty scaffolded leaf directories across all topologies (extension, game engine, CLI, backend).
-  3. **Deterministic Boundary Smoke Test Generation**: Update `bootstrap_workspace.sh` to generate an executable starter `scripts/smoke_test.sh` upon workspace bootstrapping, satisfying Phase 5 verification gates out-of-the-box.
-  4. **Path-Tolerant Symlink & Fallback Validation**: Enhance `validate_agentic_configs.sh` with `is_valid_agents_target` and `is_valid_text_pointer` helpers accepting relative (`./AGENTS.md`) and absolute paths, while adding non-breaking validation for `.github/copilot-instructions.md`.
-- **Enforced In:** [`.agents/hooks.json.example`](./.agents/hooks.json.example), [`.agents/mcp_config.json.example`](./.agents/mcp_config.json.example), [`.agents/skills/lets-build/scripts/bootstrap_workspace.sh`](./.agents/skills/lets-build/scripts/bootstrap_workspace.sh), [`.agents/skills/agentic-architect/scripts/validate_agentic_configs.sh`](./.agents/skills/agentic-architect/scripts/validate_agentic_configs.sh), [`memory.md`](./memory.md).
-
-
+<!--
+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.
+-->

package/package.json

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