azcodr 1.2.1 → 1.2.2

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

@@ -12,7 +12,7 @@ Regardless of language, all bootstrapped projects must follow this high-level se
 <project-root>/
 ├── .agents/skills/                   # Specialized agentic workflows (carried from azcodr template)
 ├── docs/
-│   ├── knowledge/                    # System knowledge graph, issue log, DO's/DONT's
+│   ├── knowledge/                    # Domain knowledge & living ubiquitous language glossary
 │   └── rules/                        # 41 atomic single-responsibility domain rules
 ├── specs/                            # Canonical contract specifications
 │   ├── protobuf/                     # gRPC service definitions (*.proto)

package/AGENTS.md

@@ -59,8 +59,7 @@ To prevent context bloat and keep prompt overhead minimal, detailed engineering
 | **TDD Double Loop** | [docs/rules/test_driven_development.md](./docs/rules/test_driven_development.md) | Outside-In TDD (London School), collaborator discovery, mock ownership. |
 | **Test Coverage & Isolation** | [docs/rules/test_isolation.md](./docs/rules/test_isolation.md) | 100.00% full-stack coverage, status codes, transactional DB rollback. |
 | **Clean Code** | [docs/rules/clean_code.md](./docs/rules/clean_code.md) | Naming, small functions, CQS, SLAP, DRY, DbC, zero side-effects. |
-| **Design Patterns** | [docs/rules/design_patterns.md](./docs/rules/design_patterns.md) | Adapter, Factory, Facade, Strategy, and Result `<T, E>` pattern. |
-| **GoF Design Patterns** | [docs/rules/gof_design_patterns_reference.md](./docs/rules/gof_design_patterns_reference.md) | Complete reference of all 23 GoF patterns across OOP and functional paradigms. |
+| **Design Patterns** | [docs/rules/design_patterns.md](./docs/rules/design_patterns.md) | Adapter, Factory, Strategy, Result `<T, E>`, and complete 23 GoF catalog. |
 | **Type Safety** | [docs/rules/typescript.md](./docs/rules/typescript.md) | Compiler strictness, branded nominal types, type safety, static sound invariants. |
 | **ADRs** | [docs/rules/architecture_decision_records.md](./docs/rules/architecture_decision_records.md) | Authoring Lightweight Architectural Decision Records in `memory.md`. |
 | **Authentication** | [docs/rules/authentication.md](./docs/rules/authentication.md) | In-memory access tokens, refresh token rotation (RTR), WebAuthn passkeys. |
@@ -93,12 +92,11 @@ To prevent context bloat and keep prompt overhead minimal, detailed engineering
 | **React & Frontend** | [docs/rules/react.md](./docs/rules/react.md) | Modern React, shadcn/ui, TanStack Query, React Hook Form, and Zod validation. |
 | **Requirements Engineering** | [docs/rules/requirements_engineering.md](./docs/rules/requirements_engineering.md) | User stories vs requirements, 3 C's, INVEST vertical cake slicing, Gherkin. |
 | **Product Ownership** | [docs/rules/product_ownership.md](./docs/rules/product_ownership.md) | Product Backlog Management, OKRs, Kano/MoSCoW/RICE, Product Value, empiricism. |
-| **Domain-Driven Design** | [docs/rules/domain_driven_design.md](./docs/rules/domain_driven_design.md) | Ubiquitous Language, Bounded Contexts, Value Objects, Aggregates. |
+| **Domain-Driven Design** | [docs/rules/domain_driven_design.md](./docs/rules/domain_driven_design.md) | Ubiquitous Language, Bounded Contexts, Aggregates, Capability Mapping. |
 | **Workflow State Machines** | [docs/rules/workflow_state_machines.md](./docs/rules/workflow_state_machines.md) | Configurable workflows, in-aggregate invariant FSMs, transition guards & audit logs. |
 | **Cloud-Native 12-Factor** | [docs/rules/cloud_native.md](./docs/rules/cloud_native.md) | 12-Factor (2026 Edition), OpenTelemetry (OTel), stateless isolates. |
 | **Agentic Config & Skills** | [docs/rules/agentic_configuration.md](./docs/rules/agentic_configuration.md) | Progressive disclosure architecture, skill inquiry branches, refinement loop. |
 | **Project Management** | [docs/rules/project_management.md](./docs/rules/project_management.md) | Work-In-Progress limits (WIP = 1), SMART developer tasks, Definition of Done. |
-| **Domain Modeling** | [docs/rules/domain_expertise.md](./docs/rules/domain_expertise.md) | Business capabilities, Aggregate Root invariants, Ubiquitous Language. |
 | **Relentless Questioning** | [docs/rules/relentless_questioning.md](./docs/rules/relentless_questioning.md) | Dynamic context-aware interrogation loops, adaptive decision trees. |
 | **Workspace Isolation** | [docs/rules/workspace_isolation.md](./docs/rules/workspace_isolation.md) | Strict workspace sovereignty, zero global contamination, local ground truth. |
 | **Continuous Learning** | [docs/rules/continuous_learning.md](./docs/rules/continuous_learning.md) | Direct rule ingestion, root-cause analysis, dynamic invariant updates. |
@@ -116,5 +114,5 @@ To prevent context bloat and keep prompt overhead minimal, detailed engineering
   - [`lets-build`](.agents/skills/lets-build/SKILL.md): Conducting architecture interviews to finalize stack, frameworks, package managers, and bootstrapping projects.
   - [`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/`](./docs/knowledge/knowledge_graph.md) for system topologies and domain glossaries.
+- **Workspace Memory & Knowledge Hub:** Consult [`memory.md`](./memory.md) for ADRs, and [`docs/knowledge/ubiquitous_language.md`](./docs/knowledge/ubiquitous_language.md) for domain glossaries.
 - **Harness Parity & Symlinks:** `AGENTS.md`, `CLAUDE.md`, and `agents.md` must remain identical via filesystem symbolic links to eliminate configuration divergence across different agent harnesses.

package/README.md

@@ -37,9 +37,8 @@
 │       └── relentless-questioner/    # Context-aware dynamic interrogation loop
 ├── docs/
 │   ├── knowledge/                    # Institutional knowledge & domain contracts
-│   │   ├── knowledge_graph.md        # Visual topologies & fast-lookup matrices
 │   │   └── ubiquitous_language.md    # Living Ubiquitous Language glossary template
-│   └── rules/                        # 47 atomic single-responsibility domain rules
+│   └── rules/                        # 45 atomic single-responsibility domain rules
 ├── AGENTS.md                         # Lean root agentic configuration (< 120 lines)
 ├── CLAUDE.md -> AGENTS.md            # Filesystem symlink for harness parity
 ├── agents.md -> AGENTS.md            # Filesystem symlink for harness parity
@@ -52,15 +51,14 @@
 
 ## 📋 Progressive Disclosure Rules Catalog (`docs/rules/`)
 
-The architecture enforces 47 atomic, single-responsibility domain rules. Read on demand to prevent prompt context bloat:
+The architecture enforces 45 atomic, single-responsibility domain rules. Read on demand to prevent prompt context bloat:
 
 | Domain | Rule Reference File | Key Focus & Invariants |
 |---|---|---|
 | **TDD Double Loop** | [`test_driven_development.md`](./docs/rules/test_driven_development.md) | Uncle Bob's 3 Laws, nano-cycles, Ping-Pong pairing, outside-in double loop. |
 | **Test Coverage & Isolation** | [`test_isolation.md`](./docs/rules/test_isolation.md) | 100.00% full-stack coverage, status codes, transactional DB rollback. |
 | **Clean Code** | [`clean_code.md`](./docs/rules/clean_code.md) | 5 evolutionary tipping points, Refactor-Before-Add, CQS, SLAP, DRY, fitness functions. |
-| **Design Patterns** | [`design_patterns.md`](./docs/rules/design_patterns.md) | Adapter, Factory, Facade, Strategy, and Result `<T, E>` pattern. |
-| **GoF Design Patterns** | [`gof_design_patterns_reference.md`](./docs/rules/gof_design_patterns_reference.md) | Complete reference of all 23 GoF patterns across OOP and functional paradigms. |
+| **Design Patterns** | [`design_patterns.md`](./docs/rules/design_patterns.md) | Adapter, Factory, Strategy, Result `<T, E>`, and complete 23 GoF catalog. |
 | **Type Safety** | [`typescript.md`](./docs/rules/typescript.md) | Compiler strictness, branded nominal types, type safety, static sound invariants. |
 | **ADRs** | [`architecture_decision_records.md`](./docs/rules/architecture_decision_records.md) | Authoring Lightweight Architectural Decision Records in `memory.md`. |
 | **Authentication** | [`authentication.md`](./docs/rules/authentication.md) | In-memory access tokens, refresh token rotation (RTR), WebAuthn passkeys. |
@@ -93,12 +91,11 @@ The architecture enforces 47 atomic, single-responsibility domain rules. Read on
 | **React & Frontend** | [`react.md`](./docs/rules/react.md) | Modern React, shadcn/ui, TanStack Query, React Hook Form, and Zod validation. |
 | **Requirements Engineering** | [`requirements_engineering.md`](./docs/rules/requirements_engineering.md) | User stories vs requirements, 3 C's, INVEST vertical cake slicing, Gherkin. |
 | **Product Ownership** | [`product_ownership.md`](./docs/rules/product_ownership.md) | Product Backlog Management, OKRs, Kano/MoSCoW/RICE, Product Value, empiricism. |
-| **Domain-Driven Design** | [`domain_driven_design.md`](./docs/rules/domain_driven_design.md) | Problem Space vs Solution Space, Ubiquitous Language, Bounded Contexts, Aggregates. |
+| **Domain-Driven Design** | [`domain_driven_design.md`](./docs/rules/domain_driven_design.md) | Problem vs Solution Space, Ubiquitous Language, Aggregates, Capability Mapping. |
 | **Workflow State Machines** | [`workflow_state_machines.md`](./docs/rules/workflow_state_machines.md) | Configurable workflows, in-aggregate invariant FSMs, transition guards & audit logs. |
 | **Cloud-Native 12-Factor** | [`cloud_native.md`](./docs/rules/cloud_native.md) | 12-Factor (2026 Edition), OpenTelemetry (OTel), stateless isolates. |
 | **Agentic Config & Skills** | [`agentic_configuration.md`](./docs/rules/agentic_configuration.md) | Progressive disclosure architecture, skill inquiry branches, refinement loop. |
 | **Project Management** | [`project_management.md`](./docs/rules/project_management.md) | Work-In-Progress limits (WIP = 1), SMART developer tasks, Definition of Done. |
-| **Domain Modeling** | [`domain_expertise.md`](./docs/rules/domain_expertise.md) | Business capabilities, Aggregate Root invariants, Ubiquitous Language. |
 | **Relentless Questioning** | [`relentless_questioning.md`](./docs/rules/relentless_questioning.md) | Dynamic context-aware interrogation loops, adaptive decision trees. |
 | **Workspace Isolation** | [`workspace_isolation.md`](./docs/rules/workspace_isolation.md) | Strict workspace sovereignty, zero global contamination, local ground truth. |
 | **Continuous Learning** | [`continuous_learning.md`](./docs/rules/continuous_learning.md) | Direct 4-step rule ingestion, root-cause analysis, dynamic invariant updates. |
@@ -168,7 +165,6 @@ Once confirmed, the agent automatically executes:
 
 ## 🏛️ Workspace Memory & Knowledge Hub
 
-- 🗺️ **[System Knowledge Graph](./docs/knowledge/knowledge_graph.md)**: Visual subsystem topologies and entity-relationship models.
 - 📖 **[Living Ubiquitous Language Glossary](./docs/knowledge/ubiquitous_language.md)**: Authoritative domain vocabulary contract.
 - 📜 **[Lightweight ADR Ledger](./memory.md)**: Formal Architectural Decision Records and governing rules.
 - 📝 **[Upstream Changes Ledger](./changes.md)**: Record candidate improvements and generic patterns for the upstream azcodr template.

package/changes.md

@@ -60,3 +60,20 @@ When an AI agent or engineer discovers a generic architectural improvement, bug
   4. Codified Uncle Bob's Three Laws of TDD, banned batch-test dumps, and introduced the Incremental Nano-Cycle and Ping-Pong Pair Programming protocol.
 - **Domain Filter Verification:** Verified 100% generic; applicable across any language, stack, and project topology.
 
+### [2026-09-25] Permanent Removal of Static Markdown Knowledge Graph
+- **Category:** Architecture & Knowledge Hub
+- **Target File(s):** `docs/knowledge/knowledge_graph.md`, `AGENTS.md`, `memory.md`, `README.md`, `docs/rules/continuous_learning.md`
+- **Rationale:** Static markdown Mermaid diagrams and entity models in template repositories suffer from maintenance drift, duplicate state from code/migrations, violate Problem-First by assuming a multi-tenant web backend, and waste prompt token budget.
+- **Description:** Permanently eliminated `docs/knowledge/knowledge_graph.md`. Enforced code, type definitions, and versioned database migrations as the single source of truth for architectural topologies. Retained `docs/knowledge/ubiquitous_language.md` for lightweight living domain vocabulary contracts.
+- **Domain Filter Verification:** Verified 100% generic; purged of all speculative and duplicate static models.
+
+### [2026-09-25] Workspace Rules Consolidation & Redundancy Purge
+- **Category:** Rule & Knowledge Hub
+- **Target File(s):** `docs/rules/domain_driven_design.md`, `docs/rules/design_patterns.md`, `docs/rules/domain_expertise.md`, `docs/rules/gof_design_patterns_reference.md`, `AGENTS.md`, `README.md`, `memory.md`
+- **Rationale:** Eliminate duplicate and fragmented rules to optimize agent attention window, consolidate domain invariants, and uphold strict Single Responsibility across progressive disclosure documentation.
+- **Description:** 
+  1. Merged business capability mapping and Aggregate Root gatekeeper invariants from `domain_expertise.md` directly into `domain_driven_design.md`. Removed redundant `domain_expertise.md`.
+  2. Integrated the complete 23 Gang of Four patterns catalog from `gof_design_patterns_reference.md` directly into `design_patterns.md`. Removed redundant `gof_design_patterns_reference.md`.
+  3. Reduced active progressive disclosure rules from 47 to 45 while preserving 100% domain coverage.
+- **Domain Filter Verification:** Verified 100% generic; purged of all redundant files and circular links.
+

package/docs/rules/continuous_learning.md

@@ -26,5 +26,4 @@ Whenever an error, test failure, build friction, or architectural anti-pattern o
 ## 2. Institutional Memory Maintenance
 
 - **Lightweight ADR Ledger**: Major technical decisions and invariant shifts are logged in [`memory.md`](../../memory.md) linking directly to the governing rule or skill.
-- **System Knowledge Graph**: Keep [`docs/knowledge/knowledge_graph.md`](../knowledge/knowledge_graph.md) synchronized with new services, ports, or adapters to avoid repetitive token-expensive codebase discovery in future sessions.
 - **Living Glossary**: Keep [`docs/knowledge/ubiquitous_language.md`](../knowledge/ubiquitous_language.md) updated with canonical domain terminology and forbidden synonyms.

package/docs/rules/design_patterns.md

@@ -36,6 +36,56 @@ Domain services must return explicit Result types, compelling callers to handle
 
 ---
 
-## 3. GoF 23 Patterns Catalog
+## 3. Gang of Four (GoF) 23 Patterns Master Catalog
 
-For reference implementations of all 23 Gang of Four patterns across OOP and functional paradigms, consult [docs/rules/gof_design_patterns_reference.md](./gof_design_patterns_reference.md).
+### A. Creational Patterns (5 Patterns)
+1. **Factory Method**: Define an interface for creating an object, but let subclasses or factory functions decide which class to instantiate.
+   - *Use Case:* Tenant-specific payment gateway instantiation (`StripeAdapter` vs `PayPalAdapter`).
+2. **Abstract Factory**: Provide an interface for creating families of related or dependent objects without specifying concrete classes.
+   - *Use Case:* Multi-cloud storage factories creating matching `FileUploader`, `FileDownloader`, and `PresignedUrlGenerator` for S3, GCS, or MinIO.
+3. **Builder**: Separate the construction of a complex object from its representation, allowing the same construction process to create different representations.
+   - *Use Case:* Fluent query builders, complex report generators, or test data builders (`OrderBuilder.withItems(...).build()`).
+4. **Prototype**: Specify the kinds of objects to create using a prototypical instance, creating new objects by cloning this prototype.
+   - *Use Case:* Fast cloning of default tenant configuration templates without querying storage.
+5. **Singleton (DI-Scoped)**: Ensure a class has only one instance and provide a global point of access.
+   - *Rule:* Avoid global static singletons (causes test coupling). Enforce singleton lifecycle strictly through Dependency Injection (DI) containers.
+
+### B. Structural Patterns (7 Patterns)
+6. **Adapter (Mandatory)**: Convert the interface of a class into another interface clients expect.
+   - *Use Case:* Wrapping 3rd-party SDKs, storage drivers, and external network clients in application-owned interfaces. *Rule: Only mock types you own.*
+7. **Bridge**: Decouple an abstraction from its implementation so the two can vary independently.
+   - *Use Case:* Decoupling notification abstractions (`UrgentNotification`, `BatchNotification`) from delivery channels (`EmailChannel`, `SlackChannel`).
+8. **Composite**: Compose objects into tree structures to represent part-whole hierarchies.
+   - *Use Case:* Nested RBAC permission trees or hierarchical menu navigation systems.
+9. **Decorator**: Attach additional responsibilities to an object dynamically as a flexible alternative to subclassing.
+   - *Use Case:* Wrapping repository methods with distributed caching, OpenTelemetry tracing, or metrics logging.
+10. **Facade**: Provide a unified, high-level interface to a complex set of interfaces in a subsystem.
+    - *Use Case:* Checkout facade orchestrating inventory verification, payment processing, invoice generation, and email notification.
+11. **Flyweight**: Use sharing to support large numbers of fine-grained objects efficiently.
+    - *Use Case:* In-memory sharing of immutable tenant metadata and shared system role permission definitions.
+12. **Proxy**: Provide a surrogate or placeholder for another object to control access to it.
+    - *Use Case:* Lazy-loading database relations, virtual proxies for large assets, or tenant-scoped connection proxies.
+
+### C. Behavioral Patterns (11 Patterns)
+13. **Chain of Responsibility**: Pass requests along a chain of handlers until a handler processes it or the chain ends.
+    - *Use Case:* Inbound gateway middleware pipelines (Authentication ➔ TenantResolution ➔ RateLimiting ➔ Controller).
+14. **Command**: Encapsulate a request as an object, thereby letting you parameterize clients with different requests, queue or log requests, and support undo.
+    - *Use Case:* Asynchronous job queues, transactional audit commands, CQRS command handlers.
+15. **Interpreter**: Given a language, define a representation for its grammar along with an interpreter that uses the representation to interpret sentences.
+    - *Use Case:* Custom search filter parsers (`status:active AND tier:pro`) or rule engine expression evaluation.
+16. **Iterator**: Provide a way to access the elements of an aggregate object sequentially without exposing its underlying representation.
+    - *Use Case:* Async iterators streaming large database cursor result sets or reading multi-part upload chunks.
+17. **Mediator**: Define an object that encapsulates how a set of objects interact, preventing direct coupling between them.
+    - *Use Case:* In-memory event dispatcher mediating communication between decoupled domain services.
+18. **Memento**: Without violating encapsulation, capture and externalize an object's internal state so the object can be restored to this state later.
+    - *Use Case:* Audit trail snapshots recording `before` and `after` states for rollback capabilities.
+19. **Observer**: Define a one-to-many dependency between objects so that when one object changes state, all its dependents are notified automatically.
+    - *Use Case:* Domain Event buses (`UserRegisteredEvent`, `PaymentFailedEvent`) invoking multiple listeners.
+20. **State**: Allow an object to alter its behavior when its internal state changes, appearing as if it changed its class.
+    - *Use Case:* Subscription lifecycles (`TrialState` ➔ `ActiveState` ➔ `PastDueState` ➔ `CanceledState`) where allowed actions change dynamically.
+21. **Strategy**: Define a family of algorithms, encapsulate each one, and make them interchangeable at runtime.
+    - *Use Case:* Dynamic fee calculation, tenant-specific password complexity policies, or feature flag evaluation providers.
+22. **Template Method**: Define the skeleton of an algorithm in an operation, deferring some steps to subclasses.
+    - *Use Case:* Base ETL or data import pipelines with fixed steps (Extract ➔ Validate ➔ Transform ➔ Persist) where subclasses define validation.
+23. **Visitor**: Represent an operation to be performed on the elements of an object structure, defining a new operation without changing the classes of the elements.
+    - *Use Case:* Document export engines traversing an AST of content blocks to generate HTML, Markdown, or PDF.

package/docs/rules/domain_driven_design.md

@@ -27,6 +27,12 @@ Software engineering fails when teams jump directly into the **Solution Space**
 - **The Solution Space (The Accidents):** Concerns *how* the system is realized. Runtimes, programming languages (C, Rust, TS, Go, Java), and storage engines are **emergent outputs** derived strictly from Problem Space constraints.
 - **The Golden Hammer Anti-Pattern:** Selecting tools (e.g., "Let's use Next.js and PostgreSQL") before mapping problem constraints forces the domain to fit the tool, creating massive accidental complexity.
 
+### Strategic Subdomain & Capability Mapping
+Structure enterprise business capabilities into three distinct tiers:
+1. **Core Subdomain / Capabilities**: Proprietary value drivers and business differentiators (e.g. specialized workflow engines, dynamic pricing algorithms). Allocate 80% of architectural effort here.
+2. **Supporting Subdomain / Capabilities**: Business functions specific to the domain but not competitive differentiators (e.g. order tracking, invoice rendering).
+3. **Generic Subdomain / Capabilities**: Standard commoditized software (e.g. authentication, audit logging, email transport). Rely exclusively on standard open-source libraries.
+
 ---
 
 ## 2. Domain-Code Language Agreement
@@ -89,6 +95,24 @@ Acceptance criteria must be written strictly in Ubiquitous Language, serving as
 
 1. **Entities**: Objects defined by identity that persists across state changes (e.g. `User`, `Order`, `Invoice`).
 2. **Value Objects**: Immutable objects defined strictly by their attributes with no identity (e.g. `Money`, `DateRange`, `EmailAddress`).
-3. **Aggregates & Aggregate Roots**: Clusters of domain objects treated as a single transactional consistency boundary. All mutations must pass through explicit methods on the Aggregate Root.
+3. **Aggregates & Aggregate Roots**: Clusters of domain objects treated as a single transactional consistency boundary. All mutations must pass through explicit methods on the Aggregate Root that assert invariants before committing state:
+   - **Zero Anemic Domain Models**: Domain entities must encapsulate state and validation logic. Never expose public setters that allow outside code to corrupt business rules.
+   - **Aggregate Root Gatekeeper Pattern**:
+     ```typescript
+     export class OrderAggregate {
+       private constructor(private order: OrderState) {}
+
+       submit(): Result<void, DomainError> {
+         if (this.order.items.length === 0) {
+           return err(new DomainError('Cannot submit empty order'));
+         }
+         if (this.order.status !== 'DRAFT') {
+           return err(new DomainError('Order already submitted'));
+         }
+         this.order.status = 'SUBMITTED';
+         return ok(undefined);
+       }
+     }
+     ```
 4. **Anti-Corruption Layer (ACL)**: When integrating with third-party APIs or legacy systems that use different terminology, translate external payloads into the internal Ubiquitous Language at the boundary adapter before they enter the domain core.
 5. **Cross-Aggregate Coordination in Use Cases**: While an Aggregate Root guards its own internal invariants, business operations frequently span multiple aggregates (e.g. reserving an inventory item for an agreement). Application use cases or orchestrators must coordinate aggregate transitions atomically: asserting resource availability prior to state change, transitioning the constrained entity (e.g. `ALLOCATED`), and restoring state (`AVAILABLE`) upon cancellation, avoiding double-allocation race conditions without coupling aggregates directly.

package/memory.md

@@ -6,7 +6,6 @@
 
 ## 1. Quick Navigation & Knowledge Repositories
 
-- 🗺️ **[System Knowledge Graph](./docs/knowledge/knowledge_graph.md)**: Architectural subsystems, Mermaid topologies, entity relationships, and fast-lookup matrices.
 - 📖 **[Living Ubiquitous Language Glossary](./docs/knowledge/ubiquitous_language.md)**: Authoritative, single-name domain vocabulary contract.
 - 📜 **[Lightweight ADR Master Index](#adr-master-index)**: Summary of all architectural decisions and direct links to governing rules.
 - 📝 **[Upstream Changes Ledger](./changes.md)**: Ledger of candidate improvements and generic patterns for upstream azcodr.
@@ -33,6 +32,9 @@
 | **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-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) |
+
 
 ---
 
@@ -126,3 +128,18 @@
   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), [`continuous_learning.md`](./docs/rules/continuous_learning.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).
+

package/package.json

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

package/docs/knowledge/knowledge_graph.md

@@ -1,188 +0,0 @@
-# System Knowledge Graph & Architectural Topology
-
-> **Core Purpose:** High-density, token-efficient knowledge representation of the workspace architecture, data topologies, and subsystem boundaries, eliminating repetitive discovery prompts.
-
----
-
-## 1. Universal Hexagonal Architectural Subsystems
-
-```mermaid
-flowchart TD
-  subgraph Ingress["Client & Primary Ingress Adapters"]
-    UI["Multi-Platform Client (Web / Mobile / Desktop SDUI)"]
-    Gateway["Ingress Gateway / Envoy (REST / gRPC / SSE)"]
-    BrokerIn["Message Consumer (Kafka / NATS / RabbitMQ)"]
-  end
-
-  subgraph Core["Pure Invariant Domain Core (Hexagonal Ports)"]
-    direction TB
-    TenantContext["Multi-Tenant Context Resolver Port"]
-    AuthPort["Authentication & Identity Port"]
-    AuthzPort["Authorization & Policy Port"]
-    DomainServices["Domain Services & Aggregate Roots"]
-    RulePort["Dynamic Rule Engine Port (CEL / Wasm)"]
-    WorkflowPort["Workflow Orchestration Port (Temporal / BPMN)"]
-    OutboxPort["Transactional Outbox Port"]
-    CachePort["Cache & Distributed Lock Port"]
-    RepoPort["Universal Repository Port"]
-  end
-
-  subgraph Egress["Secondary / Egress Polyglot Adapters"]
-    Storage["Relational & NoSQL Storage (Postgres / MySQL / Cockroach / Mongo)"]
-    CacheStore["In-Memory Store (Redis / Valkey / Dragonfly / Memcached)"]
-    BrokerOut["Event Streaming (Kafka / NATS / RabbitMQ / CloudEvents)"]
-    AuthEngines["Policy-as-Code (OPA Rego / OpenFGA ReBAC / Cerbos)"]
-    SMTP["Transactional Email Gateway (SMTP / Providers)"]
-  end
-
-  UI --> Gateway
-  Gateway --> TenantContext
-  BrokerIn --> DomainServices
-  TenantContext --> AuthPort
-  AuthPort --> AuthzPort
-  AuthzPort --> DomainServices
-  DomainServices --> RulePort
-  DomainServices --> WorkflowPort
-  DomainServices --> OutboxPort
-  DomainServices --> CachePort
-  DomainServices --> RepoPort
-
-  RepoPort --> Storage
-  OutboxPort --> Storage
-  OutboxPort --> BrokerOut
-  CachePort --> CacheStore
-  AuthzPort --> AuthEngines
-  DomainServices --> SMTP
-```
-
----
-
-## 2. Multi-Tenant Data Isolation & Schema Graph
-
-```mermaid
-erDiagram
-  TENANT ||--o{ USER : "owns"
-  TENANT ||--o{ ROLE : "defines"
-  TENANT ||--o{ TENANT_SCHEMA : "configures"
-  TENANT ||--o{ TENANT_ENTITY : "defines"
-  TENANT_ENTITY ||--o{ TENANT_RECORD : "stores"
-  TENANT ||--o{ OUTBOX_EVENT : "emits"
-  TENANT ||--o{ AUDIT_LOG : "records"
-
-  TENANT {
-    uuid id PK
-    string slug UK
-    string name
-    string subscription_tier
-    string status
-    json theme_tokens
-    timestamptz created_at
-  }
-
-  USER {
-    uuid id PK
-    uuid tenant_id FK
-    string email UK
-    string password_hash
-    boolean mfa_enabled
-    timestamptz created_at
-  }
-
-  TENANT_SCHEMA {
-    uuid id PK
-    uuid tenant_id FK
-    string entity_name
-    json json_schema
-    int version
-  }
-
-  OUTBOX_EVENT {
-    uuid id PK
-    uuid tenant_id FK
-    string aggregate_type
-    string aggregate_id
-    string event_type
-    json payload
-    string status
-    timestamptz created_at
-  }
-```
-
----
-
-## 3. Subsystem Fast Lookup Index
-
-| Capability | Invariant Contract / Open Standard | Swappable Polyglot Adapters | Governing Rule |
-|---|---|---|---|
-| **Runtime & Language** | Hexagonal Core (Zero Deps) | Polyglot (Go, Rust, Python, Java, TypeScript) | [`clean_code.md`](../rules/clean_code.md) |
-| **Type Safety** | Sound static types & branded primitives | Rust, TypeScript, Go, Python (type hints) | [`typescript.md`](../rules/typescript.md) |
-| **Persistence / DAL** | Abstract Repository & Unit of Work | Atlas / Flyway migrations; SQL & NoSQL drivers | [`database_transactions.md`](../rules/database_transactions.md) |
-| **Tenant Isolation** | 4 Models (AST Interceptor, Schema, DB, Proxy) | SQL AST parser, RLS, multi-pool router, Envoy | [`multitenancy_isolation.md`](../rules/multitenancy_isolation.md) |
-| **Dynamic Schemas** | JSON Schema Draft 2020-12 | Polyglot validators (`valico`, `gojsonschema`, `ajv`) | [`tenant_dynamic_schemas.md`](../rules/tenant_dynamic_schemas.md) |
-| **Authentication** | OIDC, OAuth 2.1, Passkeys (WebAuthn) | PASETO, JWT with JWKS, SPIFFE/SPIRE mTLS | [`authentication.md`](../rules/authentication.md) |
-| **Authorization** | Policy-as-Code & ReBAC | OPA (Rego/Wasm), OpenFGA (Zanzibar), Cerbos | [`authorization.md`](../rules/authorization.md) |
-| **Pluggable Logic** | Common Expression Language (CEL) / Wasm | `cel-go`, `cel-rust`, Extism (Wasm plugins) | [`tenant_pluggable_logic.md`](../rules/tenant_pluggable_logic.md) |
-| **Workflows** | Durable Orchestration & Statecharts | Temporal.io SDKs, Camunda/Zeebe (BPMN 2.0) | [`tenant_pluggable_logic.md`](../rules/tenant_pluggable_logic.md) |
-| **Caching** | Abstract Cache Port with XFetch | Redis, Valkey, Dragonfly, Memcached, Local LRU | [`caching.md`](../rules/caching.md) |
-| **Feature Flags** | OpenFeature Standard | Flipt, Unleash, LaunchDarkly, GoFeatureFlag | [`feature_flags.md`](../rules/feature_flags.md) |
-| **Testing** | Outside-In TDD, BDD & Consumer Contracts | Cucumber/Gherkin, Pact, Schemathesis | [`test_driven_development.md`](../rules/test_driven_development.md) |
-| **Presentation / SDUI** | Declarative JSON SDUI + DTCG Tokens | Web (React/Vue/Svelte), Mobile (Flutter/Native) | [`server_driven_ui.md`](../rules/server_driven_ui.md) |
-| **Transactional Email** | Declarative Email Specs / MJML | SMTP Gateway, Mailpit (Local), SES/Sendgrid | [`transactional_email.md`](../rules/transactional_email.md) |
-| **Event Streaming** | CNCF CloudEvents v1.0.2 | Kafka, NATS JetStream, RabbitMQ, SQS | [`database_transactions.md`](../rules/database_transactions.md) |
-| **Observability** | OpenTelemetry OTLP standard | OTel Collector, Jaeger, Prometheus, OpenSearch | [`cloud_native.md`](../rules/cloud_native.md) |
-
----
-
-## 4. Agentic Skill Topology & Composability Matrix
-
-```mermaid
-flowchart TD
-  subgraph Inputs["Inception & Intent"]
-    Req["Stakeholder Feature Request / Mutation"]
-  end
-
-  subgraph Pattern1["Pattern 1: Sequential Pipeline Chaining (Workflows)"]
-    direction TB
-    SkillRQ["relentless-questioner"]
-    SkillPA["product-analyst"]
-    SkillTDD["test_driven_development"]
-    SkillRefactor["clean-code-refactor"]
-
-    SkillRQ -->|"Feature Alignment Spec (FAS)"| SkillPA
-    SkillPA -->|"INVEST Stories & Gherkin AC"| SkillTDD
-    SkillTDD -->|"Working Green Code"| SkillRefactor
-  end
-
-  subgraph Pattern2["Pattern 2: Dynamic Skill Stacking (Contextual Composition)"]
-    AgentCore["Primary Agent Session"]
-    SkillSec["compliance-audit"]
-    SkillArch["agentic-architect"]
-
-    AgentCore -.->|"Dynamic Load"| SkillSec
-    AgentCore -.->|"Dynamic Load"| SkillArch
-  end
-
-  subgraph Pattern3["Pattern 3: Multi-Agent Subagent Delegation (Division of Labor)"]
-    Coord["Coordinator Agent"]
-    SubA["Subagent A: Compliance Auditor"]
-    SubB["Subagent B: Code Refactorer"]
-
-    Coord -->|"Invoke Task"| SubA
-    Coord -->|"Invoke Task"| SubB
-    SubA -->|"Audit Findings"| Coord
-    SubB -->|"Refactored Units"| Coord
-  end
-
-  Req --> SkillRQ
-```
-
-### Many-to-Many Skill Cross-Matrix
-
-| Skill Name | Functional Specialty | Applicable Lifecycle Stages | Target Artifacts Produced |
-|---|---|---|---|
-| `relentless-questioner` | Context-aware ambiguity interrogation | Pre-Discovery, Pre-Planning | Feature Alignment Spec (FAS), Invariant List |
-| `product-analyst` | Requirements decomposition & Gherkin | Phase 1: Requirements | INVEST User Stories, Gherkin Scenarios |
-| `lets-build` | Technical infrastructure scaffolding | Initial Bootstrapping only | Package manifests, build configs, `/healthz` |
-| `clean-code-refactor` | Code smell eradication, GoF patterns | Phase 4: TDD Inner Loop | Decoupled classes, small functions (< 30 lines) |
-| `compliance-audit` | Security & compliance verification | Phase 1, Phase 5: DoD | Gitleaks, Semgrep, Trivy, OWASP audit logs |
-| `agentic-architect` | Agent configuration & skill governance | Continuous meta-refinement | Atomic `SKILL.md`, `AGENTS.md`, ADR records |

package/docs/rules/domain_expertise.md

@@ -1,42 +0,0 @@
-# Domain Expertise, Capability Mapping & Business Invariants
-
-> **Core Mandate:** Decompose business domains into distinct capability boundaries, enforce business invariants strictly within Aggregate Roots, and protect living Ubiquitous Language.
-
----
-
-## 1. Business Capability Mapping
-
-Structure enterprise business logic into three distinct capability tiers:
-1. **Core Capabilities**: Proprietary value drivers and differentiators (e.g. specialized tenant workflow engines, dynamic pricing algorithms). Allocate 80% of architectural effort here.
-2. **Supporting Capabilities**: Business functions specific to the domain but not competitive differentiators (e.g. order tracking, invoice rendering).
-3. **Generic Capabilities**: Standard commoditized software (e.g. authentication, audit logging, email transport). Rely exclusively on standard open-source libraries.
-
----
-
-## 2. Invariant Protection within Aggregate Roots
-
-- **Zero Anemic Domain Models**: Domain entities must encapsulate state and validation. Do not expose public setters that allow outside code to corrupt business rules.
-- **Aggregate Root Gatekeeper**: All mutations that modify entity state or related child entities must pass through explicit methods on the Aggregate Root that assert invariants before committing state:
-  ```typescript
-  export class OrderAggregate {
-    private constructor(private order: OrderState) {}
-
-    submit(): Result<void, DomainError> {
-      if (this.order.items.length === 0) {
-        return err(new DomainError('Cannot submit empty order'));
-      }
-      if (this.order.status !== 'DRAFT') {
-        return err(new DomainError('Order already submitted'));
-      }
-      this.order.status = 'SUBMITTED';
-      return ok(undefined);
-    }
-  }
-  ```
-
----
-
-## 3. Living Ubiquitous Language Dictionary
-
-- Maintain strict terminology discipline across models, database tables, API schemas, and frontend labels.
-- When domain experts or users establish a term, document it immediately and eliminate all competing synonyms across the codebase.

package/docs/rules/gof_design_patterns_reference.md

@@ -1,70 +0,0 @@
-# Gang of Four (GoF) Design Patterns — Universal Enterprise Reference
-
-> **Core Mandate:** Master catalog of all 23 Gang of Four design patterns mapped to real-world domain architectures across OOP and functional polyglot systems.
-
----
-
-## 1. Creational Patterns (5 Patterns)
-
-Creational patterns abstract the instantiation process, making systems independent of how objects are created and composed.
-
-1. **Factory Method**: Define an interface for creating an object, but let subclasses or factory functions decide which class to instantiate.
-   - *Use Case:* Tenant-specific payment gateway instantiation (`StripeAdapter` vs `PayPalAdapter`).
-2. **Abstract Factory**: Provide an interface for creating families of related or dependent objects without specifying concrete classes.
-   - *Use Case:* Multi-cloud storage factories creating matching `FileUploader`, `FileDownloader`, and `PresignedUrlGenerator` for S3, GCS, or MinIO.
-3. **Builder**: Separate the construction of a complex object from its representation, allowing the same construction process to create different representations.
-   - *Use Case:* Fluent query builders, complex report generators, or test data builders (`OrderBuilder.withItems(...).build()`).
-4. **Prototype**: Specify the kinds of objects to create using a prototypical instance, creating new objects by cloning this prototype.
-   - *Use Case:* Fast cloning of default tenant configuration templates without querying storage.
-5. **Singleton (DI-Scoped)**: Ensure a class has only one instance and provide a global point of access.
-   - *Rule:* Avoid global static singletons (causes test coupling). Enforce singleton lifecycle strictly through Dependency Injection (DI) containers.
-
----
-
-## 2. Structural Patterns (7 Patterns)
-
-Structural patterns deal with object composition and relationships, ensuring subsystems remain decoupled and flexible.
-
-6. **Adapter (Mandatory)**: Convert the interface of a class into another interface clients expect.
-   - *Use Case:* Wrapping 3rd-party SDKs, storage drivers, and external network clients in application-owned interfaces. *Rule: Only mock types you own.*
-7. **Bridge**: Decouple an abstraction from its implementation so the two can vary independently.
-   - *Use Case:* Decoupling notification abstractions (`UrgentNotification`, `BatchNotification`) from delivery channels (`EmailChannel`, `SlackChannel`).
-8. **Composite**: Compose objects into tree structures to represent part-whole hierarchies.
-   - *Use Case:* Nested RBAC permission trees or hierarchical menu navigation systems.
-9. **Decorator**: Attach additional responsibilities to an object dynamically as a flexible alternative to subclassing.
-   - *Use Case:* Wrapping repository methods with distributed caching, OpenTelemetry tracing, or metrics logging.
-10. **Facade**: Provide a unified, high-level interface to a complex set of interfaces in a subsystem.
-    - *Use Case:* Checkout facade orchestrating inventory verification, payment processing, invoice generation, and email notification.
-11. **Flyweight**: Use sharing to support large numbers of fine-grained objects efficiently.
-    - *Use Case:* In-memory sharing of immutable tenant metadata and shared system role permission definitions.
-12. **Proxy**: Provide a surrogate or placeholder for another object to control access to it.
-    - *Use Case:* Lazy-loading database relations, virtual proxies for large assets, or tenant-scoped connection proxies.
-
----
-
-## 3. Behavioral Patterns (11 Patterns)
-
-Behavioral patterns characterize the ways in which classes or objects interact and distribute responsibility.
-
-13. **Chain of Responsibility**: Pass requests along a chain of handlers until a handler processes it or the chain ends.
-    - *Use Case:* Inbound gateway middleware pipelines (Authentication ➔ TenantResolution ➔ RateLimiting ➔ Controller).
-14. **Command**: Encapsulate a request as an object, thereby letting you parameterize clients with different requests, queue or log requests, and support undo.
-    - *Use Case:* Asynchronous job queues, transactional audit commands, CQRS command handlers.
-15. **Interpreter**: Given a language, define a representation for its grammar along with an interpreter that uses the representation to interpret sentences.
-    - *Use Case:* Custom search filter parsers (`status:active AND tier:pro`) or rule engine expression evaluation.
-16. **Iterator**: Provide a way to access the elements of an aggregate object sequentially without exposing its underlying representation.
-    - *Use Case:* Async iterators streaming large database cursor result sets or reading multi-part upload chunks.
-17. **Mediator**: Define an object that encapsulates how a set of objects interact, preventing direct coupling between them.
-    - *Use Case:* In-memory event dispatcher mediating communication between decoupled domain services.
-18. **Memento**: Without violating encapsulation, capture and externalize an object's internal state so the object can be restored to this state later.
-    - *Use Case:* Audit trail snapshots recording `before` and `after` states for rollback capabilities.
-19. **Observer**: Define a one-to-many dependency between objects so that when one object changes state, all its dependents are notified automatically.
-    - *Use Case:* Domain Event buses (`UserRegisteredEvent`, `PaymentFailedEvent`) invoking multiple listeners.
-20. **State**: Allow an object to alter its behavior when its internal state changes, appearing as if it changed its class.
-    - *Use Case:* Subscription lifecycles (`TrialState` ➔ `ActiveState` ➔ `PastDueState` ➔ `CanceledState`) where allowed actions change dynamically.
-21. **Strategy**: Define a family of algorithms, encapsulate each one, and make them interchangeable at runtime.
-    - *Use Case:* Dynamic fee calculation, tenant-specific password complexity policies, or feature flag evaluation providers.
-22. **Template Method**: Define the skeleton of an algorithm in an operation, deferring some steps to subclasses.
-    - *Use Case:* Base ETL or data import pipelines with fixed steps (Extract ➔ Validate ➔ Transform ➔ Persist) where subclasses define validation.
-23. **Visitor**: Represent an operation to be performed on the elements of an object structure, defining a new operation without changing the classes of the elements.
-    - *Use Case:* Document export engines traversing an AST of content blocks to generate HTML, Markdown, or PDF.