@moon791017/neo-skills 1.1.7 → 1.1.8

package/README.md

@@ -11,7 +11,7 @@
 
 目前專案提供：
 
-- `skills/`：22 個內建專家技能。
+- `skills/`：23 個內建專家技能。
 - `bin/install-skills.js`：同步技能到 Antigravity CLI 全域技能目錄。
 - `bin/install-system-instructions.js`：把系統提示詞安裝到 Claude Code、Copilot CLI、Codex 或 Antigravity 的指導檔。
 - `scripts/check-skills-syntax.py`：非互動式技能結構驗證工具。
@@ -41,6 +41,7 @@
 | DevOps | `neo-azure-pipelines` | 建立、審查、除錯或現代化 Azure Pipelines YAML，尤其是 .NET build、Azure App Service 或 IIS 部署。 |
 | 需求釐清 | `neo-clarification` | 將模糊、情緒化、片段式、截圖式需求轉成規格、驗收條件或釐清問題。 |
 | Code Review | `neo-code-review` | 進行程式碼審查、PR/diff review、bug 風險掃描、安全性、效能或可維護性檢查。 |
+| 系統架構 | `neo-clean-architecture` | 設計、實作、審查或重構符合 Clean Architecture 原則的系統，劃分層級並排除特定技術依賴。 |
 | C# | `neo-csharp` | 撰寫、審查、除錯或現代化 C#/.NET 程式碼，包含語言版本、NRT、records、pattern matching 與 async。 |
 | C# | `neo-csharp-interface-generator` | 從 C# class 產生或更新 interface，並安全建立、追加或替換 interface block。 |
 | .NET | `neo-dotnet` | 廣泛 .NET 問題或尚未確定子領域時，先偵測 SDK/project shape 並導向合適技能。 |
@@ -147,6 +148,7 @@ npx -p @moon791017/neo-skills install-system-instructions \
 | 設計 Azure Pipelines CI/CD | `neo-azure-pipelines` | `幫我建立 .NET 專案的 Azure Pipelines CI` |
 | 審查目前變更 | `neo-code-review` | `請 review 目前 git diff` |
 | 釐清模糊需求 | `neo-clarification` | `把這些零散需求整理成規格與待確認問題` |
+| 設計乾淨架構 | `neo-clean-architecture` | `幫我用 Clean Architecture 設計訂單管理模組` |
 | 寫 TypeScript 型別 | `neo-typescript` | `幫我設計這個 API response 的泛型型別` |
 | 建 Vue 3 元件 | `neo-vue` | `幫我重構這個 SFC，避免響應式踩坑` |
 | 改善 AI 開發流程 | `neo-agent-harness` | `評估這個專案讓 coding agent 協作的可靠度` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moon791017/neo-skills",
-  "version": "1.1.7",
+  "version": "1.1.8",
   "type": "module",
   "description": "Neo Skills: A Universal AI Agent Skills Extension",
   "homepage": "https://neo-blog-iota.vercel.app/",

package/skills/neo-clean-architecture/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: neo-clean-architecture
+description: >
+  Use this skill when the user wants to design, implement, review, or refactor software systems conforming to Clean Architecture principles.
+  It structures code into Domain, Application, Infrastructure, and Presentation/API layers, enforcing inward-only dependencies.
+  It advocates rich domain models, CQRS, and the Result pattern, operating on technology-neutral concepts without database or framework bindings.
+metadata:
+  pattern: reviewer-generator
+  domain: architecture
+---
+
+# Clean Architecture
+
+Design and review software systems using Clean Architecture. The core objective is separating concerns based on their rate of change, directing all source code dependencies inward toward the Domain core.
+
+## Gotchas
+* **Anemic Models**: Entities that are mere data containers (only getters/setters) leak business logic. Entities must protect their invariants. State changes must go through explicit, business-oriented methods.
+* **Pointless Value Objects**: Avoid wrapping primitives (e.g., string, number) unless they encapsulate validation (e.g., email format) or behavior (e.g., auto-slug generation).
+* **Deep Object Graphs**: Do not nest full entities for associations. Loading a parent entity will trigger database performance issues. Reference other aggregates using IDs instead.
+* **Dependency Leakage**: Repository interfaces must reside in the Application layer, with implementations in Infrastructure. Never return query streams (e.g., `IQueryable`) to Application, as it leaks database concerns.
+* **Exception Control Flow**: Do not throw runtime exceptions for expected business failures (e.g., duplicate title, user not found). Use the Result pattern for flow control.
+
+---
+
+## Workflow Checklist
+
+Progress:
+- [ ] Step 1: Analyze Core & Boundaries (See `references/design_principles.md`).
+- [ ] Step 2: Design Domain Layer (Build entities and value objects; protect invariants).
+- [ ] Step 3: Design Application Layer (Define use case handlers, CQRS inputs, and repository interfaces).
+- [ ] Step 4: Implement Outer Layers (Implement database mapping, external services, and API controllers).
+- [ ] Step 5: Audit Architecture Health (Use `assets/review_checklist.md` to scan code).
+
+---
+
+## Detailed Guidelines
+
+### Step 1 — Analyze Core & Boundaries
+1. Categorize business rules:
+   - Domain Layer: Core rules that would exist even without a computer system.
+   - Application Layer: System orchestration, workflows, and protocols.
+   - Outer Layers (Infrastructure/Presentation): Delivery mechanisms and persistence details.
+2. Read [design_principles.md](references/design_principles.md) for architectural details.
+
+### Step 2 — Design Domain Layer
+1. Entities: Keep setters private or read-only.
+2. Domain Methods: Expose semantic operations (e.g., `updateContent()`, `addTag()`) that validate rules inside the entity.
+3. Associations: Keep aggregates decoupled by referencing other aggregate roots via ID only.
+
+### Step 3 — Design Application Layer
+1. Separate write operations (Commands) from read operations (Queries) using **CQRS**.
+2. Define technology-neutral interfaces (e.g., `IUserRepository`), keeping database or network specifics out of Application.
+3. Wrap use case outcomes in a **Result** type containing success/failure status, value, error type, and message. Refer to [layer_specifications.md](references/layer_specifications.md) for concepts mapping.
+
+### Step 4 — Implement Infrastructure & Presentation
+1. **Infrastructure**: Implement interfaces defined in Application. Configure ORM/database mappings, value conversions, and call external services.
+2. **Presentation/API**: Handle transmission protocols (e.g., HTTP, gRPC). Map request payload to Command/Query, dispatch it to Application, and translate the Result into appropriate responses (e.g., HTTP 200, 201, 400, 404, 409).
+
+---
+
+## Output Templates
+
+### 1. Architecture Blueprint Template
+```markdown
+# [System Name] Clean Architecture Blueprint
+
+## 1. Domain Layer
+* **Entities & Aggregate Roots**:
+  - `EntityName` (ID-association explanation)
+* **Value Objects**:
+  - `ValueObjectName` (Validation and behavior description)
+
+## 2. Application Layer
+* **Use Cases (CQRS / Handlers)**:
+  - `CreateSomethingCommand` & Handler
+  - `GetSomethingQuery` & Handler
+* **External Interfaces (Gateways / Repositories)**:
+  - `ISomethingRepository` (Interface methods)
+
+## 3. Infrastructure Layer
+* **Persistence Configurations**:
+  - `SomethingRepository` implementation notes
+  - Value Object persistence mapping rules
+
+## 4. Presentation / API Layer
+* **Contracts (Request/Response)**:
+  - `CreateSomethingRequest` -> `SomethingResponse`
+* **Route & Status Code Mappings**:
+  - `POST /api/something` -> `201 Created` / `400 Bad Request` / `409 Conflict`
+```
+
+### 2. Architecture Review Template
+```markdown
+# Clean Architecture Review — [Project Name]
+
+## Health Score: [Score]/10
+[Brief architectural health assessment]
+
+## Findings & Recommendations
+### 🔴 Critical (Dependency Violation / Invariant Leakage)
+* **Location**: `path/to/file.ext#L12-30`
+* **Problem**: [Description of the clean architecture violation]
+* **Remediation**:
+  ```[language]
+  // Corrected code snippet
+  ```
+
+### 🟡 Warning (Anemic Model / Pointless Wrapping)
+* **Location**: `path/to/file.ext`
+* **Problem**: [Issue description]
+* **Remediation**: [Code or prose description]
+
+### 🟢 Info (Structural / Pipeline Enhancements)
+* **Location**: `path/to/file.ext`
+* **Remediation**: [Suggestion details]
+```

package/skills/neo-clean-architecture/assets/architecture_template.md

@@ -0,0 +1,93 @@
+# [System Name] — Clean Architecture Design Blueprint
+
+This document specifies the architectural layout for [System Name], conforming to inward-only dependency rules of Clean Architecture.
+
+---
+
+## 1. Domain Layer
+
+The Domain layer is independent of databases, web frameworks, and libraries.
+
+### 1.1 Entities
+
+#### Entity: `[EntityName]`
+* **Description**: [E.g., Represents a registered user account]
+* **Core Attributes** (Read-Only):
+  - `id`: UniqueIdentifier
+  - `[PropertyName]`: [PropertyType]
+* **Invariants & Operations**:
+  - `[MethodName]([parameters])`: [Explain what state changes are made and which invariants are verified]
+  - `constructor([parameters])`: [Initial validation rules upon instantiation]
+
+### 1.2 Value Objects
+
+#### Value Object: `[ValueObjectName]`
+* **Description**: [E.g., Format-validated email address]
+* **Attributes**:
+  - `value`: String
+* **Validation & Formatting**:
+  - [Explain formatting rules or auto-slug generation rules]
+
+---
+
+## 2. Application Layer
+
+Defines use cases, structures input commands/queries, and declares repository interfaces.
+
+### 2.1 Use Cases (CQRS)
+
+#### Command / Query: `[OperationName]`
+* **Description**: [E.g., Creating a new record]
+* **Input Schema**:
+  - `[ParamName]`: [ParamType]
+* **Handler Execution Steps**:
+  1. Trigger **Input Validator** to verify payload formatting.
+  2. Call `[Repository].exists([uniqueKey])` to check for conflicts (return `Result.conflict` if true).
+  3. Instantiate `[DomainEntity]`.
+  4. Invoke `[Repository].add([EntityInstance])`.
+  5. Return `Result.success([EntityId])`.
+
+### 2.2 Repository Interfaces
+
+#### Interface: `I[EntityName]Repository`
+* `findById(id: UniqueIdentifier): Promise<[EntityName] | null>`
+* `add(entity: [EntityName]): Promise<void>`
+* `update(entity: [EntityName]): Promise<void>`
+* `delete(id: UniqueIdentifier): Promise<void>`
+
+---
+
+## 3. Infrastructure Layer
+
+Implements Application interfaces and coordinates technology-specific libraries.
+
+### 3.1 Persistence
+
+#### Class: `[EntityName]Repository`
+* **Interface**: `I[EntityName]Repository`
+* **Data Mapping**:
+  - Map entity `[EntityName]` to table `[table_name]`.
+  - Convert Value Object `[ValueObjectName]` to primitive database column type `[column_type]` on save, and deserialize on fetch.
+* **Transaction Management**:
+  - Save changes using the persistence tracker in the repository's persist methods.
+
+### 3.2 External Gateways
+* [E.g., File storage clients, mail gateways, third-party REST clients]
+
+---
+
+## 4. Presentation / API Layer
+
+Entry point translating network protocols to Use Case payloads.
+
+### 4.1 Endpoints & Routing
+
+#### Route: `[HTTP_METHOD] /api/[resource_path]`
+* **Description**: [E.g., Create a resource]
+* **Request Contract**:
+  - `[FieldName]`: [FieldType]
+* **Response & Status Codes**:
+  - `201 Created` / `200 OK` -> `[ResponseContract]`
+  - `400 Bad Request` -> Validation Schema Errors
+  - `409 Conflict` -> Business Rule Violations
+  - `404 Not Found` -> Resource Missing

package/skills/neo-clean-architecture/assets/review_checklist.md

@@ -0,0 +1,35 @@
+# Clean Architecture Review Checklist
+
+Use this checklist to scan and review code bases for conformity to Clean Architecture boundaries.
+
+---
+
+## 1. Dependency Directions
+* [ ] **Physical Inward Dependency (🔴 Critical)**: Do inner circles (Domain, Application) import, reference, or depend on outer circles (Infrastructure, Presentation, ORM, Web Frameworks)?
+* [ ] **Query Stream Leakage (🔴 Critical)**: Do repository interfaces return ORM-specific query streams (e.g., `IQueryable`, `IPreparedQuery`)? This leaks persistence details to Application.
+* [ ] **ORM Annotation Leakage (🟡 Warning)**: Do domain entities contain database-specific annotations (e.g., `@Table`, `@Column`, `[Key]`, `[Required]`)? (Map ORM metadata in the Infrastructure layer instead).
+* [ ] **External SDK Leakage (🟡 Warning)**: Does the Application layer reference third-party SDK types as handler parameters? (Isolate using DTOs or custom interfaces).
+
+---
+
+## 2. Domain Layer
+* [ ] **Anemic Model (🟡 Warning)**: Are entities plain data bags with public setters, shifting business rules into Application Services?
+* [ ] **Invariant Protection (🟡 Warning)**: Do entity constructors and methods validate rules? Can an entity be instantiated in an invalid state?
+* [ ] **Pointless Value Objects (🟢 Info)**: Are primitives wrapped in value objects without any validation or formatting benefits? (Avoid pointless overhead).
+* [ ] **Coupling by Nested Entities (🟡 Warning)**: Do entities reference other aggregate roots directly as objects (e.g., `class Order { user: User }`)? (Reference aggregate roots via IDs instead to avoid ORM pre-loading performance traps).
+
+---
+
+## 3. Application & Use Case Layer
+* [ ] **Single Responsibility Use Cases (🟢 Info)**: Do use case classes or handlers manage multiple unrelated actions? (Prefer a single handler per business command/query).
+* [ ] **Cross-Cutting Concern Pollution (🟡 Warning)**: Are logging, validation, and transaction commits scattered across use case handlers? (Centralize via pipeline middleware or interceptors).
+* [ ] **Exception Control Flow (🟡 Warning)**: Does application code throw exceptions for expected failures (e.g., password mismatch, username conflict)? (Use Result objects instead).
+* [ ] **Database Transaction Leaks (🔴 Critical)**: Does Application code directly call SQL, NoSQL, or Transaction Commit APIs? (Isolate via `IRepository` and `IUnitOfWork` interfaces).
+
+---
+
+## 4. Presentation & API Layer
+* [ ] **Thin Controllers (🟡 Warning)**: Do controllers or endpoint handlers contain business logic? (Controllers must only parse request payloads and dispatch them).
+* [ ] **Contract Leakage (🟡 Warning)**: Do controllers expose Domain Entities or persistence models directly as API payloads? (Use separate Request/Response DTO contracts).
+* [ ] **Format Validation Isolation (🟢 Info)**: Is basic format validation (e.g., empty string, regex check) caught at the boundary via validators, separate from domain invariants?
+* [ ] **Status Code Mapping (🟢 Info)**: Are Result errors correctly mapped to transport status codes (e.g., HTTP 400, 404, 409, 500)?

package/skills/neo-clean-architecture/evals/eval_queries.json

@@ -0,0 +1,26 @@
+{
+  "should_trigger": [
+    "How to design a clean architecture order module?",
+    "I want to map out a Clean Architecture project structure, how should I layer it?",
+    "Could you check if this domain entity is an anemic model and tell me how to make it a Rich Domain Model?",
+    "How do I implement the Repository Pattern in Clean Architecture without leaking database concerns?",
+    "Should book loan business logic reside in the Domain or Application layer?",
+    "Can you do a Clean Architecture code review on my project structure and code?",
+    "How do I use the Result Pattern instead of Exceptions for flow control?",
+    "How should I reference associations between aggregate roots in Clean Architecture to avoid ORM performance traps?",
+    "Why shouldn't a repository return IQueryable?",
+    "Help me design microservice core logic layers using technology-neutral architecture concepts."
+  ],
+  "should_not_trigger": [
+    "How do I write an ASP.NET Core Minimal API Controller in C#?",
+    "Help me install EF Core SqlServer package and add a new Migration.",
+    "How to write a MediatR Pipeline Behavior?",
+    "How do I write a React file upload UI component?",
+    "Teach me how to write a PostgreSQL JSONB column query in SQL.",
+    "Does this code have a memory leak? Please review for performance issues.",
+    "How do I configure Docker to run a MySQL database?",
+    "What are the three pillars of object-oriented programming?",
+    "How do I implement a binary search tree in Python?",
+    "Write a simple script to parse a CSV file and sum a column."
+  ]
+}

package/skills/neo-clean-architecture/evals/evals.json

@@ -0,0 +1,29 @@
+{
+  "skill_name": "neo-clean-architecture",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Design a Clean Architecture blueprint for an 'Online Library System'. Key requirements: Borrow books (limits: max 5 books per reader, book must be available, loan record automatically saves checkout date and due date). Keep it technology-neutral and concept-focused; do not use specific programming languages.",
+      "expected_output": "A structured Clean Architecture plan containing Domain layer (Entities: Book/Reader/Loan, Value Object: LoanDuration), Application layer (BorrowBookCommand & Handler, IBookRepository interface), and generic descriptions of Infrastructure and Presentation layers, without C# or Java annotations.",
+      "assertions": [
+        "The output lists the four standard layers (Domain, Application, Infrastructure, Presentation)",
+        "The domain entity includes invariant validation methods (e.g., limit checks or status validation)",
+        "The repository interface is defined in the Application layer, not the Infrastructure layer",
+        "Entities reference each other by ID (e.g., Loan references ReaderId/BookId) rather than full object nests",
+        "The design does not depend on specific libraries or frameworks (e.g., EF Core, MediatR, Prisma)"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Review this code snippet for Clean Architecture conformity and suggest remediation:\n```javascript\n// In Controller\napp.post('/api/orders', async (req, res) => {\n  const { userId, items } = req.body;\n  if (!userId) return res.status(400).send('User ID is required');\n  \n  // Direct database query\n  const activeOrder = await db.query('SELECT * FROM orders WHERE user_id = $1 AND status = \\'ACTIVE\\'', [userId]);\n  if (activeOrder.rows.length > 0) {\n    return res.status(409).send('Each user can have only one active order');\n  }\n  \n  const order = {\n    id: generateUUID(),\n    userId,\n    items,\n    status: 'ACTIVE',\n    createdAt: new Date()\n  };\n  await db.query('INSERT INTO orders (id, user_id, items, status, created_at) VALUES ($1, $2, $3, $4, $5)', [order.id, order.userId, JSON.stringify(order.items), order.status, order.createdAt]);\n  \n  res.status(201).json(order);\n});\n```",
+      "expected_output": "An architecture review pointing out database dependency and business logic (limit of one active order) leakage in the controller. It should offer remediation to split code into an Order entity (protecting invariants), a CreateOrderUseCase/Handler, and an IOrderRepository interface, providing technology-neutral code examples.",
+      "assertions": [
+        "Identifies business logic leakage in the controller as a violation",
+        "Identifies direct database coupling in the controller as a violation",
+        "Recommends moving 'one active order check' to the Application/Domain layer",
+        "Includes a technology-neutral refactored code example (with Repository interface and Use Case handler)",
+        "Conforms to the review report template format (containing score, findings, and remediation categories)"
+      ]
+    }
+  ]
+}

package/skills/neo-clean-architecture/references/design_principles.md

@@ -0,0 +1,130 @@
+# Clean Architecture Design Principles
+
+This document defines core concepts of Clean Architecture, focusing on technology-neutral guidelines applicable across different programming languages and frameworks.
+
+---
+
+## 1. Separation of Concerns
+
+Components change for different reasons and at different rates:
+* **Business Rules** (e.g., discount logic): Exist in the **Domain** core. Changes reflect business policy shifts.
+* **Application Use Cases** (e.g., notifying users after sign-up): Coordinate flows in the **Application** layer.
+* **Technical Details** (e.g., PostgreSQL migration, REST-to-gRPC switch): Restricted to **Infrastructure** and **Presentation**.
+
+Coupling these layers increases regression risks. Boundaries isolate changes to keep updates localized.
+
+---
+
+## 2. Inward Dependency Rule
+
+Source code dependencies must point strictly inward. Inner circles have zero knowledge of outer circles.
+
+```
+┌──────────────────────────────────────────────┐
+│  Presentation / API Layer                    │
+│  ┌────────────────────────────────────────┐  │
+│  │  Infrastructure Layer                   │  │
+│  │  ┌──────────────────────────────────┐  │  │
+│  │  │  Application Layer (Use Cases)   │  │  │
+│  │  │  ┌────────────────────────────┐  │  │  │
+│  │  │  │  Domain Core (Entities)    │  │  │  │
+│  │  │  └────────────────────────────┘  │  │  │
+│  │  └──────────────────────────────────┘  │  │
+│  └────────────────────────────────────────┘  │
+└──────────────────────────────────────────────┘
+```
+
+* **Domain Core**: Inmost circle. Depends on nothing. Free of frameworks, database drivers, or outer-circle constructs.
+* **Application**: Depends only on Domain. Defines use cases and abstractions (e.g., Repository interfaces).
+* **Infrastructure**: Depends on Application and Domain. Implements application interfaces, managing persistence and external networks.
+* **Presentation**: Depends on Application. Entry point handling transport protocols (HTTP/gRPC/CLI) and dispatching inputs.
+
+### Dependency Inversion Principle (DIP)
+To persist data without letting the Application depend on Infrastructure:
+* **Approach**: Define an abstract interface (e.g., `IRepository`) in the Application layer. Implement this interface (e.g., `SqlRepository`) in the Infrastructure.
+* **Result**: At runtime, DI resolves the implementation. At compile time, the source code dependency points inward, protecting the boundary.
+
+---
+
+## 3. Rich Domain Model
+
+Entities must protect their **Invariants (business rules and consistency constraints)**. Properties must be read-only, and state changes must go through semantic methods.
+
+Anemic Domain Models (data containers with public setters) scatter business rules across services, leading to duplication and maintenance overhead.
+
+```javascript
+// ✅ Correct Design: Read-only properties, state changes managed via semantic methods
+class Prompt {
+    #id;
+    #title;
+    #content;
+    #tags = new Set();
+
+    constructor(title, content) {
+        if (!title || title.trim() === "") throw new Error("Title is required");
+        this.#id = generateUUID();
+        this.#title = title.trim();
+        this.#content = content;
+    }
+
+    get title() { return this.#title; }
+    get content() { return this.#content; }
+    get tags() { return Array.from(this.#tags); }
+
+    updateContent(newContent) {
+        if (!newContent || newContent.trim() === "") throw new Error("Content cannot be empty");
+        if (this.#content === newContent) return; 
+        this.#content = newContent;
+    }
+
+    addTag(tagValue) {
+        const normalized = tagValue.trim().toLowerCase();
+        if (normalized.length === 0) return;
+        this.#tags.add(normalized);
+    }
+}
+```
+
+---
+
+## 4. Value Objects
+
+Value Objects have no identity (ID) and are defined entirely by their properties. Two Value Objects are equal if their attributes match.
+
+### Avoid Over-engineering
+Do not wrap primitives unless they validate (e.g., `Email` format) or transform data (e.g., `Tag` slugification). Use Value Objects only when:
+1. **Validation is needed**: E.g., verifying `Email` format.
+2. **Behavior is needed**: E.g., converting tag inputs to slugs.
+3. **Attributes form a conceptual whole**: E.g., `Money(amount, currency)`.
+
+---
+
+## 5. Result Pattern
+
+Expected business failures (e.g., resource not found, title conflict) should return a structured `Result` object instead of throwing runtime exceptions.
+
+Exceptions must be reserved for unexpected, fatal system issues (e.g., database connection loss, out-of-memory).
+
+### Generic Result Design
+```javascript
+class Result {
+    constructor(isSuccess, value = null, error = null, errorType = "None") {
+        this.isSuccess = isSuccess;
+        this.value = value;
+        this.error = error;
+        this.errorType = errorType; // e.g., "NotFound", "Validation", "Conflict", "None"
+    }
+
+    static success(value) {
+        return new Result(true, value, null, "None");
+    }
+
+    static failure(error, type = "Failure") {
+        return new Result(false, null, error, type);
+    }
+
+    static notFound(error = "Resource not found") {
+        return new Result(false, null, error, "NotFound");
+    }
+}
+```

package/skills/neo-clean-architecture/references/layer_specifications.md

@@ -0,0 +1,73 @@
+# Clean Architecture Layer Specifications & Mappings
+
+This document defines the responsibilities of each layer and provides guidance on translating technology-specific code/libraries into clean, technology-neutral concepts.
+
+---
+
+## Layers & Boundary Rules
+
+| Layer Name | Core Responsibility | Absolute Prohibitions (Boundary Rules) |
+| :--- | :--- | :--- |
+| **Domain** | 1. Entities<br>2. Value Objects<br>3. Domain logic & invariants<br>4. Domain events | 🚫 No database or ORM dependencies.<br>🚫 No transport protocol references (HTTP/gRPC/CLI).<br>🚫 No references to outer-layer modules (Application/Infrastructure).<br>🚫 No third-party framework annotations (e.g., Spring, Nest, ASP.NET). |
+| **Application** | 1. Use case handlers<br>2. Command & Query inputs<br>3. Repository & Gateway interfaces<br>4. Pipeline / Interceptor interfaces | 🚫 No SQL queries or DB connection details.<br>🚫 No direct HTTP requests, responses, or routing concerns.<br>🚫 No direct access to outer networks, filesystems, or email drivers. |
+| **Infrastructure** | 1. Implement Application interfaces (Repositories)<br>2. Persistence settings & ORM configurations<br>3. External gateway implementations (Mail, Queue, File Storage) | 🚫 No business logic execution outside application-defined interfaces.<br>🚫 No direct database state modification bypassing domain invariants.<br>🚫 No dependencies on Presentation layer structures (e.g., HTTP sessions). |
+| **Presentation / API** | 1. Parse and validate Request Contracts<br>2. Basic format validation (length, null check, regex)<br>3. Dispatch inputs to Application Use Cases<br>4. Map Result to Response Contracts & Status Codes | 🚫 No direct database queries (must go through Application).<br>🚫 No business rules or invariant checks.<br>🚫 No business transaction assembly across aggregates. |
+
+---
+
+## Technology-Specific to Clean Concept Mappings
+
+When reviewing codebases, map programming language syntax and library features to these universal concepts:
+
+### 1. Request Orchestration (e.g., MediatR in C#, Spring Service in Java)
+* **Library Feature**:
+  * C# `IMediator.Send(command)` or `IRequestHandler`.
+  * Java `@Service` annotations mixing use case execution with business logic.
+* **Technology-Neutral Concept**:
+  * **Command/Query Dispatcher** or **Use Case Interactor**.
+  * Separate each business workflow into a dedicated `UseCase` class or `Handler` function, dividing input schemas from execution logic.
+* **Concept Mapping Code**:
+  ```javascript
+  // Technology-neutral Use Case concept
+  class CreateUserUseCase {
+      constructor(userRepository, emailGateway) {
+          this.userRepository = userRepository;
+          this.emailGateway = emailGateway;
+      }
+
+      async execute(command) {
+          // Flow coordination...
+      }
+  }
+  ```
+
+### 2. Cross-Cutting Concerns (e.g., MediatR Pipeline, Spring AOP, Express Middleware)
+* **Library Feature**:
+  * C# `IPipelineBehavior<TRequest, TResponse>` or Express `next()` middleware.
+* **Technology-Neutral Concept**:
+  * **Pipeline Middleware / Interceptor**.
+  * Intercept actions before and after use case execution to run Logging, Validation, Transaction, and Caching. This isolates the core handler from infrastructure concerns.
+
+### 3. Persistence Mapping (e.g., EF Core, Hibernate, Prisma, Mongoose)
+* **Library Feature**:
+  * C# `DbContext`, `DbSet`, `IEntityTypeConfiguration`, or ORM navigation properties with Lazy Loading.
+* **Technology-Neutral Concept**:
+  * **Persistence Context** and **Data Mapper**.
+  * Map entities to database schemas, converting value objects to database-friendly primitives. The Domain layer must remain free of ORM annotations or persistence metadata.
+
+### 4. Repository Leakage
+* **Library Feature**:
+  * Returning C# `IQueryable<T>` or Java `Stream<T>` from repositories.
+* **Technology-Neutral Concept**:
+  * **Leaky Abstraction Anti-Pattern**.
+  * Returning query streams allows Application code to inject query filters (e.g., SQL/LINQ criteria), leaking database capabilities inward and blocking unit test isolation.
+  * **Remediation**: Repositories must return **concrete collections** (e.g., `List` or pagination objects) or expose semantic queries (e.g., `findActiveUsersByRole`).
+
+### 5. Input Validation (e.g., FluentValidation, JSR-380 annotations)
+* **Library Feature**:
+  * `AbstractValidator` or `@NotNull` property constraints.
+* **Technology-Neutral Concept**:
+  * **Input Validator**.
+  * Manage basic schema checks at boundaries. Separate validation into:
+    1. **Format Validation**: Intercept malformed payloads at API/Application boundaries.
+    2. **Invariant Validation**: Enforce business policy rules inside the Domain entity constructor/methods.