azcodr 1.3.0 → 1.4.0

package/memory.md

@@ -17,23 +17,31 @@
 
 | ID | Title | Date | Status | Governing Rule / Skill |
 |---|---|---|---|---|
-| **ADR-001** | 100% Open-Source Tooling & Framework Mandate | 2026-09-16 | ACCEPTED | [`compliance.md`](./docs/rules/compliance.md), [`devsecops.md`](./docs/rules/devsecops.md) |
+| **ADR-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_isolation.md`](./docs/rules/multitenancy_isolation.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_integrity.md`](./docs/rules/database_integrity.md), [`rest_api_conventions.md`](./docs/rules/rest_api_conventions.md), [`ui_ux_architecture.md`](./docs/rules/ui_ux_architecture.md) |
+| **ADR-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), [`test_isolation.md`](./docs/rules/test_isolation.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_integrity.md`](./docs/rules/database_integrity.md), [`react.md`](./docs/rules/react.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), [`continuous_learning.md`](./docs/rules/continuous_learning.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), [`workspace_isolation.md`](./docs/rules/workspace_isolation.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) |
 
 
 ---
@@ -44,7 +52,7 @@
 - **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), [`compliance.md`](./docs/rules/compliance.md), [`devsecops.md`](./docs/rules/devsecops.md).
+- **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
@@ -56,7 +64,7 @@
 - **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_isolation.md`](./docs/rules/multitenancy_isolation.md).
+- **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
@@ -74,7 +82,7 @@
 - **Date:** 2026-09-18 | **Status:** ACCEPTED
 - **Context:** Prototypes often provide partial CRUD, leaving entities un-editable or undeletable. Exposing foreign keys as raw text inputs causes severe relational errors.
 - **Decision:** Every feature must implement complete lifecycle CRUD (Create, Read/Detail, Update/Transition, Delete/Archive) with 100.00% test coverage. Foreign keys must never be exposed as raw string inputs; they must be resolved via accessible relational dropdown selectors displaying contextual business metadata.
-- **Enforced In:** [`database_integrity.md`](./docs/rules/database_integrity.md), [`rest_api_conventions.md`](./docs/rules/rest_api_conventions.md), [`ui_ux_architecture.md`](./docs/rules/ui_ux_architecture.md).
+- **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
@@ -86,7 +94,7 @@
 - **Date:** 2026-09-18 | **Status:** ACCEPTED
 - **Context:** Writing production code before tests or domain understanding leads to brittle code, regressions, and "toy prototypes."
 - **Decision:** Enforce an immutable 5-Phase Agile Domain Lifecycle across all tasks (Requirements ➔ Domain Analysis ➔ Outer Acceptance RED ➔ Inner Unit TDD RED-GREEN-REFACTOR ➔ Outer GREEN & DoD). Writing production code without a failing test is strictly prohibited.
-- **Enforced In:** Root [`AGENTS.md`](./AGENTS.md), [`test_driven_development.md`](./docs/rules/test_driven_development.md), [`test_isolation.md`](./docs/rules/test_isolation.md).
+- **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
@@ -98,7 +106,7 @@
 - **Date:** 2026-09-19 | **Status:** ACCEPTED
 - **Context:** Inconsistent audit tracking risks SOC 2 / ISO 27001 non-compliance. Frontend `useEffect` fetch loops cause stale states and race conditions.
 - **Decision:** Every mutable stateful table must implement the Canonical 6 Total Audit Fields (`createdAt`, `createdBy`, `updatedAt`, `updatedBy`, `deletedAt`, `deletedBy`), with append-only ledgers omitting update/delete fields. Standardize frontend on TanStack Query, React Hook Form + Zod, and headless Radix primitives.
-- **Enforced In:** [`database_integrity.md`](./docs/rules/database_integrity.md), [`react.md`](./docs/rules/react.md).
+- **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
@@ -110,7 +118,7 @@
 - **Date:** 2026-09-20 | **Status:** ACCEPTED
 - **Context:** Conflating developer demo personas with production auth creates toy-like prototypes. Untriaged UI produces layout shifts and broken navigation.
 - **Decision:** Mandate the 7-Pillar Design Architecture Triage Gate before writing UI code; separate Enterprise Operator Workspace (`/`) from Consumer Portal (`/portal`); standardize on a persistent shell with 64px collapsible icon rail and bidirectional URL state sync; strictly isolate developer demo personas into a dev-only floating toolbar (`import.meta.env.DEV`).
-- **Enforced In:** [`ui_ux_architecture.md`](./docs/rules/ui_ux_architecture.md), [`authentication.md`](./docs/rules/authentication.md), [`ui_navigation.md`](./docs/rules/ui_navigation.md).
+- **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
@@ -132,7 +140,7 @@
 - **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), [`continuous_learning.md`](./docs/rules/continuous_learning.md), [`memory.md`](./memory.md).
+- **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
@@ -151,5 +159,131 @@
   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`](./lib/scaffold.js), [`bin/azcodr.js`](./bin/azcodr.js), [`memory.md`](./memory.md).
+- **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).
+
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azcodr",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Enterprise Architecture & Agentic Engineering Starter Template",
   "bin": {
     "azcodr": "bin/azcodr.js"
@@ -54,6 +54,6 @@
     "test:coverage": "node scripts/test_coverage.js",
     "lint": "node --check bin/azcodr.js lib/index.js lib/scaffold.js tests/cli.test.js tests/scaffold.test.js scripts/test_coverage.js",
     "validate": "bash .agents/skills/agentic-architect/scripts/validate_agentic_configs.sh",
-    "prepublishOnly": "npm run test:coverage && npm run validate"
+    "prepublishOnly": "npm run lint && npm run test:coverage && npm run validate"
   }
 }

package/docs/rules/accessibility.md

@@ -1,31 +0,0 @@
-# Accessibility (A11y) & WCAG 2.2 Standards
-
-> **Core Mandate:** Enforce WCAG 2.2 Level AA compliance, accessible Radix UI primitives, keyboard focus management, visible focus rings, and ARIA live regions across all user interfaces.
-
----
-
-## 1. Accessible UI Primitives & Radix UI
-
-- **Prohibited Native Alerts**: Strictly prohibit browser-native `window.confirm()` or `window.alert()`. Use accessible Radix UI dialogs (`@radix-ui/react-dialog`, `@radix-ui/react-alert-dialog`).
-- **Focus Management & Trapping**:
-  - Modal dialogs must trap keyboard focus within the dialog container while open.
-  - Closing a dialog must return keyboard focus deterministically to the triggering element.
-- **Visible Focus Indicators**: Never remove default outline rings (`outline: none`) without providing an explicit, high-contrast replacement (`focus-visible:ring-2 focus-visible:ring-offset-2`).
-
----
-
-## 2. Form & Feedback Accessibility
-
-- **Form Input Wiring**:
-  - Every form input must have an associated `<label>` using `htmlFor` or nested wrapping.
-  - Validation errors must be programmatically linked to their inputs via `aria-invalid="true"` and `aria-describedby="<error-message-id>"`.
-- **Dynamic Content & Status Feedback (ARIA Live Regions)**:
-  - Asynchronous notifications, toast alerts, and status updates must use `role="status"` or `aria-live="polite"` so screen readers announce changes without interrupting the user.
-  - Critical error alerts must use `role="alert"` or `aria-live="assertive"`.
-
----
-
-## 3. Visual & Contrast Baselines
-
-- **Color Contrast**: Maintain a minimum contrast ratio of 4.5:1 for normal text and 3:1 for large text / UI controls against their background.
-- **Semantic Landmark Markup**: Use semantic landmark elements (`<main>`, `<nav>`, `<aside>`, `<header>`, `<footer>`, `<section>`) rather than unsemantic `<div>` structures.

package/docs/rules/advanced_api_patterns.md

@@ -1,104 +0,0 @@
-# Advanced REST API Patterns & Capability Architecture
-
-> **Core Mandate:** Enrich API responses with capability metadata (Allowed Actions), ensure safe mutations via idempotency keys, enforce cursor pagination, and prevent race conditions with optimistic concurrency.
-
----
-
-## 1. Allowed Actions & Capability Metadata (HATEOAS-Lite)
-
-Clients must not duplicate server-side business and authorization rules to decide whether an action (edit, delete, approve, cancel) is permitted. **The server is the authoritative source of truth.**
-
-### Pattern: `_actions` and `_links` Envelope
-Every resource response must embed an `_actions` boolean map and optional `_links` hypermedia block indicating what the requesting caller is permitted to do based on their role, tenant boundaries, and the entity's current state:
-
-```json
-{
-  "id": "ord_9876",
-  "status": "SHIPPED",
-  "totalAmount": 149.99,
-  "currency": "USD",
-  "_actions": {
-    "canEdit": false,
-    "canCancel": false,
-    "canTrack": true,
-    "canRequestRefund": true
-  },
-  "_links": {
-    "self": { "href": "/api/v1/orders/ord_9876", "method": "GET" },
-    "track": { "href": "/api/v1/orders/ord_9876/tracking", "method": "GET" },
-    "refund": { "href": "/api/v1/orders/ord_9876/refunds", "method": "POST" }
-  }
-}
-```
-
-### UI Benefits
-- Frontend buttons and menus simply bind to `resource._actions.canDelete`.
-- When business logic evolves (e.g. orders over $1,000 require manager approval), only the backend logic changes—zero frontend redeployment required.
-
----
-
-## 2. Safe Mutations via Idempotency Keys (IETF Draft)
-
-To prevent duplicate processing (double charging, duplicate resource creation) caused by network retries:
-
-### Protocol
-- Clients generating mutating requests (`POST`, `PATCH`) must supply a unique `Idempotency-Key: <uuid-v4>` header.
-- **Server Lifecycle**:
-  1. Check distributed idempotency store for key `idemp:<tenantId>:<idempotencyKey>`.
-  2. If found with status `IN_FLIGHT`: return `409 Conflict` (`IDEMPOTENT_OPERATION_IN_PROGRESS`).
-  3. If found with status `COMPLETED`: return the cached status code, headers, and response payload without re-executing.
-  4. If not found: Acquire distributed lock, process mutation atomically, cache response with a 24-hour TTL, and release lock.
-
----
-
-## 3. High-Scale Keyset / Cursor-Based Pagination
-
-Never use offset pagination (`OFFSET 10000 LIMIT 20`) on large tables. Offsets degrade linearly (`O(N)`) and suffer from page-drift anomalies.
-
-### Specification
-- Query Parameters: `?cursor=<opaque_base64>&limit=20` (default limit 20, max 100).
-- Response Envelope:
-  ```json
-  {
-    "data": [...],
-    "pagination": {
-      "nextCursor": "ZXlKaWRI...==",
-      "hasMore": true,
-      "limit": 20
-    }
-  }
-  ```
-- **Agnostic Keyset Query Pattern**:
-  ```sql
-  SELECT * FROM orders
-  WHERE tenant_id = :tenantId
-    AND (created_at, id) < (:cursorCreatedAt, :cursorId)
-  ORDER BY created_at DESC, id DESC
-  LIMIT :limit + 1;
-  ```
-  If `results.length > limit`, slice the extra item and encode its cursor token for `nextCursor`.
-
----
-
-## 4. Optimistic Concurrency Control (OCC)
-
-Prevent lost-update anomalies during concurrent edits without pessimistic database row locking:
-
-### Protocol
-- Every mutable entity contains an incrementing integer `version` column.
-- Server returns the current version in the `ETag` response header: `ETag: W/"v4"`.
-- Clients submitting updates (`PUT`, `PATCH`) must include `If-Match: W/"v4"`.
-- **Conflict Handling**:
-  - Atomic update: `UPDATE table SET ..., version = version + 1 WHERE id = :id AND version = :expectedVersion`.
-  - If 0 rows updated: Return **`409 Conflict`** with error code `CONCURRENCY_CONFLICT` and the latest entity representation.
-
----
-
-## 5. Asynchronous Processing (`202 Accepted`)
-
-For tasks taking > 1.5 seconds (video rendering, large PDF export, batch imports):
-- Do NOT block synchronous client requests.
-- Dispatch task to an asynchronous worker queue or workflow engine.
-- Return **`202 Accepted`** immediately with:
-  - Header: `Location: /api/v1/tasks/:taskId`
-  - Body: `{ "taskId": "tsk_123", "status": "QUEUED", "pollIntervalMs": 2000 }`

package/docs/rules/api_versioning.md

@@ -1,113 +0,0 @@
-# API Versioning, SemVer Lifecycle & Swagger Multi-Version Architecture
-
-> **Core Mandate:** Enforce URI path major versioning (`/api/v1/`), SemVer 2.0.0 contract specifications, RFC 8594 Sunset/Deprecation headers, a 90-day retirement window, and multi-version Swagger UI exploration.
-
----
-
-## 1. Semantic Versioning (SemVer 2.0.0) in Web APIs
-
-Semantic Versioning maps to Web APIs according to contract stability and backward compatibility:
-
-$$\text{Version Format: } \mathbf{MAJOR.MINOR.PATCH}$$
-
-| SemVer Component | Scope & Impact | Exposure Channel | Example |
-|---|---|---|---|
-| **MAJOR** | Breaking, backwards-incompatible contract modifications. Requires client code/URL changes. | URI Path (`/api/v1/`, `/api/v2/`) & OpenAPI `info.version` | `2.0.0` |
-| **MINOR** | Backwards-compatible additive functionality, new endpoints, or optional attributes. | OpenAPI `info.version`, `API-Version` response header | `1.1.0` |
-| **PATCH** | Backwards-compatible bug fixes, performance optimizations, and documentation fixes. | OpenAPI `info.version`, release tags, telemetry metadata | `1.0.1` |
-
-> [!IMPORTANT]
-> **Why URI Path Exposes MAJOR Only:**
-> Exposing minor or patch versions in the URL path (e.g. `/api/v1.2.3/`) is a severe anti-pattern. Minor additions and bug fixes must not break client routing. Clients bind to the stable major version (`/api/v1/`) while consuming backward-compatible updates transparently.
-
----
-
-## 2. SemVer Trigger Matrix: What Triggers a Version Update?
-
-### A. MAJOR Bump (`1.x.x` ➔ `2.0.0`) — Breaking Changes
-A MAJOR version bump and a new URI prefix (`/api/v2/`) are triggered whenever existing clients would fail without code modifications:
-
-1. **Endpoint Alterations:**
-   - Deleting an existing endpoint or HTTP method.
-   - Renaming an existing URL path or subresource route.
-2. **Request Contract Breaking Changes:**
-   - Removing an existing request parameter (header, query, or body field).
-   - Renaming a request field.
-   - Changing the data type or format of a request field (e.g., string integer to number, date format change).
-   - Adding a new **mandatory / required** field to an existing request payload without a default value.
-   - Tightening input validation constraints (e.g., reducing max string length, narrowing allowed enum values).
-3. **Response Contract Breaking Changes:**
-   - Removing an existing field from a response payload.
-   - Changing the data type or structure of a response field (e.g., object converted to array, integer cents converted to float string).
-   - Changing the semantic business meaning of a field.
-4. **Behavioral & Protocol Breaking Changes:**
-   - Altering the standard HTTP status code for successful execution (e.g., changing `200 OK` to `204 No Content` or `201 Created`).
-   - Changing the error envelope schema away from RFC 7807 problem details.
-   - Changing authentication or authorization requirements (e.g. requiring a new OAuth scope or mTLS).
-
-### B. MINOR Bump (`1.0.x` ➔ `1.1.0`) — Additive, Backward-Compatible
-A MINOR version bump preserves the `/api/v1/` URI path and updates the contract specification:
-
-1. Adding completely new endpoints or resources (e.g., adding `POST /api/v1/documents/:id/signatures`).
-2. Adding new optional query parameters, headers, or request body fields.
-3. Adding new fields to response payloads (clients must follow Postel's Law / Tolerant Reader pattern).
-4. Adding new enum values to input requests if the service handles them gracefully without breaking old clients.
-5. Relaxing validation constraints (e.g., increasing maximum allowed file upload size or string length).
-6. Introducing deprecation notices on endpoints (via RFC 8594 headers) while maintaining functionality.
-
-### C. PATCH Bump (`1.0.0` ➔ `1.0.1`) — Bug Fixes & Non-Contractual Changes
-A PATCH version bump preserves contract schemas and updates release metadata:
-
-1. Internal bug fixes in domain logic that do not alter the contractual request/response schema or status codes.
-2. Performance enhancements, caching optimization, and database indexing.
-3. Security patches in dependencies and runtime frameworks.
-4. Clarifications, typo corrections, and formatting updates in OpenAPI descriptions.
-
----
-
-## 3. RFC 8594 Sunset & Deprecation Lifecycle
-
-When an older major version or endpoint is scheduled for retirement, inject standardized RFC 8594 headers:
-
-```http
-Deprecation: @1773619200
-Sunset: Wed, 16 Sep 2026 23:59:59 GMT
-Link: <https://api.domain.com/docs/migration/v2>; rel="sunset"
-```
-
-- **Mandatory 90-Day Migration Window:** Retain deprecated API versions for a minimum of 90 days following formal deprecation notification before decommissioning.
-- **Access Telemetry:** Track consumer traffic on deprecated routes via OpenTelemetry attributes (`api.deprecated=true`, `http.route`) to coordinate client migration.
-
----
-
-## 4. Swagger UI Multi-Version Selector Architecture
-
-Swagger UI must provide an interactive version dropdown selector enabling consumers and developers to inspect both active and upcoming API specifications.
-
-### Multi-Spec Configuration in Express / Swagger UI:
-```ts
-app.use(
-  '/docs',
-  swaggerUi.serve,
-  swaggerUi.setup(undefined, {
-    swaggerOptions: {
-      urls: [
-        { url: '/specs/v1/openapi.yaml', name: 'v1.0.0 (Current Stable)' },
-        { url: '/specs/v2/openapi.yaml', name: 'v2.0.0-draft (Next Major Preview)' }
-      ],
-      'urls.primaryName': 'v1.0.0 (Current Stable)'
-    }
-  })
-);
-```
-
-### Filesystem Specification Hierarchy:
-```
-specs/
-├── openapi/
-│   ├── v1/
-│   │   └── openapi.yaml
-│   └── v2/
-│       └── openapi.yaml
-```
-

package/docs/rules/application_security.md

@@ -1,23 +0,0 @@
-# Application Security & OWASP Top 10 Defenses
-
-> **Core Mandate:** Enforce proactive defenses against the OWASP Top 10 vulnerabilities, cryptographic rigor, and token-bucket rate limiting across all layers.
-
----
-
-## 1. OWASP Top 10 Defenses
-
-- **A01: Broken Access Control**: Verify permissions server-side on every request using Policy Enforcement Points (PEPs). Enforce immutable multi-tenancy data isolation (AST interceptors, database RLS, or schema namespaces).
-- **A02: Cryptographic Failures**: Passwords must be hashed using **Argon2id** with memory-hard parameters. Encrypt sensitive data at rest using authenticated ciphers (**AES-256-GCM** or **ChaCha20-Poly1305**).
-- **A03: Injection (SQL / NoSQL / Command)**: Strictly prohibit raw query string interpolation or dynamic execution. All database interactions must use parameterized prepared statements.
-- **A07: Identification and Authentication Failures**: Enforce rate limiting on auth endpoints, FIDO2/WebAuthn passkeys, and Refresh Token Rotation (RTR) with family invalidation on replay detection.
-- **A10: Server-Side Request Forgery (SSRF)**: Validate and restrict outbound network requests to an explicit allowlist of domains. Block requests targeting RFC 1918 private IP ranges, loopback addresses (`127.0.0.1`), and cloud metadata endpoints (`169.254.169.254`).
-
----
-
-## 2. Distributed API Rate Limiting
-
-- Utilize token-bucket or sliding-window rate limiters backed by a distributed in-memory cache port.
-- Enforce tiered rate limits:
-  - Authentication routes: Max 5 requests / minute per IP.
-  - Standard API routes: Max 100 requests / minute per tenant/user.
-- Return **`429 Too Many Requests`** with standard `Retry-After` and `RateLimit-*` IETF headers when limits are exceeded.

package/docs/rules/architecture_decision_records.md

@@ -1,42 +0,0 @@
-# Architecture Decision Records (ADR)
-
-> **Core Mandate:** Log all technical, architectural, and operational trade-offs in `memory.md` using the standardized Lightweight ADR format.
-
----
-
-## 1. When to Author an ADR
-
-An Architectural Decision Record must be authored whenever a team member or agent:
-- Introduces or removes an external dependency or library.
-- Modifies database schema architecture, transaction boundaries, or migration strategies.
-- Selects an architectural pattern (e.g. Server-Driven UI, Event-Driven Outbox, OpenFeature).
-- Defines security boundaries, cryptographic standards, or compliance exceptions.
-
----
-
-## 2. Lightweight ADR Format
-
-Log decisions in `memory.md` adhering to this structure:
-
-```markdown
-### ADR-[Number]: [Concise Title]
-
-- **Date:** [YYYY-MM-DD]
-- **Status:** [PROPOSED | ACCEPTED | SUPERSEDED]
-
-#### 1. Context & Problem Statement
-What business requirement, technical bottleneck, or security mandate necessitated this architectural decision?
-
-#### 2. Decision Drivers
-- [Driver 1: e.g. Zero-downtime database deployment]
-- [Driver 2: e.g. SOC 2 Type II tamper-evident logging compliance]
-
-#### 3. Considered Options
-- **Option A:** [Description and evaluation]
-- **Option B:** [Description and evaluation]
-
-#### 4. Decision Outcome & Consequences
-- **Chosen Option:** [Selected approach and core rationale]
-- **Positive Consequences:** [What improves]
-- **Negative Consequences / Trade-offs:** [What operational or code overhead is accepted]
-```

package/docs/rules/compliance.md

@@ -1,25 +0,0 @@
-# Regulatory Compliance: SOC 2, ISO 27001 & GDPR
-
-> **Core Mandate:** Enforce SOC 2 Type II Trust Services Criteria, ISO/IEC 27001 ISMS technical controls, and GDPR data subject privacy rights using open-source architectures.
-
----
-
-## 1. SOC 2 Type II Trust Services Criteria
-
-- **Access Controls (CC6.1)**: Enforce least-privilege RBAC/ABAC on all API endpoints. System-defined roles must be protected from unauthorized mutation.
-- **Tamper-Evident Audit Trails (CC7.2)**:
-  - All state mutations must create write-only, immutable audit log records:
-    `{ timestamp, actorId, tenantId, action, entityType, entityId, ipAddress, userAgent, changes: { before, after } }`.
-  - Audit logs must be retained for at least 365 days in append-only storage.
-
----
-
-## 2. ISO/IEC 27001 ISMS Technical Controls
-
-- **Annex A Cryptographic Controls (A.10.1)**: Enforce TLS 1.3 for data in transit and AES-256-GCM for sensitive data at rest. Passwords must be hashed using Argon2id or bcrypt.
-
----
-
-## 3. GDPR Data Subject Rights
-
-- **Right to Erasure (Article 17)**: Deleting a tenant or user must cascade delete or pseudonymize all associated personal identifiable information (PII) across active databases and backups.