feat(docs): Year 2500 Design Patterns Living Documentation Portal & Dynamic Canvas Engine

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: DesignPatterns Quality & Security Gate
 
 on:
   push:
-    branches: [main]
+    branches: [main, "feature/**"]
   pull_request:
     branches: [main]
   workflow_dispatch:
@@ -13,7 +13,7 @@ concurrency:
 
 jobs:
   syntax-and-compilation:
-    name: Python Architecture Compilation Check
+    name: Python Architecture Compilation & Lint
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -26,15 +26,31 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Compile all Python files
+      - name: Install Linting Tools
         run: |
-          python -m compileall -q .
-          echo "✅ All design pattern implementations compiled successfully without SyntaxErrors."
+          python -m pip install --upgrade pip
+          pip install ruff
 
-      - name: Basic Syntax & Import Linter
+      - name: Run Canonical Architecture Tests & Linter
         run: |
-          pip install ruff
-          ruff check . --select=E9,F63,F7,F82 --output-format=github
+          make test
+          make lint
+
+  docs-verification:
+    name: 15-Gate Living Docs Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Run 15-Gate Headless Verification Suite
+        run: |
+          chmod +x scripts/*.sh scripts/*.py
+          make docs-test
 
   security-scan:
     name: Gitleaks Secret Audit

.github/workflows/docs-publish.yml

@@ -0,0 +1,51 @@
+name: Docs Publish & Deploy
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build-and-verify:
+    name: Build & Verify Living Docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build & Run 15-Gate Headless Verification Suite
+        run: |
+          chmod +x scripts/*.sh scripts/*.py
+          make docs-build
+          make docs-test
+
+      - name: Upload Pages Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build-and-verify
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -61,6 +61,8 @@ pnpm-debug.log*
 .nuxt/
 dist/
 build/
+_site/
+.playwright-mcp/
 
 # --- Python & Environments (if scripts are run locally) ---
 __pycache__/

00 - Foundations/theory.md

@@ -246,7 +246,7 @@ classDiagram
 When you plug in a lamp, you don't wire it directly to the power plant. You plug it into a **wall outlet** (the abstraction). The lamp doesn't know or care if the electricity comes from solar, wind, or coal. And the power plant doesn't know or care if it's powering a lamp, a fridge, or a TV.
 
 #### The Rule
-Don't import concrete classes directly. Depend on interfaces/protocols. This is the foundation of **Dependency Injection** (Chapter 24).
+Don't import concrete classes directly. Depend on interfaces/protocols. This is the foundation of **Dependency Injection** (Chapter 25).
 
 #### Architecture: Before vs After
 
@@ -260,17 +260,17 @@ flowchart TB
     subgraph "✅ With DIP"
         D["OrderService"] -->|"depends on"| E["Database (Protocol)"]
         D -->|"depends on"| F["EmailSender (Protocol)"]
-        E <|.. G["MySQLDatabase"]
-        E <|.. H["PostgresDatabase"]
-        F <|.. I["SMTPEmailSender"]
-        F <|.. J["SendGridSender"]
+        E -.-> G["MySQLDatabase"]
+        E -.-> H["PostgresDatabase"]
+        F -.-> I["SMTPEmailSender"]
+        F -.-> J["SendGridSender"]
     end
 ```
 
 #### Which Patterns Embody DIP?
 | Pattern | How It Uses DIP |
 |---------|----------------|
-| **Dependency Injection** (Ch 24) | THE pattern for DIP |
+| **Dependency Injection** (Ch 25) | THE pattern for DIP |
 | **Abstract Factory** (Ch 03) | Client depends on factory interface, not concrete factories |
 | **Bridge** (Ch 07) | Abstraction depends on implementor interface |
 | **Repository** (Ch 23) | Business logic depends on repository interface, not DB |

01 - Singleton (Creational)/theory.md

@@ -33,7 +33,7 @@ That's a Singleton: **one instance, shared by everyone**.
 
 **Anti-signals (when NOT to use this pattern):**
 - You need multiple instances with different configs → use **Factory Method** (Ch 02)
-- You want to pass dependencies explicitly → use **Dependency Injection** (Ch 24)
+- You want to pass dependencies explicitly → use **Dependency Injection** (Ch 25)
 - You just need shared data, not a shared object → use a module-level variable
 - Testing requires isolated instances → Singleton makes mocking painful
 
@@ -296,7 +296,7 @@ graph LR
     S --> FW["11 Flyweight<br/>(flyweight factory is singleton)"]
     S --> FA["10 Facade<br/>(facade often singleton)"]
     ST["20 Strategy"] -.->|"Often confused"| S
-    DI["24 Dependency Injection"] -.->|"Better alternative"| S
+    DI["25 Dependency Injection"] -.->|"Better alternative"| S
 
     style DI fill:#51cf66,color:#fff
 ```
@@ -362,7 +362,7 @@ graph LR
 
 4. No! The subclass and parent share `cls._instance` if using a simple `__new__` override. The first one created wins. Use a metaclass with a per-class dict to fix this.
 
-5. **No!** Singleton guarantees ONE instance. You need THREE. Use **Factory Method** (Ch 02) or **Dependency Injection** (Ch 24) to create and manage multiple configured instances.
+5. **No!** Singleton guarantees ONE instance. You need THREE. Use **Factory Method** (Ch 02) or **Dependency Injection** (Ch 25) to create and manage multiple configured instances.
 
 6. Borg shares **state** (same `__dict__`) but creates **different objects** (`id()` differs). Singleton shares the **object itself** (same `id()`). Borg is useful when identity doesn't matter but shared state does.
 

02 - Factory Method (Creational)/theory.md

@@ -287,7 +287,7 @@ graph LR
     FM["02 Factory Method"] --> AF["03 Abstract Factory<br/>(FM is a simplified AF)"]
     FM --> TM["21 Template Method<br/>(FM is often called<br/>inside template method)"]
     FM --> PR["05 Prototype<br/>(alternative: clone instead<br/>of construct)"]
-    FM --> DI["24 Dependency Injection<br/>(DI generalizes the factory idea)"]
+    FM --> DI["25 Dependency Injection<br/>(DI generalizes the factory idea)"]
     S["01 Singleton"] -.->|"Factory can be<br/>a singleton"| FM
 ```
 

13 - Chain of Responsibility (Behavioral)/theory.md

@@ -121,8 +121,8 @@ flowchart LR
     subgraph "GoF Classic (Stop at First Handler)"
         R1["Request"] --> H1["Auth"]
         H1 -->|"Not my job"| H2["Cache"]
-        H2 -->|"I can do this!"| End["Return Response"]
-        End -.x H3["Database (Ignored)"]
+        H2 -->|"I can do this!"| RespEnd["Return Response"]
+        RespEnd -. "never reached" .-> H3["Database (Ignored)"]
     end
 
     subgraph "Modern Middleware (Pass Through All)"

26 - Event Sourcing & CQRS (Architectural)/theory.md

@@ -64,8 +64,8 @@ flowchart TB
 
     ES -.->|Async Publish Event| RDB
 
-    C -->|Send Command (POST)| Cmd
-    C -->|Ask Query (GET)| Qry
+    C -->|"Send Command (POST)"| Cmd
+    C -->|"Ask Query (GET)"| Qry
 ```
 
 ---

Makefile

@@ -0,0 +1,82 @@
+# ==============================================================================
+# Design Patterns Autonomous Command Deck Makefile
+# Unified automation for building, testing, linting, and serving
+# ==============================================================================
+
+.DEFAULT_GOAL := help
+SHELL := /usr/bin/env bash
+
+# Terminal Colors
+CYAN   := \033[0;36m
+GREEN  := \033[0;32m
+YELLOW := \033[1;33m
+RED    := \033[0;31m
+NC     := \033[0m
+
+.PHONY: help docs-build docs-serve docs-test test-boxes format-boxes test-links test-details test-badges test lint ci clean
+
+help: ## Show this interactive help menu
+	@printf "\n$(CYAN)🏛️ Design Patterns Architecture Bible — Autonomous Command Deck$(NC)\n\n"
+	@printf "Usage:\n  make $(CYAN)<target>$(NC)\n\nTargets:\n"
+	@awk 'BEGIN {FS = ":.*##"; printf ""} /^[a-zA-Z_-]+:.*?##/ { printf "  $(CYAN)%-18s$(NC) %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
+	@printf "\n"
+
+docs-build: ## Compile 28 chapters catalog and package static site into _site/
+	@printf "$(CYAN)📚 Compiling Design Patterns Living Documentation into _site/...$(NC)\n"
+	@bash scripts/build-docs.sh
+
+docs-serve: docs-build ## Serve living documentation portal on http://localhost:4000
+	@printf "$(CYAN)🚀 Serving Design Patterns Living Documentation on http://localhost:4000...$(NC)\n"
+	@if command -v python3 >/dev/null; then \
+		python3 -m http.server 4000 --directory _site; \
+	elif command -v npx >/dev/null; then \
+		npx -y serve _site -p 4000; \
+	else \
+		echo "$(RED)❌ Neither python3 nor npx found to serve static documentation.$(NC)"; \
+		exit 1; \
+	fi
+
+docs-test: ## Run 15-gate automated headless verification suite
+	@bash scripts/test-docs.sh
+
+test-boxes: ## Audit ASCII and Unicode box-drawing tables and cards alignment
+	@printf "$(CYAN)📐 Auditing ASCII/Unicode box-drawing alignment...$(NC)\n"
+	@python3 scripts/audit_ascii_boxes.py --check
+
+format-boxes: ## Realign and format all ASCII/Unicode boxes across the repository in place
+	@printf "$(CYAN)✨ Formatting and realigning all ASCII/Unicode boxes...$(NC)\n"
+	@python3 scripts/audit_ascii_boxes.py --fix
+
+test-links: ## Audit universal hyperlink integrity, SPA containment, and zero local path leaks
+	@printf "$(CYAN)🔗 Auditing hyperlink integrity & zero local path leaks...$(NC)\n"
+	@python3 scripts/audit_links_and_anchors.py
+
+test-details: ## Audit collapsible details and raw HTML block invariants
+	@printf "$(CYAN)📂 Auditing collapsible details and raw HTML block invariants...$(NC)\n"
+	@python3 scripts/audit_collapsible_elements.py
+
+test-badges: ## Audit monospace semantic badges and implementation labels
+	@printf "$(CYAN)🏷️ Auditing monospace semantic badges...$(NC)\n"
+	@python3 scripts/audit_monospace_badging.py
+
+test: test-boxes ## Run Python AST syntax and compilation checks across all patterns
+	@printf "$(CYAN)🧪 Compiling all Python design pattern implementations...$(NC)\n"
+	@python3 -m compileall -q .
+	@printf "$(GREEN)✅ All Python files compiled successfully without SyntaxErrors.$(NC)\n"
+
+lint: test-boxes ## Lint codebase with ruff and validate box alignment
+	@printf "$(CYAN)🔍 Running ruff linter...$(NC)\n"
+	@if command -v ruff >/dev/null; then \
+		ruff check . --select=E9,F63,F7,F82; \
+	else \
+		printf "$(YELLOW)⚠️ ruff not installed in local environment, skipping.$(NC)\n"; \
+	fi
+
+ci: test lint docs-test ## Run full continuous integration audit suite locally
+	@printf "\n$(GREEN)🎉 Full CI audit suite passed locally with 100%% compliance!$(NC)\n\n"
+
+clean: ## Clean build output directory and pycache
+	@printf "$(CYAN)🧹 Cleaning build artifacts...$(NC)\n"
+	@rm -rf _site/
+	@find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	@printf "$(GREEN)✅ Clean complete.$(NC)\n"

README.md

@@ -57,9 +57,10 @@ This repository is a comprehensive, notebook-style guide to software design patt
 *Beyond GoF — patterns that shape real-world systems at scale.*
 
 - [23 - Repository Pattern](./23%20-%20Repository%20Pattern%20%28Architectural%29/)
-- [24 - Dependency Injection](./24%20-%20Dependency%20Injection%20%28Architectural%29/)
-- [25 - Event Sourcing & CQRS](./25%20-%20Event%20Sourcing%20%26%20CQRS%20%28Architectural%29/)
-- [26 - Patterns in the Wild (Capstone)](./26%20-%20Patterns%20in%20the%20Wild%20%28Capstone%29/)
+- [24 - Unit of Work](./24%20-%20Unit%20of%20Work%20%28Architectural%29/)
+- [25 - Dependency Injection](./25%20-%20Dependency%20Injection%20%28Architectural%29/)
+- [26 - Event Sourcing & CQRS](./26%20-%20Event%20Sourcing%20%26%20CQRS%20%28Architectural%29/)
+- [27 - Patterns in the Wild (Capstone)](./27%20-%20Patterns%20in%20the%20Wild%20%28Capstone%29/)
 
 ---
 
@@ -92,8 +93,9 @@ This repository is a comprehensive, notebook-style guide to software design patt
 | Define a skeleton algorithm with customizable steps | Template Method | 21 |
 | Add operations to objects without modifying them | Visitor | 22 |
 | Abstract data persistence layer | Repository | 23 |
-| Decouple construction from usage of dependencies | Dependency Injection | 24 |
-| Track state changes as a sequence of events | Event Sourcing & CQRS | 25 |
+| Coordinate business transactions across repositories | Unit of Work | 24 |
+| Decouple construction from usage of dependencies | Dependency Injection | 25 |
+| Track state changes as a sequence of events | Event Sourcing & CQRS | 26 |
 
 ---
 
@@ -134,8 +136,9 @@ graph TB
 
     subgraph "Architectural"
         RP["23 Repository"]
-        DI["24 Dependency Injection"]
-        ES["25 Event Sourcing"]
+        UOW["24 Unit of Work"]
+        DI["25 Dependency Injection"]
+        ES["26 Event Sourcing"]
     end
 
     FM --> AF
@@ -161,6 +164,7 @@ graph TB
     VI --> IT
 
     RP --> FM
+    RP --> UOW
     DI --> STR
     DI --> FM
     ES --> OBS
@@ -175,7 +179,7 @@ graph TB
 2. **Go chapter-by-chapter** for a structured learning path, or **jump directly** to a pattern you need
 3. **Each chapter has a `theory.md`** — read this first for the conceptual deep-dive
 4. **Then explore `example_*.py` files** — runnable Python 3.14 code you can execute immediately
-5. **End with [Chapter 26 — Capstone](./26%20-%20Patterns%20in%20the%20Wild%20%28Capstone%29/)** for the decision matrix, anti-patterns, and interview playbook
+5. **End with [Chapter 27 — Capstone](./27%20-%20Patterns%20in%20the%20Wild%20%28Capstone%29/)** for the decision matrix, anti-patterns, and interview playbook
 
 ---
 

_internal/instructions.md

@@ -90,7 +90,7 @@ You MUST follow the **ReAct** (Reasoning + Acting) loop augmented with **Reflexi
 
 ```
 ┌─────────────────────────────────────────────────────┐
-│                   ReAct + Reflexion                  │
+│                   ReAct + Reflexion                 │
 │                                                     │
 │  1. THINK   → Reason about the current task.        │
 │               What do I know? What's missing?       │