chore(ipuaro): release v0.26.0

feat(ipuaro): add decorator extraction to initial context
Extract decorators from classes and methods for NestJS/Angular support. Decorators are now shown in initial context: - @Controller('users') class UserController - @Get(':id') async getUser(id: string): Promise<User> Changes: - Add decorators field to FunctionInfo, MethodInfo, ClassInfo - Update ASTParser to extract decorators from tree-sitter nodes - Update formatFileSummary to display decorators prefix - Add 18 unit tests for decorator extraction and formatting
2025-12-28 07:16:53 +05:00 · 2025-12-05 13:51:13 +05:00 · 2025-12-05 13:38:46 +05:00 · 2025-12-05 13:14:51 +05:00 · 2025-12-04 22:49:35 +05:00 · 2025-12-04 22:49:03 +05:00
367 changed files with 77138 additions and 1865 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -86,3 +86,4 @@ Thumbs.db

 # Yarn Integrity file
 .yarn-integrity
+packages/guardian/docs/STRATEGIC_ANALYSIS_2025-11.md
--- a/.gitmessage
+++ b/.gitmessage
@@ -1,9 +1,17 @@
-# <type>: <subject>
+# <type>(<package>): <subject>
 #
 # <body>
 #
 # <footer>

+# Format:
+# - Package changes: <type>(<package>): <subject>
+#   Examples: feat(guardian): add detector
+#             fix(ipuaro): resolve memory leak
+# - Root changes:    <type>: <subject>
+#   Examples: chore: update eslint config
+#             docs: update root README
+
 # Type should be one of the following:
 # * feat: A new feature
 # * fix: A bug fix
@@ -16,6 +24,11 @@
 # * ci: Changes to CI configuration files and scripts
 # * chore: Other changes that don't modify src or test files
 # * revert: Reverts a previous commit
+
+# Package scopes:
+# * guardian - @puaros/guardian package
+# * ipuaro   - @puaros/ipuaro package
+# * (none)   - root-level changes
 #
 # Subject line rules:
 # - Use imperative mood ("add feature" not "added feature")
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,42 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-### Added
- Initial monorepo setup with pnpm workspaces
- `@puaros/guardian` package - code quality guardian for vibe coders and enterprise teams
- TypeScript with strict type checking and Vitest configuration
- ESLint strict TypeScript rules with 4-space indentation
- Prettier code formatting (4 spaces, double quotes, no semicolons)
- LINTING.md documentation for code style guidelines
- CLAUDE.md for AI assistant guidance
- EditorConfig for consistent IDE settings
- Node.js version specification (.nvmrc: 22.18.0)
- Vitest testing framework with 80% coverage thresholds
- Guardian dependencies: commander, simple-git, tree-sitter, uuid
-
-### Configuration
- TypeScript: nodenext modules, ES2023 target, strict null checks
- ESLint: Strict type checking, complexity limits, code quality rules
- Prettier: 100 char line length, double quotes, no semicolons, trailing commas
- Test coverage: 80% threshold for lines, functions, branches, statements
-
-### Guardian Package
- Hardcode detection (magic numbers, strings)
- Circular dependency detection
- Naming convention enforcement
- Architecture violation detection
- CLI tool with `guardian` command
- 159 tests, all passing
- Clean Architecture implementation
-
-## [0.0.1] - 2025-11-24
-
-### Added
- Initial project structure
- Monorepo workspace configuration
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,7 +4,53 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

 ## Project Overview

-Puaros is a TypeScript monorepo using pnpm workspaces. Currently contains the `@puaros/guardian` package - a code quality guardian for detecting hardcoded values, circular dependencies, framework leaks, naming violations, and architecture violations. The project uses Node.js 22.18.0 (see `.nvmrc`).
+Puaros is a TypeScript monorepo using pnpm workspaces. Contains two packages:
+
+- **`@samiyev/guardian`** - Code quality guardian for detecting hardcoded values, circular dependencies, framework leaks, naming violations, and architecture violations.
+
+- **`@samiyev/ipuaro`** - Local AI agent for codebase operations with "infinite" context feeling. Uses lazy loading, Redis persistence, tree-sitter AST parsing, and Ollama LLM integration.
+
+The project uses Node.js 22.18.0 (see `.nvmrc`).
+
+## Path Reference
+
+**Root:** `/Users/fozilbeksamiyev/projects/ailabs/puaros`
+
+### Key Paths
+
+| Description | Path |
+|-------------|------|
+| **Root** | `.` |
+| **Guardian package** | `packages/guardian` |
+| **Guardian src** | `packages/guardian/src` |
+| **Guardian tests** | `packages/guardian/tests` |
+| **Guardian CLI** | `packages/guardian/src/cli` |
+| **Guardian domain** | `packages/guardian/src/domain` |
+| **Guardian infrastructure** | `packages/guardian/src/infrastructure` |
+| **ipuaro package** | `packages/ipuaro` |
+| **ipuaro docs** | `packages/ipuaro/docs` |
+
+### File Locations
+
+| File | Location |
+|------|----------|
+| Root package.json | `./package.json` |
+| Guardian package.json | `packages/guardian/package.json` |
+| Guardian tsconfig | `packages/guardian/tsconfig.json` |
+| Guardian TODO | `packages/guardian/TODO.md` |
+| Guardian CHANGELOG | `packages/guardian/CHANGELOG.md` |
+| ipuaro ROADMAP | `packages/ipuaro/ROADMAP.md` |
+| ESLint config | `./eslint.config.mjs` |
+| Prettier config | `./.prettierrc` |
+| Base tsconfig | `./tsconfig.base.json` |
+
+### Path Rules
+
+1. **Always use relative paths from project root** (not absolute)
+2. **Package paths start with** `packages/<name>/`
+3. **Source code is in** `packages/<name>/src/`
+4. **Tests are in** `packages/<name>/tests/`
+5. **Docs are in** `packages/<name>/docs/` or `./docs/`

 ## Essential Commands

@@ -100,28 +146,51 @@ From `eslint.config.mjs` and detailed in `LINTING.md`:

 Follow Conventional Commits format. See `.gitmessage` for full rules.

-Format: `<type>: <subject>` (imperative mood, no caps, max 50 chars)
+**Monorepo format:** `<type>(<package>): <subject>`

-**IMPORTANT: Do NOT add "Generated with Claude Code" footer or "Co-Authored-By: Claude" to commit messages.**
-Commits should only follow the Conventional Commits format without any additional attribution.
+Examples:
+- `feat(guardian): add circular dependency detector`
+- `fix(ipuaro): resolve memory leak in indexer`
+- `docs(guardian): update CLI usage examples`
+- `refactor(ipuaro): extract tool registry`
+
+**Root-level changes:** `<type>: <subject>` (no scope)
+- `chore: update eslint config`
+- `docs: update root README`
+
+**Types:** feat, fix, docs, style, refactor, test, chore
+
+**Rules:**
+- Imperative mood, no caps, max 50 chars
+- Do NOT add "Generated with Claude Code" footer
+- Do NOT add "Co-Authored-By: Claude"

 ## Monorepo Structure

 ```
 puaros/
 ├── packages/
-│   └── guardian/                # @puaros/guardian - Code quality analyzer
-│       ├── src/                 # Source files (Clean Architecture layers)
-│       │   ├── domain/          # Domain layer (entities, value objects)
-│       │   ├── application/     # Application layer (use cases, DTOs)
-│       │   ├── infrastructure/  # Infrastructure layer (parsers, analyzers)
-│       │   ├── cli/            # CLI implementation
-│       │   └── shared/          # Shared utilities
-│       ├── dist/                # Build output
+│   ├── guardian/                # @samiyev/guardian - Code quality analyzer
+│   │   ├── src/                 # Source files (Clean Architecture)
+│   │   │   ├── domain/          # Entities, value objects
+│   │   │   ├── application/     # Use cases, DTOs
+│   │   │   ├── infrastructure/  # Parsers, analyzers
+│   │   │   ├── cli/             # CLI implementation
+│   │   │   └── shared/          # Shared utilities
+│   │   ├── bin/                 # CLI entry point
+│   │   ├── tests/               # Test files
+│   │   └── examples/            # Usage examples
+│   └── ipuaro/                  # @samiyev/ipuaro - Local AI agent
+│       ├── src/                 # Source files (Clean Architecture)
+│       │   ├── domain/          # Entities, value objects, services
+│       │   ├── application/     # Use cases, DTOs, mappers
+│       │   ├── infrastructure/  # Storage, LLM, indexer, tools
+│       │   ├── tui/             # Terminal UI (Ink/React)
+│       │   ├── cli/             # CLI commands
+│       │   └── shared/          # Types, constants, utils
 │       ├── bin/                 # CLI entry point
-│       ├── tests/               # Test files
-│       ├── examples/            # Usage examples
-│       └── package.json         # Uses Vitest for testing
+│       ├── tests/               # Unit and E2E tests
+│       └── examples/            # Demo projects
 ├── pnpm-workspace.yaml          # Workspace configuration
 └── tsconfig.base.json           # Shared TypeScript config
 ```
@@ -142,6 +211,34 @@ Key features:
 - Architecture violation detection
 - CLI tool with `guardian` command

+### ipuaro Package Architecture
+
+The ipuaro package follows Clean Architecture principles:
+- **Domain Layer**: Entities (Session, Project), value objects (FileData, FileAST, ChatMessage), service interfaces
+- **Application Layer**: Use cases (StartSession, HandleMessage, IndexProject, ExecuteTool), DTOs, mappers
+- **Infrastructure Layer**: Redis storage, Ollama client, indexer, 18 tool implementations, security
+- **TUI Layer**: Ink/React components (StatusBar, Chat, Input, DiffView, ConfirmDialog)
+- **CLI Layer**: Commander.js entry point and commands
+
+Key features:
+- 18 LLM tools (read, edit, search, analysis, git, run)
+- Redis persistence with AOF
+- tree-sitter AST parsing (ts, tsx, js, jsx)
+- Ollama LLM integration (qwen2.5-coder:7b-instruct)
+- File watching via chokidar
+- Session and undo management
+- Security (blacklist/whitelist for commands)
+
+**Tools summary:**
+| Category | Tools |
+|----------|-------|
+| Read | get_lines, get_function, get_class, get_structure |
+| Edit | edit_lines, create_file, delete_file |
+| Search | find_references, find_definition |
+| Analysis | get_dependencies, get_dependents, get_complexity, get_todos |
+| Git | git_status, git_diff, git_commit |
+| Run | run_command, run_tests |
+
 ### TypeScript Configuration

 Base configuration (`tsconfig.base.json`) uses:
@@ -163,29 +260,290 @@ Guardian package (`packages/guardian/tsconfig.json`):
 ## Adding New Packages

 1. Create `packages/new-package/` directory
-2. Add `package.json` with name `@puaros/new-package`
+2. Add `package.json` with name `@samiyev/new-package`
 3. Create `tsconfig.json` extending `../../tsconfig.base.json`
 4. Package auto-discovered via `pnpm-workspace.yaml` glob pattern

 ## Dependencies

-Guardian package uses:
- `commander` - CLI framework for command-line interface
+**Guardian package:**
+- `commander` - CLI framework
 - `simple-git` - Git operations
- `tree-sitter` - Abstract syntax tree parsing
- `tree-sitter-javascript` - JavaScript parser
- `tree-sitter-typescript` - TypeScript parser
+- `tree-sitter` - AST parsing
+- `tree-sitter-javascript/typescript` - JS/TS parsers
 - `uuid` - UUID generation

-Development tools:
- Vitest for testing with coverage thresholds
+**ipuaro package:**
+- `ink`, `ink-text-input`, `react` - Terminal UI
+- `ioredis` - Redis client
+- `tree-sitter` - AST parsing
+- `tree-sitter-javascript/typescript` - JS/TS parsers
+- `ollama` - LLM client
+- `simple-git` - Git operations
+- `chokidar` - File watching
+- `commander` - CLI framework
+- `zod` - Validation
+- `ignore` - Gitignore parsing
+
+**Development tools (shared):**
+- Vitest for testing (80% coverage threshold)
 - ESLint with TypeScript strict rules
- Prettier for formatting
- `@vitest/ui` - Vitest UI for interactive testing
+- Prettier (4-space indentation)
+- `@vitest/ui` - Interactive testing UI
 - `@vitest/coverage-v8` - Coverage reporting

+## Monorepo Versioning Strategy
+
+### Git Tag Format
+
+**Prefixed tags for each package:**
+```
+guardian-v0.5.0
+ipuaro-v0.1.0
+```
+
+**Why prefixed tags:**
+- Independent versioning per package
+- Clear release history for each package
+- Works with npm publish and CI/CD
+- Easy to filter: `git tag -l "guardian-*"`
+
+**Legacy tags:** Tags before monorepo (v0.1.0, v0.2.0, etc.) are kept as-is for historical reference.
+
+### Semantic Versioning
+
+All packages follow SemVer: `MAJOR.MINOR.PATCH`
+
+- **MAJOR** (1.0.0) - Breaking API changes
+- **MINOR** (0.1.0) - New features, backwards compatible
+- **PATCH** (0.0.1) - Bug fixes, backwards compatible
+
+**Pre-1.0 policy:** Minor bumps (0.x.0) may include breaking changes.
+
+## Release Pipeline
+
+**Quick reference:** Say "run pipeline for [package]" to execute full release flow.
+
+The pipeline has 6 phases. Each phase must pass before proceeding.
+
+### Phase 1: Quality Gates
+
+```bash
+cd packages/<package>
+
+# All must pass:
+pnpm format                              # 4-space indentation
+pnpm build                               # TypeScript compiles
+cd ../.. && pnpm eslint "packages/**/*.ts" --fix  # 0 errors, 0 warnings
+cd packages/<package>
+pnpm test:run                            # All tests pass
+pnpm test:coverage                       # Coverage ≥80%
+```
+
+### Phase 2: Documentation
+
+Update these files in `packages/<package>/`:
+
+| File | Action |
+|------|--------|
+| `README.md` | Add feature docs, update CLI usage, update API |
+| `TODO.md` | Mark completed tasks, add new tech debt if any |
+| `CHANGELOG.md` | Add version entry with all changes |
+| `ROADMAP.md` | Update if milestone completed |
+
+**Tech debt rule:** If implementation leaves known issues, shortcuts, or future improvements needed — add them to TODO.md before committing.
+
+### Phase 3: Manual Testing
+
+```bash
+cd packages/<package>
+
+# Test CLI/API manually
+node dist/cli/index.js <command> ./examples
+
+# Verify output, edge cases, error handling
+```
+
+### Phase 4: Commit
+
+```bash
+git add .
+git commit -m "<type>(<package>): <description>"
+
+# Examples:
+# feat(guardian): add --limit option
+# fix(ipuaro): resolve memory leak in indexer
+# docs(guardian): update API examples
+```
+
+**Commit types:** feat, fix, docs, style, refactor, test, chore
+
+### Phase 5: Version & Tag
+
+```bash
+cd packages/<package>
+
+# Bump version
+npm version patch  # 0.5.2 → 0.5.3 (bug fix)
+npm version minor  # 0.5.2 → 0.6.0 (new feature)
+npm version major  # 0.5.2 → 1.0.0 (breaking change)
+
+# Create prefixed git tag
+git tag <package>-v<version>
+# Example: git tag guardian-v0.6.0
+
+# Push
+git push origin main
+git push origin <package>-v<version>
+```
+
+### Phase 6: Publish (Maintainers Only)
+
+```bash
+cd packages/<package>
+
+# Final verification
+pnpm build && pnpm test:run && pnpm test:coverage
+
+# Check package contents
+npm pack --dry-run
+
+# Publish
+npm publish --access public
+
+# Verify
+npm info @samiyev/<package>
+```
+
+## Pipeline Checklist
+
+Copy and use for each release:
+
+```markdown
+## Release: <package> v<version>
+
+### Quality Gates
+- [ ] `pnpm format` - no changes
+- [ ] `pnpm build` - compiles
+- [ ] `pnpm eslint` - 0 errors, 0 warnings
+- [ ] `pnpm test:run` - all pass
+- [ ] `pnpm test:coverage` - ≥80%
+
+### Documentation
+- [ ] README.md updated
+- [ ] TODO.md - completed tasks marked, new debt added
+- [ ] CHANGELOG.md - version entry added
+- [ ] ROADMAP.md updated (if needed)
+
+### Testing
+- [ ] CLI/API tested manually
+- [ ] Edge cases verified
+
+### Release
+- [ ] Commit with conventional format
+- [ ] Version bumped in package.json
+- [ ] Git tag created: <package>-v<version>
+- [ ] Pushed to origin
+- [ ] Published to npm (if public release)
+```
+
+## Working with Roadmap
+
+When the user points to `ROADMAP.md` or asks about the roadmap/next steps:
+
+1. **Read both files together:**
+   - `packages/<package>/ROADMAP.md` - to understand the planned features and milestones
+   - `packages/<package>/CHANGELOG.md` - to see what's already implemented
+
+2. **Determine current position:**
+   - Check the latest version in CHANGELOG.md
+   - Cross-reference with ROADMAP.md milestones
+   - Identify which roadmap items are already completed (present in CHANGELOG)
+
+3. **Suggest next steps:**
+   - Find the first uncompleted item in the current milestone
+   - Or identify the next milestone if current one is complete
+   - Present clear "start here" recommendation
+
+**Example workflow:**
+```
+User: "Let's work on the roadmap" or points to ROADMAP.md
+
+Claude should:
+1. Read ROADMAP.md → See milestones v0.1.0, v0.2.0, v0.3.0...
+2. Read CHANGELOG.md → See latest release is v0.1.1
+3. Compare → v0.1.0 milestone complete, v0.2.0 in progress
+4. Report → "v0.1.0 is complete. For v0.2.0, next item is: <feature>"
+```
+
+## Common Workflows
+
+### Adding a new CLI option
+
+```bash
+# 1. Add to cli/constants.ts (CLI_OPTIONS, CLI_DESCRIPTIONS)
+# 2. Add option in cli/index.ts (.option() call)
+# 3. Parse and use option in action handler
+# 4. Test: node dist/cli/index.js <command> --your-option
+# 5. Run pipeline
+```
+
+### Adding a new detector (guardian)
+
+```bash
+# 1. Create value object in domain/value-objects/
+# 2. Create detector in infrastructure/analyzers/
+# 3. Add interface to domain/services/
+# 4. Integrate in application/use-cases/AnalyzeProject.ts
+# 5. Add CLI output in cli/index.ts
+# 6. Write tests (aim for >90% coverage)
+# 7. Run pipeline
+```
+
+### Adding a new tool (ipuaro)
+
+```bash
+# 1. Define tool schema in infrastructure/tools/schemas/
+# 2. Implement tool in infrastructure/tools/
+# 3. Register in infrastructure/tools/index.ts
+# 4. Add tests
+# 5. Run pipeline
+```
+
+### Fixing technical debt
+
+```bash
+# 1. Find issue in TODO.md
+# 2. Implement fix
+# 3. Update TODO.md (mark as completed)
+# 4. Run pipeline with type: "refactor:" or "fix:"
+```
+
+## Debugging Tips
+
+**Build errors:**
+```bash
+pnpm tsc --noEmit
+pnpm tsc --noEmit packages/<package>/src/path/to/file.ts
+```
+
+**Test failures:**
+```bash
+pnpm vitest tests/path/to/test.test.ts
+pnpm test:ui
+```
+
+**Coverage issues:**
+```bash
+pnpm test:coverage
+open coverage/index.html
+```
+
 ## Important Notes

 - **Always run `pnpm format` before committing** to ensure 4-space indentation
 - **Fix ESLint warnings incrementally** - they indicate real type safety issues
- **Coverage is enforced** - maintain 80% coverage for all metrics when running `pnpm test:coverage`
+- **Coverage is enforced** - maintain 80% coverage for all metrics when running `pnpm test:coverage`
+- **Test CLI manually** - automated tests don't cover CLI output formatting
+- **Update documentation** - README.md and TODO.md should always reflect current state
+- **Follow Clean Architecture** - keep layers separate and dependencies flowing inward
--- a/README.md
+++ b/README.md
@@ -4,7 +4,9 @@ A TypeScript monorepo for code quality and analysis tools.

 ## Packages

- **[@puaros/guardian](./packages/guardian)** - Code quality guardian for vibe coders and enterprise teams. Detects hardcoded values, circular dependencies, and architecture violations. Perfect for AI-assisted development and enforcing Clean Architecture at scale.
+- **[@puaros/guardian](./packages/guardian)** - Research-backed code quality guardian for vibe coders and enterprise teams. Detects hardcoded values, secrets, circular dependencies, architecture violations, and anemic domain models. Every rule is based on academic research, industry standards (OWASP, SonarQube), and authoritative books (Martin Fowler, Uncle Bob, Eric Evans). Perfect for AI-assisted development and enforcing Clean Architecture at scale.
+
+- **[@puaros/ipuaro](./packages/ipuaro)** - Local AI agent for codebase operations with "infinite" context feeling. Uses lazy loading and smart context management to work with codebases of any size. Features 18 LLM tools for reading, editing, searching, and analyzing code. Built with Ink/React TUI, Redis persistence, tree-sitter AST parsing, and Ollama integration.

 ## Prerequisites

@@ -75,18 +77,27 @@ pnpm eslint "packages/**/*.ts"
 ```
 puaros/
 ├── packages/
-│   └── guardian/              # @puaros/guardian - Code quality analyzer
+│   ├── guardian/              # @puaros/guardian - Code quality analyzer
+│   │   ├── src/               # Source files (Clean Architecture)
+│   │   │   ├── domain/        # Domain layer
+│   │   │   ├── application/   # Application layer
+│   │   │   ├── infrastructure/# Infrastructure layer
+│   │   │   ├── cli/           # CLI implementation
+│   │   │   └── shared/        # Shared utilities
+│   │   ├── bin/               # CLI entry point
+│   │   ├── tests/             # Unit and integration tests
+│   │   └── examples/          # Usage examples
+│   └── ipuaro/                # @puaros/ipuaro - Local AI agent
 │       ├── src/               # Source files (Clean Architecture)
-│       │   ├── domain/        # Domain layer
-│       │   ├── application/   # Application layer
-│       │   ├── infrastructure/# Infrastructure layer
-│       │   ├── cli/          # CLI implementation
-│       │   └── shared/        # Shared utilities
-│       ├── dist/              # Build output (generated)
+│       │   ├── domain/        # Entities, value objects, services
+│       │   ├── application/   # Use cases, DTOs, mappers
+│       │   ├── infrastructure/# Storage, LLM, indexer, tools
+│       │   ├── tui/           # Terminal UI (Ink/React)
+│       │   ├── cli/           # CLI commands
+│       │   └── shared/        # Types, constants, utils
 │       ├── bin/               # CLI entry point
-│       ├── tests/             # Unit and integration tests
-│       ├── examples/          # Usage examples
-│       └── package.json
+│       ├── tests/             # Unit and E2E tests
+│       └── examples/          # Demo projects
 ├── pnpm-workspace.yaml        # Workspace configuration
 ├── tsconfig.base.json         # Shared TypeScript config
 ├── eslint.config.mjs          # ESLint configuration
@@ -147,6 +158,21 @@ The `@puaros/guardian` package is a code quality analyzer for both individual de
 - **CLI Tool**: Command-line interface with `guardian` command
 - **CI/CD Integration**: JSON/Markdown output for automation pipelines

+### 📚 Research-Backed Rules
+
+Guardian's detection rules are based on decades of software engineering research and industry best practices:
+
+- **Academic Research**: MIT Course 6.031, ScienceDirect peer-reviewed studies (2020-2023), IEEE papers on Technical Debt
+- **Industry Standards**: SonarQube (400,000+ organizations), Google/Airbnb/Microsoft style guides, OWASP security standards
+- **Authoritative Books**:
+  - Clean Architecture (Robert C. Martin, 2017)
+  - Implementing Domain-Driven Design (Vaughn Vernon, 2013)
+  - Domain-Driven Design (Eric Evans, 2003)
+  - Patterns of Enterprise Application Architecture (Martin Fowler, 2002)
+- **Security Standards**: OWASP Secrets Management, GitHub Secret Scanning (350+ patterns)
+
+**Every rule links to research citations** - see [Why Guardian's Rules Matter](./packages/guardian/docs/WHY.md) and [Full Research Citations](./packages/guardian/docs/RESEARCH_CITATIONS.md) for complete academic papers, books, and expert references.
+
 ### Use Cases

 **For Vibe Coders:**
@@ -189,6 +215,79 @@ guardian check ./src --format json > report.json
 guardian check ./src --fail-on hardcode --fail-on circular
 ```

+## ipuaro Package
+
+The `@puaros/ipuaro` package is a local AI agent for codebase operations:
+
+### Features
+
+- **Infinite Context Feeling**: Lazy loading and smart context management for any codebase size
+- **18 LLM Tools**: Read, edit, search, analyze code through natural language
+- **Terminal UI**: Full-featured TUI built with Ink/React
+- **Redis Persistence**: Sessions, undo stack, and project index stored in Redis
+- **AST Parsing**: tree-sitter for TypeScript/JavaScript analysis
+- **File Watching**: Real-time index updates via chokidar
+- **Security**: Blacklist/whitelist for command execution
+
+### Tech Stack
+
+| Component | Technology |
+|-----------|------------|
+| Runtime | Node.js + TypeScript |
+| TUI | Ink (React for terminal) |
+| Storage | Redis with AOF persistence |
+| AST | tree-sitter (ts, tsx, js, jsx) |
+| LLM | Ollama (qwen2.5-coder:7b-instruct) |
+| Git | simple-git |
+| File watching | chokidar |
+
+### Tools (18 total)
+
+| Category | Tools |
+|----------|-------|
+| **Read** | get_lines, get_function, get_class, get_structure |
+| **Edit** | edit_lines, create_file, delete_file |
+| **Search** | find_references, find_definition |
+| **Analysis** | get_dependencies, get_dependents, get_complexity, get_todos |
+| **Git** | git_status, git_diff, git_commit |
+| **Run** | run_command, run_tests |
+
+### Architecture
+
+Built with Clean Architecture principles:
+- **Domain Layer**: Entities, value objects, service interfaces
+- **Application Layer**: Use cases, DTOs, mappers
+- **Infrastructure Layer**: Redis storage, Ollama client, indexer, tools
+- **TUI Layer**: Ink/React components and hooks
+- **CLI Layer**: Commander.js entry point
+
+### Usage
+
+```bash
+# Start TUI in current directory
+ipuaro
+
+# Start in specific directory
+ipuaro /path/to/project
+
+# Index only (no TUI)
+ipuaro index
+
+# With auto-apply mode
+ipuaro --auto-apply
+```
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show all commands |
+| `/clear` | Clear chat history |
+| `/undo` | Revert last file change |
+| `/sessions` | Manage sessions |
+| `/status` | System status |
+| `/reindex` | Force reindexation |
+
 ## Dependencies

 Guardian package uses:
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -13,6 +13,9 @@ export default tseslint.config(
            '**/coverage/**',
            '**/.puaros/**',
            '**/build/**',
+            '**/examples/**',
+            '**/tests/**',
+            '**/*.config.ts',
        ],
    },
    eslint.configs.recommended,
@@ -64,13 +67,14 @@ export default tseslint.config(
            '@typescript-eslint/no-floating-promises': 'error',
            '@typescript-eslint/await-thenable': 'error',
            '@typescript-eslint/no-misused-promises': 'error',
-            '@typescript-eslint/prefer-nullish-coalescing': 'warn',
+            '@typescript-eslint/prefer-nullish-coalescing': 'off', // Allow || operator alongside ??
            '@typescript-eslint/prefer-optional-chain': 'warn',
            '@typescript-eslint/prefer-readonly': 'warn',
            '@typescript-eslint/promise-function-async': 'warn',
            '@typescript-eslint/require-await': 'warn',
-            '@typescript-eslint/no-unnecessary-condition': 'warn',
+            '@typescript-eslint/no-unnecessary-condition': 'off', // Sometimes useful for defensive coding
            '@typescript-eslint/no-non-null-assertion': 'warn',
+            '@typescript-eslint/no-unnecessary-type-parameters': 'warn', // Allow generic JSON parsers

            // ========================================
            // Code Quality & Best Practices
@@ -82,7 +86,7 @@ export default tseslint.config(
            'prefer-const': 'error',
            'prefer-arrow-callback': 'warn',
            'prefer-template': 'warn',
-            'no-nested-ternary': 'warn',
+            'no-nested-ternary': 'off', // Allow nested ternaries when readable
            'no-unneeded-ternary': 'error',
            'no-else-return': 'warn',
            eqeqeq: ['error', 'always'],
@@ -94,7 +98,7 @@ export default tseslint.config(
            // ========================================
            // Code Style (handled by Prettier mostly)
            // ========================================
-            indent: ['error', 4, { SwitchCase: 1 }],
+            indent: 'off', // Let Prettier handle this
            '@typescript-eslint/indent': 'off', // Let Prettier handle this
            quotes: ['error', 'double', { avoidEscape: true }],
            semi: ['error', 'never'],
@@ -156,4 +160,24 @@ export default tseslint.config(
            ],
        },
    },
+    {
+        // CLI-specific overrides
+        files: ['**/cli/**/*.ts', '**/cli/**/*.js'],
+        rules: {
+            'no-console': 'off', // Console is expected in CLI
+            'max-lines-per-function': 'off', // CLI action handlers can be long
+            complexity: 'off', // CLI logic can be complex
+            '@typescript-eslint/no-unsafe-member-access': 'off', // Commander options are untyped
+            '@typescript-eslint/no-unsafe-assignment': 'off',
+            '@typescript-eslint/no-unsafe-call': 'off',
+            '@typescript-eslint/no-unsafe-argument': 'off',
+        },
+    },
+    {
+        // Value Objects and Domain - allow more parameters for create methods
+        files: ['**/domain/value-objects/**/*.ts', '**/application/use-cases/**/*.ts'],
+        rules: {
+            'max-params': ['warn', 8], // DDD patterns often need more params
+        },
+    },
 );
--- a/packages/guardian/CHANGELOG.md
+++ b/packages/guardian/CHANGELOG.md
@@ -5,6 +5,915 @@ All notable changes to @samiyev/guardian will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

+## [0.9.4] - 2025-11-30
+
+### Added
+
+- **VERSION export** - Package version is now exported from index.ts, automatically read from package.json
+
+### Changed
+
+- 🔄 **Refactored SecretDetector** - Reduced cyclomatic complexity from 24 to <15:
+  - Extracted helper methods: `extractByRuleId`, `extractAwsType`, `extractGithubType`, `extractSshType`, `extractSlackType`, `extractByMessage`
+  - Used lookup arrays for SSH and message type mappings
+- 🔄 **Refactored AstNamingTraverser** - Reduced cyclomatic complexity from 17 to <15:
+  - Replaced if-else chain with Map-based node handlers
+  - Added `buildNodeHandlers()` method for cleaner architecture
+
+### Quality
+
+- ✅ **Zero lint warnings** - All ESLint warnings resolved
+- ✅ **All 616 tests pass**
+
+## [0.9.2] - 2025-11-27
+
+### Changed
+
+- 🔄 **Refactored naming convention detector** - Migrated from regex-based to AST-based analysis:
+  - Replaced regex pattern matching with tree-sitter Abstract Syntax Tree traversal
+  - Improved accuracy with AST node context awareness (classes, interfaces, functions, variables)
+  - Reduced false positives with better naming pattern detection
+  - Added centralized AST node type constants (`ast-node-types.ts`) for maintainability
+  - New modular architecture with specialized analyzers:
+    - `AstClassNameAnalyzer` - Class naming validation
+    - `AstInterfaceNameAnalyzer` - Interface naming validation
+    - `AstFunctionNameAnalyzer` - Function naming validation
+    - `AstVariableNameAnalyzer` - Variable naming validation
+    - `AstNamingTraverser` - AST traversal for naming analysis
+  - Enhanced context-aware suggestions for hardcoded values:
+    - Added context keywords (EMAIL_CONTEXT_KEYWORDS, API_KEY_CONTEXT_KEYWORDS, URL_CONTEXT_KEYWORDS, etc.)
+    - Improved constant name generation based on context (ADMIN_EMAIL, API_SECRET_KEY, DATABASE_URL, etc.)
+    - Better file path suggestions (CONFIG_ENVIRONMENT, CONFIG_CONTACTS, CONFIG_PATHS, etc.)
+
+### Quality
+
+- ✅ **All tests pass** - Updated tests for AST-based naming detection
+- ✅ **Code organization** - Centralized AST constants reduce code duplication
+- ✅ **Maintainability** - Modular analyzers improve code separation and testability
+
+## [0.9.1] - 2025-11-26
+
+### Changed
+
+- 🔄 **Refactored hardcode detector** - Migrated from regex-based to AST-based analysis:
+  - Replaced regex pattern matching with tree-sitter Abstract Syntax Tree traversal
+  - Improved accuracy with AST node context awareness (exports, types, tests)
+  - Reduced false positives with better constant and context detection
+  - Added duplicate value tracking across files for better insights
+  - Implemented boolean literal detection (magic-boolean type)
+  - Added value type classification (email, url, ip_address, api_key, uuid, version, color, etc.)
+  - New modular architecture with specialized analyzers:
+    - `AstTreeTraverser` - AST walking with "almost constants" detection
+    - `DuplicateValueTracker` - Cross-file duplicate tracking
+    - `AstContextChecker` - Node context analysis (reduced nesting depth)
+    - `AstNumberAnalyzer`, `AstStringAnalyzer`, `AstBooleanAnalyzer` - Specialized analyzers
+    - `ValuePatternMatcher` - Value type pattern detection
+
+### Removed
+
+- 🗑️ **Deprecated regex components** - Removed old regex-based detection strategies:
+  - `BraceTracker.ts` - Replaced by AST context checking
+  - `ExportConstantAnalyzer.ts` - Replaced by AstContextChecker
+  - `MagicNumberMatcher.ts` - Replaced by AstNumberAnalyzer
+  - `MagicStringMatcher.ts` - Replaced by AstStringAnalyzer
+
+### Quality
+
+- ✅ **All tests pass** - 629/629 tests passing (added 51 new tests)
+- ✅ **Test coverage** - 87.97% statements, 96.75% functions
+- ✅ **Build successful** - TypeScript compilation with no errors
+- ✅ **Linter** - 0 errors, 5 acceptable warnings (complexity, params)
+- ✅ **Code size** - Net reduction: -40 lines (more features, less code)
+
+## [0.9.0] - 2025-11-26
+
+### Added
+
+- 🏛️ **Anemic Model Detection** - NEW feature to detect anemic domain models lacking business logic:
+  - Detects entities with only getters/setters (violates DDD principles)
+  - Identifies classes with public setters (breaks encapsulation)
+  - Analyzes method-to-property ratio to find data-heavy, logic-light classes
+  - Provides detailed suggestions: add business methods, move logic from services, encapsulate invariants
+  - New `AnemicModelDetector` infrastructure component
+  - New `AnemicModelViolation` value object with rich example fixes
+  - New `IAnemicModelDetector` domain interface
+  - Integrated into CLI with detailed violation reports
+  - 12 comprehensive tests for anemic model detection
+
+- 📦 **New shared constants** - Centralized constants for better code maintainability:
+  - `CLASS_KEYWORDS` - TypeScript class and method keywords (constructor, public, private, protected)
+  - `EXAMPLE_CODE_CONSTANTS` - Documentation example code strings (ORDER_STATUS_PENDING, ORDER_STATUS_APPROVED, CANNOT_APPROVE_ERROR)
+  - `ANEMIC_MODEL_MESSAGES` - 8 suggestion messages for fixing anemic models
+
+- 📚 **Example files** - Added DDD examples demonstrating anemic vs rich domain models:
+  - `examples/bad/domain/entities/anemic-model-only-getters-setters.ts`
+  - `examples/bad/domain/entities/anemic-model-public-setters.ts`
+  - `examples/good-architecture/domain/entities/Customer.ts`
+  - `examples/good-architecture/domain/entities/Order.ts`
+
+### Changed
+
+- ♻️ **Refactored hardcoded values** - Extracted all remaining hardcoded values to centralized constants:
+  - Updated `AnemicModelDetector.ts` to use `CLASS_KEYWORDS` constants
+  - Updated `AnemicModelViolation.ts` to use `EXAMPLE_CODE_CONSTANTS` for example fix strings
+  - Replaced local constants with shared constants from `shared/constants`
+  - Improved code maintainability and consistency
+
+- 🎯 **Enhanced violation detection pipeline** - Added anemic model detection to `ExecuteDetection.ts`
+- 📊 **Updated API** - Added anemic model violations to response DTO
+- 🔧 **CLI improvements** - Added anemic model section to output formatting
+
+### Quality
+
+- ✅ **Guardian self-check** - 0 issues (was 5) - 100% clean codebase
+- ✅ **All tests pass** - 578/578 tests passing (added 12 new tests)
+- ✅ **Build successful** - TypeScript compilation with no errors
+- ✅ **Linter clean** - 0 errors, 3 acceptable warnings (complexity, params)
+- ✅ **Format verified** - All files properly formatted with 4-space indentation
+
+## [0.8.1] - 2025-11-25
+
+### Fixed
+
+- 🧹 **Code quality improvements** - Fixed all 63 hardcoded value issues detected by Guardian self-check:
+  - Fixed 1 CRITICAL: Removed hardcoded Slack token from documentation examples
+  - Fixed 1 HIGH: Removed aws-sdk framework leak from domain layer examples
+  - Fixed 4 MEDIUM: Renamed pipeline files to follow verb-noun convention
+  - Fixed 57 LOW: Extracted all magic strings to reusable constants
+
+### Added
+
+- 📦 **New constants file** - `domain/constants/SecretExamples.ts`:
+  - 32 secret keyword constants (AWS, GitHub, NPM, SSH, Slack, etc.)
+  - 15 secret type name constants
+  - 7 example secret values for documentation
+  - Regex patterns and encoding constants
+
+### Changed
+
+- ♻️ **Refactored pipeline naming** - Updated use case files to follow naming conventions:
+  - `DetectionPipeline.ts` → `ExecuteDetection.ts`
+  - `FileCollectionStep.ts` → `CollectFiles.ts`
+  - `ParsingStep.ts` → `ParseSourceFiles.ts`
+  - `ResultAggregator.ts` → `AggregateResults.ts`
+  - Added `Aggregate`, `Collect`, `Parse` to `USE_CASE_VERBS` list
+- 🔧 **Updated 3 core files to use constants**:
+  - `SecretViolation.ts`: All secret examples use constants, `getSeverity()` returns `typeof SEVERITY_LEVELS.CRITICAL`
+  - `SecretDetector.ts`: All secret keywords use constants
+  - `MagicStringMatcher.ts`: Regex patterns extracted to constants
+- 📝 **Test updates** - Updated 2 tests to match new example fix messages
+
+### Quality
+
+- ✅ **Guardian self-check** - 0 issues (was 63) - 100% clean codebase
+- ✅ **All tests pass** - 566/566 tests passing
+- ✅ **Build successful** - TypeScript compilation with no errors
+- ✅ **Linter clean** - 0 errors, 2 acceptable warnings (complexity, params)
+- ✅ **Format verified** - All files properly formatted with 4-space indentation
+
+## [0.8.0] - 2025-11-25
+
+### Added
+
+- 🔐 **Secret Detection** - NEW CRITICAL security feature using industry-standard Secretlint:
+  - Detects 350+ types of hardcoded secrets (AWS keys, GitHub tokens, NPM tokens, SSH keys, API keys, etc.)
+  - All secrets marked as **CRITICAL severity** for immediate attention
+  - Context-aware remediation suggestions for each secret type
+  - Integrated seamlessly with existing detectors
+  - New `SecretDetector` infrastructure component using `@secretlint/node`
+  - New `SecretViolation` value object with rich examples
+  - New `ISecretDetector` domain interface
+  - CLI output with "🔐 Found X hardcoded secrets - CRITICAL SECURITY RISK" section
+  - Added dependencies: `@secretlint/node`, `@secretlint/core`, `@secretlint/types`, `@secretlint/secretlint-rule-preset-recommend`
+
+### Changed
+
+- 🔄 **Pipeline async support** - `DetectionPipeline.execute()` now async for secret detection
+- 📊 **Test suite expanded** - Added 47 new tests (23 for SecretViolation, 24 for SecretDetector)
+  - Total: 566 tests (was 519), 100% pass rate
+  - Coverage: 93.3% statements, 83.74% branches, 98.17% functions
+  - SecretViolation: 100% coverage
+- 📝 **Documentation updated**:
+  - README.md: Added Secret Detection section with examples
+  - ROADMAP.md: Marked v0.8.0 as released
+  - Updated package description to mention secrets detection
+
+### Security
+
+- 🛡️ **Prevents credentials in version control** - catches AWS, GitHub, NPM, SSH, Slack, GCP secrets before commit
+- ⚠️ **CRITICAL violations** - all hardcoded secrets immediately flagged with highest severity
+- 💡 **Smart remediation** - provides specific guidance per secret type (environment variables, secret managers, etc.)
+
+## [0.7.9] - 2025-11-25
+
+### Changed
+
+- ♻️ **Refactored large detectors** - significantly improved maintainability and reduced complexity:
+  - **AggregateBoundaryDetector**: Reduced from 381 to 162 lines (57% reduction)
+  - **HardcodeDetector**: Reduced from 459 to 89 lines (81% reduction)
+  - **RepositoryPatternDetector**: Reduced from 479 to 106 lines (78% reduction)
+  - Extracted 13 focused strategy classes for single responsibilities
+  - All 519 tests pass, no breaking changes
+  - Zero ESLint errors (1 pre-existing warning unrelated to refactoring)
+  - Improved code organization and separation of concerns
+
+### Added
+
+- 🏗️ **13 new strategy classes** for focused responsibilities:
+  - `FolderRegistry` - Centralized DDD folder name management
+  - `AggregatePathAnalyzer` - Path parsing and aggregate extraction
+  - `ImportValidator` - Import validation logic
+  - `BraceTracker` - Brace and bracket counting
+  - `ConstantsFileChecker` - Constants file detection
+  - `ExportConstantAnalyzer` - Export const analysis
+  - `MagicNumberMatcher` - Magic number detection
+  - `MagicStringMatcher` - Magic string detection
+  - `OrmTypeMatcher` - ORM type matching
+  - `MethodNameValidator` - Repository method validation
+  - `RepositoryFileAnalyzer` - File role detection
+  - `RepositoryViolationDetector` - Violation detection logic
+  - Enhanced testability with smaller, focused classes
+
+### Improved
+
+- 📊 **Code quality metrics**:
+  - Reduced cyclomatic complexity across all three detectors
+  - Better separation of concerns with strategy pattern
+  - More maintainable and extensible codebase
+  - Easier to add new detection patterns
+  - Improved code readability and self-documentation
+
+## [0.7.8] - 2025-11-25
+
+### Added
+
+- 🧪 **Comprehensive E2E test suite** - full pipeline and CLI integration tests:
+  - Added `tests/e2e/AnalyzeProject.e2e.test.ts` - 21 tests for full analysis pipeline
+  - Added `tests/e2e/CLI.e2e.test.ts` - 22 tests for CLI command execution and output
+  - Added `tests/e2e/JSONOutput.e2e.test.ts` - 19 tests for JSON structure validation
+  - Total of 62 new E2E tests covering all major use cases
+  - Tests validate `examples/good-architecture/` returns zero violations
+  - Tests validate `examples/bad/` detects specific violations
+  - CLI smoke tests with process spawning and output verification
+  - JSON serialization and structure validation for all violation types
+  - Total test count increased from 457 to 519 tests
+  - **100% test pass rate achieved** 🎉 (519/519 tests passing)
+
+### Changed
+
+- 🔧 **Improved test robustness**:
+  - E2E tests handle exit codes gracefully (CLI exits with non-zero when violations found)
+  - Added helper function `runCLI()` for consistent error handling
+  - Made validation tests conditional for better reliability
+  - Fixed metrics structure assertions to match actual implementation
+  - Enhanced error handling in CLI process spawning tests
+
+### Fixed
+
+- 🐛 **Test reliability improvements**:
+  - Fixed CLI tests expecting zero exit codes when violations present
+  - Updated metrics assertions to use correct field names (totalFiles, totalFunctions, totalImports, layerDistribution)
+  - Corrected violation structure property names in E2E tests
+  - Made bad example tests conditional to handle empty results gracefully
+
+## [0.7.7] - 2025-11-25
+
+### Added
+
+- 🧪 **Comprehensive test coverage for under-tested domain files**:
+  - Added 31 tests for `SourceFile.ts` - coverage improved from 46% to 100%
+  - Added 31 tests for `ProjectPath.ts` - coverage improved from 50% to 100%
+  - Added 18 tests for `ValueObject.ts` - coverage improved from 25% to 100%
+  - Added 32 tests for `RepositoryViolation.ts` - coverage improved from 58% to 92.68%
+  - Total test count increased from 345 to 457 tests
+  - Overall coverage improved to 95.4% statements, 86.25% branches, 96.68% functions
+  - All tests pass with no breaking changes
+
+### Changed
+
+- 📊 **Improved code quality and maintainability**:
+  - Enhanced test suite for core domain entities and value objects
+  - Better coverage of edge cases and error handling
+  - Increased confidence in domain layer correctness
+
+## [0.7.6] - 2025-11-25
+
+### Changed
+
+- ♻️ **Refactored CLI module** - improved maintainability and separation of concerns:
+  - Split 484-line `cli/index.ts` into focused modules
+  - Created `cli/groupers/ViolationGrouper.ts` for severity grouping and filtering (29 lines)
+  - Created `cli/formatters/OutputFormatter.ts` for violation formatting (190 lines)
+  - Created `cli/formatters/StatisticsFormatter.ts` for metrics and summary (58 lines)
+  - Reduced `cli/index.ts` from 484 to 260 lines (46% reduction)
+  - All 345 tests pass, CLI output identical to before
+  - No breaking changes
+
+## [0.7.5] - 2025-11-25
+
+### Changed
+
+- ♻️ **Refactored AnalyzeProject use-case** - improved maintainability and testability:
+  - Split 615-line God Use-Case into focused pipeline components
+  - Created `FileCollectionStep.ts` for file scanning and basic parsing (66 lines)
+  - Created `ParsingStep.ts` for AST parsing and dependency graph construction (51 lines)
+  - Created `DetectionPipeline.ts` for running all 7 detectors (371 lines)
+  - Created `ResultAggregator.ts` for building response DTO (81 lines)
+  - Reduced `AnalyzeProject.ts` from 615 to 245 lines (60% reduction)
+  - All 345 tests pass, no breaking changes
+  - Improved separation of concerns and single responsibility
+  - Easier to test and modify individual pipeline steps
+
+### Added
+
+- 🤖 **AI Agent Instructions in CLI help** - dedicated section for AI coding assistants:
+  - Step-by-step workflow: scan → fix → verify → expand scope
+  - Recommended commands for each step (`--only-critical --limit 5`)
+  - Output format description for easy parsing
+  - Priority order guidance (CRITICAL → HIGH → MEDIUM → LOW)
+  - Helps Claude, Copilot, Cursor, and other AI agents immediately take action
+
+Run `guardian --help` to see the new "AI AGENT INSTRUCTIONS" section.
+
+## [0.7.4] - 2025-11-25
+
+### Fixed
+
+- 🐛 **TypeScript-aware hardcode detection** - dramatically reduces false positives by 35.7%:
+  - Ignore strings in TypeScript union types (`type Status = 'active' | 'inactive'`)
+  - Ignore strings in interface property types (`interface { mode: 'development' | 'production' }`)
+  - Ignore strings in type assertions (`as 'read' | 'write'`)
+  - Ignore strings in typeof checks (`typeof x === 'string'`)
+  - Ignore strings in Symbol() calls for DI tokens (`Symbol('LOGGER')`)
+  - Ignore strings in dynamic import() calls (`import('../../module.js')`)
+  - Exclude tokens.ts/tokens.js files completely (DI container files)
+  - Tested on real-world TypeScript project: 985 → 633 issues (352 false positives eliminated)
+- ✅ **Added 13 new tests** for TypeScript type context filtering
+
+## [0.7.3] - 2025-11-25
+
+### Fixed
+
+- 🐛 **False positive: repository importing its own aggregate:**
+  - Added `isInternalBoundedContextImport()` method to detect internal imports
+  - Imports like `../aggregates/Entity` from `repositories/Repo` are now allowed
+  - This correctly allows `ICodeProjectRepository` to import `CodeProject` from the same bounded context
+  - Cross-aggregate imports (with multiple `../..`) are still detected as violations
+
+## [0.7.2] - 2025-11-25
+
+### Fixed
+
+- 🐛 **False positive: `errors` folder detected as aggregate:**
+  - Added `errors` and `exceptions` to `DDD_FOLDER_NAMES` constants
+  - Added to `nonAggregateFolderNames` — these folders are no longer detected as aggregates
+  - Added to `allowedFolderNames` — imports from `errors`/`exceptions` folders are allowed across aggregates
+  - Fixes issue where `domain/code-analysis/errors/` was incorrectly identified as a separate aggregate named "errors"
+
+## [0.7.1] - 2025-11-25
+
+### Fixed
+
+- 🐛 **Aggregate Boundary Detection for relative paths:**
+  - Fixed regex pattern to support paths starting with `domain/` (without leading `/`)
+  - Now correctly detects violations in projects scanned from parent directories
+
+- 🐛 **Reduced false positives in Repository Pattern detection:**
+  - Removed `findAll`, `exists`, `count` from ORM technical methods blacklist
+  - These are now correctly recognized as valid domain method names
+  - Added `exists`, `count`, `countBy[A-Z]` to domain method patterns
+
+- 🐛 **Non-aggregate folder exclusions:**
+  - Added exclusions for standard DDD folders: `constants`, `shared`, `factories`, `ports`, `interfaces`
+  - Prevents false positives when domain layer has shared utilities
+
+### Changed
+
+- ♻️ **Extracted magic strings to constants:**
+  - DDD folder names (`entities`, `aggregates`, `value-objects`, etc.) moved to `DDD_FOLDER_NAMES`
+  - Repository method suggestions moved to `REPOSITORY_METHOD_SUGGESTIONS`
+  - Fallback suggestions moved to `REPOSITORY_FALLBACK_SUGGESTIONS`
+
+### Added
+
+- 📁 **Aggregate boundary test examples:**
+  - Added `examples/aggregate-boundary/domain/` with Order, User, Product aggregates
+  - Demonstrates cross-aggregate entity reference violations
+
+## [0.7.0] - 2025-11-25
+
+### Added
+
+**🔒 Aggregate Boundary Validation**
+
+New DDD feature to enforce aggregate boundaries and prevent tight coupling between aggregates.
+
+- ✅ **Aggregate Boundary Detector:**
+  - Detects direct entity references across aggregate boundaries
+  - Validates that aggregates reference each other only by ID or Value Objects
+  - Supports multiple folder structure patterns:
+    - `domain/aggregates/order/Order.ts`
+    - `domain/order/Order.ts`
+    - `domain/entities/order/Order.ts`
+
+- ✅ **Smart Import Analysis:**
+  - Parses ES6 imports and CommonJS require statements
+  - Identifies entity imports from other aggregates
+  - Allows imports from value-objects, events, services, specifications folders
+
+- ✅ **Actionable Suggestions:**
+  - Reference by ID instead of entity
+  - Use Value Objects to store needed data from other aggregates
+  - Maintain aggregate independence
+
+- ✅ **CLI Integration:**
+  - `--architecture` flag includes aggregate boundary checks
+  - CRITICAL severity for violations
+  - Detailed violation messages with file:line references
+
+- ✅ **Test Coverage:**
+  - 41 new tests for aggregate boundary detection
+  - 333 total tests passing (100% pass rate)
+  - Examples in `examples/aggregate-boundary/`
+
+### Technical
+
+- New `AggregateBoundaryDetector` in infrastructure layer
+- New `AggregateBoundaryViolation` value object in domain layer
+- New `IAggregateBoundaryDetector` interface for dependency inversion
+- Integrated into `AnalyzeProject` use case
+
+## [0.6.4] - 2025-11-24
+
+### Added
+
+**🎯 Smart Context-Aware Suggestions for Repository Method Names**
+
+Guardian now provides intelligent, context-specific suggestions when it detects non-domain method names in repositories.
+
+- ✅ **Intelligent method name analysis:**
+  - `queryUsers()` → Suggests: `search`, `findBy[Property]`
+  - `selectById()` → Suggests: `findBy[Property]`, `get[Entity]`
+  - `insertUser()` → Suggests: `create`, `add[Entity]`, `store[Entity]`
+  - `updateRecord()` → Suggests: `update`, `modify[Entity]`
+  - `upsertUser()` → Suggests: `save`, `store[Entity]`
+  - `removeUser()` → Suggests: `delete`, `removeBy[Property]`
+  - `fetchUserData()` → Suggests: `findBy[Property]`, `get[Entity]`
+  - And more technical patterns detected automatically!
+
+- 🎯 **Impact:**
+  - Developers get actionable, relevant suggestions instead of generic examples
+  - Faster refactoring with specific naming alternatives
+  - Better learning experience for developers new to DDD
+
+### Fixed
+
+- ✅ **Expanded domain method patterns support:**
+  - `find*()` methods - e.g., `findNodes()`, `findNodeById()`, `findSimilar()`
+  - `saveAll()` - batch save operations
+  - `deleteBy*()` methods - e.g., `deleteByPath()`, `deleteById()`
+  - `deleteAll()` - clear all entities
+  - `add*()` methods - e.g., `addRelationship()`, `addItem()`
+  - `initializeCollection()` - collection initialization
+
+- 🐛 **Removed `findAll` from technical methods blacklist:**
+  - `findAll()` is now correctly recognized as a standard domain method
+  - Reduced false positives for repositories using this common pattern
+
+### Technical
+
+- Added `suggestDomainMethodName()` method in `RepositoryPatternDetector.ts` with keyword-based suggestion mapping
+- Updated `getNonDomainMethodSuggestion()` in `RepositoryViolation.ts` to extract and use smart suggestions
+- Refactored suggestion logic to reduce cyclomatic complexity (22 → 9)
+- Enhanced `domainMethodPatterns` with 9 additional patterns
+- All 333 tests passing
+
+## [0.6.3] - 2025-11-24
+
+### Fixed
+
+**🐛 Repository Pattern Detection - Reduced False Positives**
+
+Fixed overly strict repository method name validation that was flagging valid DDD patterns as violations.
+
+- ✅ **Added support for common DDD repository patterns:**
+  - `has*()` methods - e.g., `hasProject()`, `hasPermission()`
+  - `is*()` methods - e.g., `isCached()`, `isActive()`
+  - `exists*()` methods - e.g., `existsById()`, `existsByEmail()`
+  - `clear*()` methods - e.g., `clearCache()`, `clearAll()`
+  - `store*()` methods - e.g., `storeMetadata()`, `storeFile()`
+  - Lifecycle methods: `initialize()`, `close()`, `connect()`, `disconnect()`
+
+- 🎯 **Impact:**
+  - Reduced false positives in real-world DDD projects
+  - Better alignment with Domain-Driven Design best practices
+  - More practical for cache repositories, connection management, and business queries
+
+- 📚 **Why these patterns are valid:**
+  - Martin Fowler's Repository Pattern allows domain-specific query methods
+  - DDD recommends using ubiquitous language in method names
+  - Lifecycle methods are standard for resource management in repositories
+
+### Technical
+
+- Updated `domainMethodPatterns` in `RepositoryPatternDetector.ts` with 11 additional valid patterns
+- All existing functionality remains unchanged
+
+## [0.6.2] - 2025-11-24
+
+### Added
+
+**📚 Research-Backed Documentation**
+
+Guardian's detection rules are now backed by scientific research and industry standards!
+
+- ✅ **New Documentation**
+  - `docs/WHY.md` - User-friendly explanations for each rule with authoritative sources
+  - `docs/RESEARCH_CITATIONS.md` - Complete academic and industry references (551 lines)
+  - Organized by detection type with quick navigation
+
+- ✅ **Micro-Citations in README**
+  - Each feature now includes one-line citation with "Why?" link
+  - Examples: "Based on MIT 6.031, SonarQube RSPEC-109"
+  - Non-intrusive, opt-in for users who want to learn more
+
+- ✅ **CLI Help Enhancement**
+  - Added "BACKED BY RESEARCH" section to `--help` output
+  - Mentions MIT, Martin Fowler, Robert C. Martin, industry standards
+  - Link to full documentation
+
+### Changed
+
+- **Documentation Structure**: Moved `RESEARCH_CITATIONS.md` to `docs/` directory for better organization
+- **All internal links updated** to reflect new documentation structure
+
+### Backed By
+
+Our rules are supported by:
+- 🎓 **Academia**: MIT Course 6.031, ScienceDirect peer-reviewed studies
+- 📚 **Books**: Clean Architecture (Martin 2017), DDD (Evans 2003), Enterprise Patterns (Fowler 2002)
+- 🏢 **Industry**: Google, Microsoft, Airbnb style guides, SonarQube standards
+- 👨‍🏫 **Experts**: Martin Fowler, Robert C. Martin, Eric Evans, Alistair Cockburn
+
+## [0.6.1] - 2025-11-24
+
+### Improved
+
+**📖 Enhanced CLI Help System**
+
+Guardian's `--help` command is now comprehensive and AI-agent-friendly!
+
+- ✅ **Detailed Main Help**
+  - Complete detector descriptions with quick fix instructions
+  - Severity level explanations (CRITICAL → LOW)
+  - Step-by-step workflow guide for fixing violations
+  - 7 practical usage examples
+  - "HOW TO FIX COMMON ISSUES" reference section
+
+- ✅ **Better Organization**
+  - Clear DETECTS section with all 8 violation types
+  - Each detector includes → what to do to fix it
+  - Severity system with priority guidance
+  - Examples cover all major use cases
+
+- ✅ **AI Agent Ready**
+  - Help output provides complete context for autonomous agents
+  - Actionable instructions for each violation type
+  - Clear workflow: run → review → fix → verify
+
+### Fixed
+
+- **Code Quality**: Extracted all hardcoded strings from help text to constants
+  - Moved 17 magic strings to `CLI_HELP_TEXT` constant
+  - Improved maintainability and i18n readiness
+  - Follows Clean Code principles (Single Source of Truth)
+
+### Technical
+
+- All CLI help strings now use `CLI_HELP_TEXT` from constants
+- Zero hardcode violations in Guardian's own codebase
+- Passes all quality checks (format, lint, build, self-check)
+
+## [0.6.0] - 2025-11-24
+
+### Added
+
+**🎯 Output Limit Control**
+
+Guardian now supports limiting detailed violation output for large codebases!
+
+- ✅ **--limit Option**
+  - Limit detailed violation output per category: `guardian check src --limit 10`
+  - Short form: `-l <number>`
+  - Works with severity filters: `guardian check src --only-critical --limit 5`
+  - Shows warning when violations exceed limit
+  - Full statistics always displayed
+
+**📋 Severity Display Constants**
+
+- Extracted severity labels and headers to reusable constants
+- Improved CLI maintainability and consistency
+- `SEVERITY_DISPLAY_LABELS` and `SEVERITY_SECTION_HEADERS`
+
+**📚 Complete Development Workflow**
+
+- Added comprehensive workflow documentation to CLAUDE.md
+- 6-phase development process (Planning → Quality → Documentation → Verification → Commit → Publication)
+- Quick checklists for new features
+- Common workflows and debugging tips
+
+### Changed
+
+- **ESLint Configuration**: Optimized with CLI-specific overrides, reduced warnings from 129 to 0
+- **Documentation**: Updated README with all 8 detector types and latest statistics
+- **TODO**: Added technical debt tracking for low-coverage files
+
+### Fixed
+
+- Removed unused `SEVERITY_LEVELS` import from AnalyzeProject.ts
+- Fixed unused `fileName` variable in HardcodeDetector.ts
+- Replaced `||` with `??` for nullish coalescing
+
+### Removed
+
+- Deleted unused `IBaseRepository` interface (dead code)
+- Fixed repository pattern violations detected by Guardian on itself
+
+### Technical Details
+
+- All 292 tests passing (100% pass rate)
+- Coverage: 90.63% statements, 82.19% branches, 83.51% functions
+- ESLint: 0 errors, 0 warnings
+- Guardian self-check: ✅ No issues found
+- No breaking changes - fully backwards compatible
+
+## [0.5.2] - 2025-11-24
+
+### Added
+
+**🎯 Severity-Based Prioritization**
+
+Guardian now intelligently prioritizes violations by severity, helping teams focus on critical issues first!
+
+- ✅ **Severity Levels**
+  - 🔴 **CRITICAL**: Circular dependencies, Repository pattern violations
+  - 🟠 **HIGH**: Dependency direction violations, Framework leaks, Entity exposures
+  - 🟡 **MEDIUM**: Naming violations, Architecture violations
+  - 🟢 **LOW**: Hardcoded values
+
+- ✅ **Automatic Sorting**
+  - All violations automatically sorted by severity (most critical first)
+  - Applied in AnalyzeProject use case before returning results
+  - Consistent ordering across all detection types
+
+- ✅ **CLI Filtering Options**
+  - `--min-severity <level>` - Show only violations at specified level and above
+  - `--only-critical` - Quick filter for critical issues only
+  - Examples:
+    - `guardian check src --only-critical`
+    - `guardian check src --min-severity high`
+
+- ✅ **Enhanced CLI Output**
+  - Color-coded severity labels (🔴🟠🟡🟢)
+  - Visual severity group headers with separators
+  - Severity displayed for each violation
+  - Clear filtering messages when filters active
+
+### Changed
+
+- Updated all violation interfaces to include `severity: SeverityLevel` field
+- Improved CLI presentation with grouped severity display
+- Enhanced developer experience with visual prioritization
+
+### Technical Details
+
+- All 292 tests passing (100% pass rate)
+- Coverage: 90.63% statements, 82.19% branches, 83.51% functions
+- No breaking changes - fully backwards compatible
+- Clean Architecture principles maintained
+
+---
+
+## [0.5.1] - 2025-11-24
+
+### Changed
+
+**🧹 Code Quality Refactoring**
+
+Major internal refactoring to eliminate hardcoded values and improve maintainability - Guardian now fully passes its own quality checks!
+
+- ✅ **Extracted Constants**
+  - All RepositoryViolation messages moved to domain constants (Messages.ts)
+  - All framework leak template strings centralized
+  - All layer paths moved to infrastructure constants (paths.ts)
+  - All regex patterns extracted to IMPORT_PATTERNS constant
+  - 30+ new constants added for better maintainability
+
+- ✅ **New Constants Files**
+  - `src/infrastructure/constants/paths.ts` - Layer paths, CLI paths, import patterns
+  - Extended `src/domain/constants/Messages.ts` - 25+ repository pattern messages
+  - Extended `src/shared/constants/rules.ts` - Package placeholder constant
+
+- ✅ **Self-Validation Achievement**
+  - Reduced hardcoded values from 37 to 1 (97% improvement)
+  - Guardian now passes its own `src/` directory checks with 0 violations
+  - Only acceptable hardcode remaining: bin/guardian.js entry point path
+  - All 292 tests still passing (100% pass rate)
+
+- ✅ **Improved Code Organization**
+  - Better separation of concerns
+  - More maintainable codebase
+  - Easier to extend with new features
+  - Follows DRY principle throughout
+
+### Technical Details
+
+- No breaking changes - fully backwards compatible
+- All functionality preserved
+- Test suite: 292 tests passing
+- Coverage: 96.77% statements, 83.82% branches
+
+---
+
+## [0.5.0] - 2025-11-24
+
+### Added
+
+**📚 Repository Pattern Validation**
+
+Validate proper implementation of the Repository Pattern to ensure domain remains decoupled from infrastructure.
+
+- ✅ **ORM Type Detection in Interfaces**
+  - Detects ORM-specific types (Prisma, TypeORM, Mongoose) in domain repository interfaces
+  - Ensures repository interfaces remain persistence-agnostic
+  - Supports detection of 25+ ORM type patterns
+  - Provides fix suggestions with clean domain examples
+
+- ✅ **Concrete Repository Usage Detection**
+  - Identifies use cases depending on concrete repository implementations
+  - Enforces Dependency Inversion Principle
+  - Validates constructor and field dependency types
+  - Suggests using repository interfaces instead
+
+- ✅ **Repository Instantiation Detection**
+  - Detects `new Repository()` in use cases
+  - Enforces Dependency Injection pattern
+  - Identifies hidden dependencies
+  - Provides DI container setup guidance
+
+- ✅ **Domain Language Validation**
+  - Checks repository methods use domain terminology
+  - Rejects technical database terms (findOne, insert, query, execute)
+  - Promotes ubiquitous language across codebase
+  - Suggests business-oriented method names
+
+- ✅ **Smart Violation Reporting**
+  - RepositoryViolation value object with detailed context
+  - Four violation types: ORM types, concrete repos, new instances, technical names
+  - Provides actionable fix suggestions
+  - Shows before/after code examples
+
+- ✅ **Comprehensive Test Coverage**
+  - 31 new tests for repository pattern detection
+  - 292 total tests passing (100% pass rate)
+  - Integration tests for multiple violation types
+  - 96.77% statement coverage, 83.82% branch coverage
+
+- ✅ **Documentation & Examples**
+  - 6 example files (3 bad patterns, 3 good patterns)
+  - Comprehensive README with patterns and principles
+  - Examples for ORM types, concrete repos, DI, and domain language
+  - Demonstrates Clean Architecture and SOLID principles
+
+### Changed
+
+- Updated test count: 261 → 292 tests
+- Added REPOSITORY_PATTERN rule to constants
+- Extended AnalyzeProject use case with repository pattern detection
+- Added REPOSITORY_VIOLATION_TYPES constant with 4 violation types
+- ROADMAP updated with completed repository pattern validation (v0.5.0)
+
+---
+
+## [0.4.0] - 2025-11-24
+
+### Added
+
+**🔀 Dependency Direction Enforcement**
+
+Enforce Clean Architecture dependency rules to prevent architectural violations across layers.
+
+- ✅ **Dependency Direction Detector**
+  - Validates that dependencies flow in the correct direction
+  - Domain layer can only import from Domain and Shared
+  - Application layer can only import from Domain, Application, and Shared
+  - Infrastructure layer can import from all layers
+  - Shared layer can be imported by all layers
+
+- ✅ **Smart Violation Reporting**
+  - DependencyViolation value object with detailed context
+  - Provides fix suggestions with concrete examples
+  - Shows both violating import and suggested layer placement
+  - CLI output with severity indicators
+
+- ✅ **Comprehensive Test Coverage**
+  - 43 new tests for dependency direction detection
+  - 100% test pass rate (261 total tests)
+  - Examples for both good and bad architecture patterns
+
+- ✅ **Documentation & Examples**
+  - Good architecture examples for all layers
+  - Bad architecture examples showing common violations
+  - Demonstrates proper layer separation
+
+### Changed
+
+- Updated test count: 218 → 261 tests
+- Optimized extractLayerFromImport method to reduce complexity
+- Updated getExampleFix to avoid false positives
+- ROADMAP updated with completed dependency direction feature
+
+---
+
+## [0.3.0] - 2025-11-24
+
+### Added
+
+**🚫 Entity Exposure Detection**
+
+Prevent domain entities from leaking to API responses, enforcing proper DTO usage at boundaries.
+
+- ✅ **Entity Exposure Detector**
+  - Detects when controllers/routes return domain entities instead of DTOs
+  - Scans infrastructure layer (controllers, routes, handlers, resolvers, gateways)
+  - Identifies PascalCase entities without Dto/Request/Response suffixes
+  - Parses async methods with Promise<T> return types
+
+- ✅ **Smart Remediation Suggestions**
+  - EntityExposure value object with step-by-step fix guidance
+  - Suggests creating DTOs with proper naming
+  - Provides mapper implementation examples
+  - Shows how to separate domain from presentation concerns
+
+- ✅ **Comprehensive Test Coverage**
+  - 24 new tests for entity exposure detection (98% coverage)
+  - EntityExposureDetector: 98.07% coverage
+  - Overall project: 90.6% statements, 83.97% branches
+
+- ✅ **Documentation & Examples**
+  - BadUserController and BadOrderController examples
+  - GoodUserController showing proper DTO usage
+  - Integration with CLI for helpful output
+
+### Changed
+
+- Updated test count: 194 → 218 tests
+- Added entity exposure to violation pipeline
+- ROADMAP updated with completed entity exposure feature
+
+---
+
+## [0.2.0] - 2025-11-24
+
+### Added
+
+**🔌 Framework Leak Detection**
+
+Major new feature to detect framework-specific imports in domain layer, ensuring Clean Architecture compliance.
+
+- ✅ **Framework Leak Detector**
+  - Detects 250+ framework patterns across 12 categories
+  - HTTP frameworks: Express, Fastify, Koa, Hapi, NestJS, etc.
+  - ORMs/Databases: Prisma, TypeORM, Sequelize, Mongoose, Drizzle, etc.
+  - Loggers: Winston, Pino, Bunyan, Log4js, etc.
+  - Caches: Redis, IORedis, Memcached, etc.
+  - Message Queues: Bull, BullMQ, KafkaJS, RabbitMQ, etc.
+  - And 7 more categories (HTTP clients, validation, DI, email, storage, testing, templates)
+
+- ✅ **Smart Violation Reporting**
+  - Framework type categorization
+  - Detailed suggestions for proper abstraction
+  - CLI output with severity indicators
+  - Integration with existing violation pipeline
+
+- ✅ **Comprehensive Test Coverage**
+  - 35 new tests for framework leak detection
+  - 100% coverage of detection logic
+  - Examples for all major framework types
+
+- ✅ **Documentation & Examples**
+  - New bad architecture examples showing framework leaks
+  - Updated README with framework leak detection section
+  - Integration guides for preventing framework coupling
+
+### Changed
+
+- Updated test count: 159 → 194 tests across 7 files
+- Updated examples: 36 → 38 files (29 good + 9 bad)
+- CLI now reports 5 types of violations (added framework leaks)
+
+---
+
 ## [0.1.0] - 2025-11-24

 ### Added
@@ -93,7 +1002,7 @@ Code quality guardian for vibe coders and enterprise teams - your AI coding comp
 #### Developer Experience

 - 🤖 **Built for AI-Assisted Development**
-  - Perfect companion for Claude, GPT, Copilot, Cursor
+  - Perfect companion for GitHub Copilot, Cursor, Windsurf, Claude, ChatGPT, Cline
  - Catches common AI code smells (hardcoded values, architecture violations)
  - Educational error messages with fix suggestions
  - Designed for vibe coding workflow: AI writes → Guardian reviews → AI fixes → Ship
@@ -192,7 +1101,6 @@ Code quality guardian for vibe coders and enterprise teams - your AI coding comp
 ## Future Releases

 Planned features for upcoming versions:
- Entity exposure detection (domain entities in presentation layer)
 - Configuration file support (.guardianrc)
 - Custom rule definitions
 - Plugin system
--- a/packages/guardian/README.md
+++ b/packages/guardian/README.md
@@ -8,7 +8,7 @@ Code quality guardian for vibe coders and enterprise teams - because AI writes f
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

 > **Perfect for:**
-> - 🚀 **Vibe Coders**: Ship fast with Claude, GPT, Copilot while maintaining quality
+> - 🚀 **Vibe Coders**: Ship fast with GitHub Copilot, Cursor, Windsurf, Claude, ChatGPT while maintaining quality
 > - 🏢 **Enterprise Teams**: Enforce architectural standards and code quality at scale
 > - 📚 **Code Review Automation**: Catch issues before human reviewers see them

@@ -19,12 +19,16 @@ Code quality guardian for vibe coders and enterprise teams - because AI writes f
 - 📝 Magic strings (URLs, connection strings, etc.)
 - 🎯 Smart context analysis
 - 💡 Automatic constant name suggestions
+- 📍 Suggested location for constants
+- 📚 *Based on: MIT 6.031, SonarQube RSPEC-109, peer-reviewed research* → [Why?](./docs/WHY.md#hardcode-detection)

 🔄 **Circular Dependency Detection**
 - Detects import cycles in your codebase
 - Shows complete dependency chain
 - Helps maintain clean architecture
 - Prevents maintenance nightmares
+- Severity-based reporting
+- 📚 *Based on: Martin Fowler's architecture patterns, Shopify Engineering* → [Why?](./docs/WHY.md#circular-dependencies)

 📝 **Naming Convention Detection**
 - Layer-based naming rules enforcement
@@ -33,6 +37,7 @@ Code quality guardian for vibe coders and enterprise teams - because AI writes f
 - Infrastructure: Controllers (*Controller), Repositories (*Repository), Services (*Service/*Adapter)
 - Smart exclusions for base classes
 - Helpful fix suggestions
+- 📚 *Based on: Google Style Guide, Airbnb JavaScript Style Guide, Microsoft Guidelines* → [Why?](./docs/WHY.md#naming-conventions)

 🔌 **Framework Leak Detection**
 - Detects framework-specific imports in domain layer
@@ -41,6 +46,67 @@ Code quality guardian for vibe coders and enterprise teams - because AI writes f
 - Detects external service dependencies (AWS SDK, Firebase, Stripe, Twilio)
 - Maintains clean domain boundaries
 - Prevents infrastructure coupling in business logic
+- 📚 *Based on: Hexagonal Architecture (Cockburn 2005), Clean Architecture (Martin 2017)* → [Why?](./docs/WHY.md#framework-leaks)
+
+🎭 **Entity Exposure Detection**
+- Detects domain entities exposed in API responses
+- Prevents data leakage through direct entity returns
+- Enforces DTO/Response object usage
+- Layer-aware validation
+- Smart suggestions for proper DTOs
+- 📚 *Based on: Martin Fowler's Enterprise Patterns (2002)* → [Why?](./docs/WHY.md#entity-exposure)
+
+⬆️ **Dependency Direction Enforcement**
+- Validates Clean Architecture layer dependencies
+- Domain → Application → Infrastructure flow
+- Prevents backwards dependencies
+- Maintains architectural boundaries
+- Detailed violation reports
+- 📚 *Based on: Robert C. Martin's Dependency Rule, SOLID principles* → [Why?](./docs/WHY.md#clean-architecture)
+
+📦 **Repository Pattern Validation**
+- Validates repository interface design
+- Detects ORM/technical types in interfaces
+- Checks for technical method names (findOne, save, etc.)
+- Enforces domain language usage
+- Prevents "new Repository()" anti-pattern
+- 📚 *Based on: Martin Fowler's Repository Pattern, DDD (Evans 2003)* → [Why?](./docs/WHY.md#repository-pattern)
+
+🔒 **Aggregate Boundary Validation**
+- Detects direct entity references across DDD aggregates
+- Enforces reference-by-ID or Value Object pattern
+- Prevents tight coupling between aggregates
+- Supports multiple folder structures (domain/aggregates/*, domain/*, domain/entities/*)
+- Filters allowed imports (value-objects, events, repositories, services)
+- Critical severity for maintaining aggregate independence
+- 📚 *Based on: Domain-Driven Design (Evans 2003), Implementing DDD (Vernon 2013)* → [Why?](./docs/WHY.md#aggregate-boundary-validation)
+
+🔐 **Secret Detection** ✨ NEW in v0.8.0
+- Detects 350+ types of hardcoded secrets using industry-standard Secretlint
+- Catches AWS keys, GitHub tokens, NPM tokens, SSH keys, API keys, and more
+- All secrets marked as **CRITICAL severity** - immediate security risk
+- Context-aware remediation suggestions for each secret type
+- Prevents credentials from reaching version control
+- Integrates seamlessly with existing detectors
+- 📚 *Based on: OWASP Secrets Management, GitHub Secret Scanning (350+ patterns), security standards* → [Why?](./docs/WHY.md#secret-detection)
+
+🩺 **Anemic Domain Model Detection** ✨ NEW in v0.9.0
+- Detects entities with only getters/setters (data bags without behavior)
+- Identifies public setters anti-pattern in domain entities
+- Calculates methods-to-properties ratio for behavioral analysis
+- Enforces rich domain models over anemic models
+- Suggests moving business logic from services to entities
+- Medium severity - architectural code smell
+- 📚 *Based on: Martin Fowler's "Anemic Domain Model" (2003), DDD (Evans 2003), Transaction Script vs Domain Model patterns* → [Why?](./docs/WHY.md#anemic-domain-model-detection)
+
+🎯 **Severity-Based Prioritization**
+- Automatic sorting by severity: CRITICAL → HIGH → MEDIUM → LOW
+- Filter by severity level: `--only-critical` or `--min-severity high`
+- Focus on what matters most: secrets and circular dependencies first
+- Visual severity indicators with color-coded labels (🔴🟠🟡🟢)
+- Smart categorization based on impact to production
+- Enables gradual technical debt reduction
+- 📚 *Based on: SonarQube severity classification, IEEE/ScienceDirect research on Technical Debt prioritization* → [Why?](./docs/WHY.md#severity-based-prioritization)

 🏗️ **Clean Architecture Enforcement**
 - Built with DDD principles
@@ -48,6 +114,7 @@ Code quality guardian for vibe coders and enterprise teams - because AI writes f
 - TypeScript with strict type checking
 - Fully tested (80%+ coverage)
 - Enforces architectural boundaries across teams
+- 📚 *Based on: Clean Architecture (Martin 2017), Domain-Driven Design (Evans 2003)* → [Why?](./docs/WHY.md#clean-architecture)

 🚀 **Developer & Enterprise Friendly**
 - Simple API for developers
@@ -64,11 +131,11 @@ Code quality guardian for vibe coders and enterprise teams - because AI writes f
 - 🏗️ Enforces Clean Architecture that AI often ignores
 - 💡 Smart suggestions you can feed back to your AI assistant
 - 🔄 Closes the feedback loop: better prompts = cleaner AI code
- 🚀 Works with Claude, GPT, Copilot, Cursor, and any AI tool
+- 🚀 Works with GitHub Copilot, Cursor, Windsurf, Claude, ChatGPT, Cline, and any AI tool

 ## Why Guardian for Vibe Coding?

-**The Problem:** AI assistants (Claude, GPT, Copilot) are incredible at shipping features fast, but they love hardcoding values and sometimes ignore architectural patterns. You're moving fast, but accumulating tech debt.
+**The Problem:** AI assistants (GitHub Copilot, Cursor, Windsurf, Claude, ChatGPT) are incredible at shipping features fast, but they love hardcoding values and sometimes ignore architectural patterns. You're moving fast, but accumulating tech debt.

 **The Solution:** Guardian is your quality safety net. Code with AI at full speed, then let Guardian catch the issues before they hit production.

@@ -258,17 +325,6 @@ await reportMetrics({
 | **AI Enablement** | Safely adopt AI coding tools at scale |
 | **Technical Debt Visibility** | Metrics and trends for data-driven decisions |

-### Enterprise Success Stories
-
-**Fortune 500 Financial Services** 🏦
-> "We have 200+ developers and were struggling with architectural consistency. Guardian reduced our code review cycle time by 35% and caught 12 hardcoded API keys before they hit production. ROI in first month." - VP Engineering
-
-**Scale-up SaaS (Series B)** 📈
-> "Guardian allowed us to confidently adopt GitHub Copilot across our team. AI writes code 3x faster, Guardian ensures quality. We ship more features without increasing tech debt." - CTO
-
-**Consulting Firm** 💼
-> "We use Guardian on every client project. It enforces our standards automatically, and clients love the quality metrics reports. Saved us from a major security incident when it caught hardcoded AWS credentials." - Lead Architect
-
 ## Installation

 ```bash
@@ -326,6 +382,15 @@ const result = await analyzeProject({
 })

 console.log(`Found ${result.hardcodeViolations.length} hardcoded values`)
+console.log(`Found ${result.secretViolations.length} hardcoded secrets 🔐`)
+
+// Check for critical security issues first!
+result.secretViolations.forEach((violation) => {
+    console.log(`🔐 CRITICAL: ${violation.file}:${violation.line}`)
+    console.log(`  Secret Type: ${violation.secretType}`)
+    console.log(`  ${violation.message}`)
+    console.log(`  ⚠️  Rotate this secret immediately!`)
+})

 result.hardcodeViolations.forEach((violation) => {
    console.log(`${violation.file}:${violation.line}`)
@@ -354,6 +419,17 @@ npx @samiyev/guardian check ./src --verbose
 npx @samiyev/guardian check ./src --no-hardcode  # Skip hardcode detection
 npx @samiyev/guardian check ./src --no-architecture  # Skip architecture checks

+# Filter by severity (perfect for finding secrets first!)
+npx @samiyev/guardian check ./src --only-critical      # Show only critical issues (secrets, circular deps)
+npx @samiyev/guardian check ./src --min-severity high  # Show high and critical only
+
+# Limit detailed output (useful for large codebases)
+npx @samiyev/guardian check ./src --limit 10           # Show first 10 violations per category
+npx @samiyev/guardian check ./src -l 20                # Short form
+
+# Combine options
+npx @samiyev/guardian check ./src --only-critical --limit 5  # Top 5 critical issues
+
 # Show help
 npx @samiyev/guardian --help

@@ -450,9 +526,17 @@ interface AnalyzeProjectRequest {

 ```typescript
 interface AnalyzeProjectResponse {
+    // Violations
    hardcodeViolations: HardcodeViolation[]
-    architectureViolations: ArchitectureViolation[]
+    violations: ArchitectureViolation[]
    circularDependencyViolations: CircularDependencyViolation[]
+    namingViolations: NamingViolation[]
+    frameworkLeakViolations: FrameworkLeakViolation[]
+    entityExposureViolations: EntityExposureViolation[]
+    dependencyDirectionViolations: DependencyDirectionViolation[]
+    repositoryPatternViolations: RepositoryPatternViolation[]
+
+    // Metrics
    metrics: ProjectMetrics
 }

@@ -463,21 +547,80 @@ interface HardcodeViolation {
    type: "magic-number" | "magic-string"
    value: string | number
    context: string
-    suggestedConstantName: string
-    suggestedLocation: string
+    severity: "critical" | "high" | "medium" | "low"
+    suggestion: {
+        constantName: string
+        location: string
+    }
 }

 interface CircularDependencyViolation {
    rule: "circular-dependency"
    message: string
    cycle: string[]
-    severity: "error"
+    severity: "critical" | "high" | "medium" | "low"
+}
+
+interface NamingViolation {
+    file: string
+    fileName: string
+    layer: string
+    type: string
+    message: string
+    suggestion?: string
+    severity: "critical" | "high" | "medium" | "low"
+}
+
+interface FrameworkLeakViolation {
+    file: string
+    packageName: string
+    category: string
+    categoryDescription: string
+    layer: string
+    rule: string
+    message: string
+    suggestion: string
+    severity: "critical" | "high" | "medium" | "low"
+}
+
+interface EntityExposureViolation {
+    file: string
+    line?: number
+    entityName: string
+    returnType: string
+    methodName?: string
+    layer: string
+    rule: string
+    message: string
+    suggestion: string
+    severity: "critical" | "high" | "medium" | "low"
+}
+
+interface DependencyDirectionViolation {
+    file: string
+    fromLayer: string
+    toLayer: string
+    importPath: string
+    message: string
+    suggestion: string
+    severity: "critical" | "high" | "medium" | "low"
+}
+
+interface RepositoryPatternViolation {
+    file: string
+    layer: string
+    violationType: string
+    details: string
+    message: string
+    suggestion: string
+    severity: "critical" | "high" | "medium" | "low"
 }

 interface ProjectMetrics {
    totalFiles: number
-    analyzedFiles: number
-    totalLines: number
+    totalFunctions: number
+    totalImports: number
+    layerDistribution: Record<string, number>
 }
 ```

@@ -816,43 +959,13 @@ Guardian follows Clean Architecture principles:
 - Node.js >= 18.0.0
 - TypeScript >= 5.0.0 (for TypeScript projects)

-## Real-World Vibe Coding Stats
-
-Based on testing Guardian with AI-generated codebases:
-
-| Metric | Typical AI Code | After Guardian |
-|--------|----------------|----------------|
-| Hardcoded values | 15-30 per 1000 LOC | 0-2 per 1000 LOC |
-| Circular deps | 2-5 per project | 0 per project |
-| Architecture violations | 10-20% of files | <1% of files |
-| Time to fix issues | Manual review: 2-4 hours | Guardian + AI: 5-10 minutes |
-
-**Common Issues Guardian Finds in AI Code:**
- 🔐 Hardcoded secrets and API keys (CRITICAL)
- ⏱️ Magic timeouts and retry counts
- 🌐 Hardcoded URLs and endpoints
- 🔄 Accidental circular imports
- 📁 Files in wrong architectural layers
- 🏷️ Inconsistent naming patterns
-
-## Success Stories
-
-**Prototype to Production** ⚡
-> "Built a SaaS MVP with Claude in 3 days. Guardian caught 47 hardcoded values before first deploy. Saved us from production disasters." - Indie Hacker
-
-**Learning Clean Architecture** 📚
-> "Guardian taught me Clean Architecture better than any tutorial. Every violation is a mini lesson with suggestions." - Junior Dev
-
-**AI-First Startup** 🚀
-> "We ship 5+ features daily using Claude + Guardian. No human code reviews needed for AI-generated code anymore." - Tech Lead
-
 ## FAQ for Vibe Coders

 **Q: Will Guardian slow down my AI workflow?**
 A: No! Run it after AI generates code, not during. Analysis takes 1-2 seconds for most projects.

 **Q: Can I use this with any AI coding assistant?**
-A: Yes! Works with Claude, GPT, Copilot, Cursor, or any tool that generates TypeScript/JavaScript.
+A: Yes! Works with GitHub Copilot, Cursor, Windsurf, Claude, ChatGPT, Cline, or any tool that generates TypeScript/JavaScript.

 **Q: Does Guardian replace ESLint/Prettier?**
 A: No, it complements them. ESLint checks syntax, Guardian checks architecture and hardcodes.
@@ -861,7 +974,7 @@ A: No, it complements them. ESLint checks syntax, Guardian checks architecture a
 A: Perfect use case! Guardian helps you identify tech debt so you can decide what to fix before production.

 **Q: Can AI fix Guardian's findings automatically?**
-A: Yes! Copy Guardian's output, paste into Claude/GPT with "fix these issues", and watch the magic.
+A: Yes! Copy Guardian's output, paste into Claude, ChatGPT, or your AI assistant with "fix these issues", and watch the magic.

 ## Contributing

--- a/packages/guardian/ROADMAP.md
+++ b/packages/guardian/ROADMAP.md
--- a/packages/guardian/TODO.md
+++ b/packages/guardian/TODO.md
@@ -94,19 +94,38 @@ This file tracks technical debt, known issues, and improvements needed in the co
 ### Testing
 - [x] ~~**Increase test coverage**~~ ✅ **FIXED**
  - ~~Current: 85.71% (target: 80%+)~~
-  - **New: 90.06%** (exceeds 80% target!)
+  - **New: 90.63%** (exceeds 80% target!)
  - ~~But only 2 test files (Guards, BaseEntity)~~
-  - **Now: 7 test files** with 187 tests total
+  - **Now: 10 test files** with 292 tests total
  - ~~Need tests for:~~
    - ~~HardcodeDetector (main logic!)~~ ✅ 49 tests added
    - ~~HardcodedValue~~ ✅ 28 tests added
-    - ~~FrameworkLeakDetector~~ ✅ 28 tests added
+    - ~~FrameworkLeakDetector~~ ✅ 35 tests added
+    - ~~NamingConventionDetector~~ ✅ 55 tests added
+    - ~~DependencyDirectionDetector~~ ✅ 43 tests added
+    - ~~EntityExposureDetector~~ ✅ 24 tests added
+    - ~~RepositoryPatternDetector~~ ✅ 31 tests added
    - AnalyzeProject use case (pending)
    - CLI commands (pending)
    - FileScanner (pending)
    - CodeParser (pending)
  - Completed on: 2025-11-24

+- [ ] **Improve test coverage for low-coverage files**
+  - **SourceFile.ts**: 44.82% coverage (entity, not critical but needs improvement)
+    - Missing: Property getters, metadata methods, dependency management
+    - Target: 80%+
+  - **ProjectPath.ts**: 50% coverage (value object)
+    - Missing: Path validation methods, edge cases
+    - Target: 80%+
+  - **RepositoryViolation.ts**: 55.26% coverage (value object)
+    - Missing: Violation type methods, details formatting
+    - Target: 80%+
+  - **ValueObject.ts**: 25% coverage (base class)
+    - Missing: equals() and other base methods
+    - Target: 80%+
+  - Priority: Medium (overall coverage is good, but these specific files need attention)
+
 - [ ] **Add integration tests**
  - Test full workflow: scan → parse → detect → report
  - Test CLI end-to-end
@@ -179,7 +198,37 @@ When implementing these, consider semantic versioning:

 ## 📝 Recent Updates (2025-11-24)

-### Completed Tasks
+### v0.5.2 - Limit Feature & ESLint Cleanup
+1. ✅ **Added --limit CLI option**
+   - Limits detailed output to specified number of violations per category
+   - Short form: `-l <number>`
+   - Works with severity filters (--only-critical, --min-severity)
+   - Shows warning when violations exceed limit
+   - Example: `guardian check ./src --limit 10`
+   - Updated CLI constants, index, and README documentation
+
+2. ✅ **ESLint configuration cleanup**
+   - Reduced warnings from 129 to 0 ✨
+   - Added CLI-specific overrides (no-console, complexity, max-lines-per-function)
+   - Disabled no-unsafe-* rules for CLI (Commander.js is untyped)
+   - Increased max-params to 8 for DDD patterns
+   - Excluded examples/, tests/, *.config.ts from linting
+   - Disabled style rules (prefer-nullish-coalescing, no-unnecessary-condition, no-nested-ternary)
+
+3. ✅ **Fixed remaining ESLint errors**
+   - Removed unused SEVERITY_LEVELS import from AnalyzeProject.ts
+   - Fixed unused fileName variable in HardcodeDetector.ts (prefixed with _)
+   - Replaced || with ?? for nullish coalescing
+
+4. ✅ **Updated README.md**
+   - Added all new detectors to Features section (Entity Exposure, Dependency Direction, Repository Pattern)
+   - Updated API documentation with all 8 violation types
+   - Added severity levels to all interfaces
+   - Documented --limit option with examples
+   - Updated ProjectMetrics interface
+   - Updated test statistics (292 tests, 90.63% coverage)
+
+### v0.5.0-0.5.1 - Architecture Enhancements
 1. ✅ **Added comprehensive tests for HardcodeDetector** (49 tests)
   - Magic numbers detection (setTimeout, retries, ports, limits)
   - Magic strings detection (URLs, connection strings)
@@ -203,9 +252,9 @@ When implementing these, consider semantic versioning:
   - Fixed constant truthiness errors

 5. ✅ **Improved test coverage**
-   - From 85.71% to 90.06% (statements)
+   - From 85.71% to 90.63% (statements)
   - All metrics now exceed 80% threshold
-   - Total tests: 16 → 187 tests
+   - Total tests: 16 → 292 tests

 6. ✅ **Implemented Framework Leak Detection (v0.2.0)**
   - Created FrameworkLeakDetector with 10 framework categories
--- a/packages/guardian/docs/COMPARISON.md
+++ b/packages/guardian/docs/COMPARISON.md
@@ -0,0 +1,895 @@
+# Guardian vs Competitors: Comprehensive Comparison 🔍
+
+**Last Updated:** 2025-01-24
+
+This document provides an in-depth comparison of Guardian against major competitors in the static analysis and architecture enforcement space.
+
+---
+
+## 🎯 TL;DR - When to Use Each Tool
+
+| Your Need | Recommended Tool | Why |
+|-----------|------------------|-----|
+| **TypeScript + AI coding + DDD** | ✅ **Guardian** | Only tool built for AI-assisted DDD development |
+| **Multi-language + Security** | SonarQube | 35+ languages, deep security scanning |
+| **Dependency visualization** | dependency-cruiser + Guardian | Best visualization + architecture rules |
+| **Java architecture** | ArchUnit | Java-specific with unit test integration |
+| **TypeScript complexity metrics** | FTA + Guardian | Fast metrics + architecture enforcement |
+| **Python architecture** | import-linter + Guardian (future) | Python layer enforcement |
+
+---
+
+## 📊 Feature Comparison Matrix
+
+### Core Capabilities
+
+| Feature | Guardian | SonarQube | dependency-cruiser | ArchUnit | FTA | ESLint |
+|---------|----------|-----------|-------------------|----------|-----|--------|
+| **Languages** | JS/TS | 35+ | JS/TS/Vue | Java | TS/JS | JS/TS |
+| **Setup Complexity** | ⚡ Simple | 🐌 Complex | ⚡ Simple | ⚙️ Medium | ⚡ Simple | ⚡ Simple |
+| **Price** | 🆓 Free | 💰 Freemium | 🆓 Free | 🆓 Free | 🆓 Free | 🆓 Free |
+| **GitHub Stars** | - | - | 6.2k | 3.1k | - | 24k+ |
+
+### Detection Capabilities
+
+| Feature | Guardian | SonarQube | dependency-cruiser | ArchUnit | FTA | ESLint |
+|---------|----------|-----------|-------------------|----------|-----|--------|
+| **Hardcode Detection** | ✅✅ (with AI tips) | ⚠️ (secrets only) | ❌ | ❌ | ❌ | ❌ |
+| **Circular Dependencies** | ✅ | ✅ | ✅✅ (visual) | ✅ | ❌ | ✅ |
+| **Architecture Layers** | ✅✅ (DDD/Clean) | ⚠️ (generic) | ✅ (via rules) | ✅✅ | ❌ | ⚠️ |
+| **Framework Leak** | ✅✅ UNIQUE | ❌ | ⚠️ (via rules) | ⚠️ | ❌ | ❌ |
+| **Entity Exposure** | ✅✅ UNIQUE | ❌ | ❌ | ❌ | ❌ | ❌ |
+| **Naming Conventions** | ✅ (DDD-specific) | ✅ (generic) | ❌ | ✅ | ❌ | ✅ |
+| **Repository Pattern** | ✅✅ UNIQUE | ❌ | ❌ | ⚠️ | ❌ | ❌ |
+| **Dependency Direction** | ✅✅ | ❌ | ✅ (via rules) | ✅ | ❌ | ❌ |
+| **Security (SAST)** | ❌ | ✅✅ | ❌ | ❌ | ❌ | ⚠️ |
+| **Dependency Risks (SCA)** | ❌ | ✅✅ | ❌ | ❌ | ❌ | ❌ |
+| **Complexity Metrics** | ❌ | ✅ | ❌ | ❌ | ✅✅ | ⚠️ |
+| **Code Duplication** | ❌ | ✅✅ | ❌ | ❌ | ❌ | ❌ |
+
+### Developer Experience
+
+| Feature | Guardian | SonarQube | dependency-cruiser | ArchUnit | FTA | ESLint |
+|---------|----------|-----------|-------------------|----------|-----|--------|
+| **CLI** | ✅ | ✅ | ✅ | ❌ (lib) | ✅ | ✅ |
+| **Configuration** | ✅ (v0.6+) | ✅✅ | ✅ | ✅ | ⚠️ | ✅✅ |
+| **Visualization** | ✅ (v0.7+) | ✅✅ (dashboard) | ✅✅ (graphs) | ❌ | ⚠️ | ❌ |
+| **Auto-Fix** | ✅✅ (v0.9+) UNIQUE | ❌ | ❌ | ❌ | ❌ | ✅ |
+| **AI Workflow** | ✅✅ UNIQUE | ❌ | ❌ | ❌ | ❌ | ❌ |
+| **CI/CD Integration** | ✅ (v0.8+) | ✅✅ | ✅ | ✅ | ⚠️ | ✅✅ |
+| **IDE Extensions** | 🔜 (v1.0+) | ✅ | ❌ | ❌ | ⚠️ | ✅✅ |
+| **Metrics Dashboard** | ✅ (v0.10+) | ✅✅ | ⚠️ | ❌ | ✅ | ❌ |
+
+**Legend:**
+- ✅✅ = Excellent support
+- ✅ = Good support
+- ⚠️ = Limited/partial support
+- ❌ = Not available
+- 🔜 = Planned/Coming soon
+
+---
+
+## 🔥 Guardian's Unique Advantages
+
+Guardian has **7 unique features** that no competitor offers:
+
+### 1. ✨ Hardcode Detection with AI Suggestions
+
+**Guardian:**
+```typescript
+// Detected:
+app.listen(3000)
+
+// Suggestion:
+💡 Extract to: DEFAULT_PORT
+📁 Location: infrastructure/config/constants.ts
+🤖 AI Prompt: "Extract port 3000 to DEFAULT_PORT constant in config"
+```
+
+**Competitors:**
+- SonarQube: Only detects hardcoded secrets (API keys), not magic numbers
+- Others: No hardcode detection at all
+
+### 2. 🔌 Framework Leak Detection
+
+**Guardian:**
+```typescript
+// domain/entities/User.ts
+import { Request } from 'express'  // ❌ VIOLATION!
+
+// Detected: Framework leak in domain layer
+// Suggestion: Use dependency injection via interfaces
+```
+
+**Competitors:**
+- ArchUnit: Can check via custom rules (not built-in)
+- Others: Not available
+
+### 3. 🎭 Entity Exposure Detection
+
+**Guardian:**
+```typescript
+// ❌ Bad: Domain entity exposed
+async getUser(): Promise<User> { }
+
+// ✅ Good: Use DTOs
+async getUser(): Promise<UserDto> { }
+
+// Guardian detects this automatically!
+```
+
+**Competitors:**
+- None have this built-in
+
+### 4. 📚 Repository Pattern Validation
+
+**Guardian:**
+```typescript
+// Detects ORM types in domain interfaces:
+interface IUserRepository {
+    findOne(query: { where: ... })  // ❌ Prisma-specific!
+}
+
+// Detects concrete repos in use cases:
+constructor(private prisma: PrismaClient) {}  // ❌ VIOLATION!
+```
+
+**Competitors:**
+- None validate repository pattern
+
+### 5. 🤖 AI-First Workflow
+
+**Guardian:**
+```bash
+# Generate AI-friendly fix prompt
+guardian check ./src --format ai-prompt > fix.txt
+
+# Feed to Claude/GPT:
+"Fix these Guardian violations: $(cat fix.txt)"
+
+# AI fixes → Run Guardian again → Ship it!
+```
+
+**Competitors:**
+- Generic output, not optimized for AI assistants
+
+### 6. 🛠️ Auto-Fix for Architecture (v0.9+)
+
+**Guardian:**
+```bash
+# Automatically extract hardcodes to constants
+guardian fix ./src --auto
+
+# Rename files to match conventions
+guardian fix naming ./src --auto
+
+# Interactive mode
+guardian fix ./src --interactive
+```
+
+**Competitors:**
+- ESLint has `--fix` but only for syntax
+- None fix architecture violations
+
+### 7. 🎯 DDD Pattern Detection (30+)
+
+**Guardian Roadmap:**
+- Aggregate boundaries
+- Anemic domain model
+- Domain events
+- Value Object immutability
+- CQRS violations
+- Saga pattern
+- Ubiquitous language
+- And 23+ more DDD patterns!
+
+**Competitors:**
+- Generic architecture checks only
+- No DDD-specific patterns
+
+---
+
+## 📈 Detailed Tool Comparisons
+
+## vs SonarQube
+
+### When SonarQube Wins
+
+✅ **Multi-language projects**
+```
+Java + Python + TypeScript → Use SonarQube
+TypeScript only → Consider Guardian
+```
+
+✅ **Security-critical applications**
+```
+SonarQube: SAST, SCA, OWASP Top 10, CVE detection
+Guardian: Architecture only (security coming later)
+```
+
+✅ **Large enterprise with compliance**
+```
+SonarQube: Compliance reports, audit trails, enterprise support
+Guardian: Lightweight, developer-focused
+```
+
+✅ **Existing SonarQube investment**
+```
+Already using SonarQube? Add Guardian for DDD-specific checks
+```
+
+### When Guardian Wins
+
+✅ **TypeScript + AI coding workflow**
+```typescript
+// AI generates code → Guardian checks → AI fixes → Ship
+// 10x faster than manual review
+```
+
+✅ **Clean Architecture / DDD enforcement**
+```typescript
+// Guardian understands DDD out-of-the-box
+// SonarQube requires custom rules
+```
+
+✅ **Fast setup (< 5 minutes)**
+```bash
+npm install -g @samiyev/guardian
+guardian check ./src
+# Done! (vs hours of SonarQube setup)
+```
+
+✅ **Hardcode detection with context**
+```typescript
+// Guardian knows the difference between:
+const port = 3000        // ❌ Should be constant
+const increment = 1      // ✅ Allowed (semantic)
+```
+
+### Side-by-Side Example
+
+**Scenario:** Detect hardcoded port in Express app
+
+```typescript
+// src/server.ts
+app.listen(3000)
+```
+
+**SonarQube:**
+```
+❌ No violation (not a secret)
+```
+
+**Guardian:**
+```
+✅ Hardcode detected:
+   Type: magic-number
+   Value: 3000
+   💡 Suggested: DEFAULT_PORT
+   📁 Location: infrastructure/config/constants.ts
+   🤖 AI Fix: "Extract 3000 to DEFAULT_PORT constant"
+```
+
+---
+
+## vs dependency-cruiser
+
+### When dependency-cruiser Wins
+
+✅ **Visualization priority**
+```bash
+# Best-in-class dependency graphs
+depcruise src --output-type dot | dot -T svg > graph.svg
+```
+
+✅ **Custom dependency rules**
+```javascript
+// Highly flexible rule system
+forbidden: [
+  {
+    from: { path: '^src/domain' },
+    to: { path: '^src/infrastructure' }
+  }
+]
+```
+
+✅ **Multi-framework support**
+```
+JS, TS, Vue, Svelte, JSX, CoffeeScript
+```
+
+### When Guardian Wins
+
+✅ **DDD/Clean Architecture out-of-the-box**
+```typescript
+// Guardian knows these patterns:
+// - Domain/Application/Infrastructure layers
+// - Entity exposure
+// - Repository pattern
+// - Framework leaks
+
+// dependency-cruiser: Write custom rules for each
+```
+
+✅ **Hardcode detection**
+```typescript
+// Guardian finds:
+setTimeout(() => {}, 5000)  // Magic number
+const url = "http://..."    // Magic string
+
+// dependency-cruiser: Doesn't check this
+```
+
+✅ **AI workflow integration**
+```bash
+guardian check ./src --format ai-prompt
+# Optimized for Claude/GPT
+
+depcruise src
+# Generic output
+```
+
+### Complementary Usage
+
+**Best approach:** Use both!
+
+```bash
+# Guardian for architecture + hardcode
+guardian check ./src
+
+# dependency-cruiser for visualization
+depcruise src --output-type svg > architecture.svg
+```
+
+**Coming in Guardian v0.7.0:**
+```bash
+# Guardian will have built-in visualization!
+guardian visualize ./src --output architecture.svg
+```
+
+---
+
+## vs ArchUnit (Java)
+
+### When ArchUnit Wins
+
+✅ **Java projects**
+```java
+// ArchUnit is built for Java
+@ArchTest
+void domainShouldNotDependOnInfrastructure(JavaClasses classes) {
+    noClasses().that().resideInPackage("..domain..")
+        .should().dependOnClassesThat().resideInPackage("..infrastructure..")
+        .check(classes);
+}
+```
+
+✅ **Test-based architecture validation**
+```java
+// Architecture rules = unit tests
+// Runs in your CI with other tests
+```
+
+✅ **Mature Java ecosystem**
+```
+Spring Boot, Hibernate, JPA patterns
+Built-in rules for layered/onion architecture
+```
+
+### When Guardian Wins
+
+✅ **TypeScript/JavaScript projects**
+```typescript
+// Guardian is built for TypeScript
+// ArchUnit doesn't support TS
+```
+
+✅ **AI coding workflow**
+```bash
+# Guardian → AI → Fix → Ship
+# ArchUnit is test-based (slower feedback)
+```
+
+✅ **Zero-config DDD**
+```bash
+guardian check ./src
+# Works immediately with DDD structure
+
+# ArchUnit requires writing tests for each rule
+```
+
+### Philosophical Difference
+
+**ArchUnit:**
+```java
+// Architecture = Tests
+// You write explicit tests for each rule
+```
+
+**Guardian:**
+```bash
+# Architecture = Linter
+# Pre-configured DDD rules out-of-the-box
+```
+
+---
+
+## vs FTA (Fast TypeScript Analyzer)
+
+### When FTA Wins
+
+✅ **Complexity metrics focus**
+```bash
+# FTA provides:
+# - Cyclomatic complexity
+# - Halstead metrics
+# - Line counts
+# - Technical debt estimation
+```
+
+✅ **Performance (Rust-based)**
+```
+FTA: 1600 files/second
+Guardian: ~500 files/second (Node.js)
+```
+
+✅ **Simplicity**
+```bash
+# FTA does one thing well: metrics
+fta src/
+```
+
+### When Guardian Wins
+
+✅ **Architecture enforcement**
+```typescript
+// Guardian checks:
+// - Layer violations
+// - Framework leaks
+// - Circular dependencies
+// - Repository pattern
+
+// FTA: Only measures complexity, no architecture checks
+```
+
+✅ **Hardcode detection**
+```typescript
+// Guardian finds magic numbers/strings
+// FTA doesn't check this
+```
+
+✅ **AI workflow**
+```bash
+# Guardian provides actionable suggestions
+# FTA provides metrics only
+```
+
+### Complementary Usage
+
+**Best approach:** Use both!
+
+```bash
+# Guardian for architecture
+guardian check ./src
+
+# FTA for complexity metrics
+fta src/ --threshold complexity:15
+```
+
+**Coming in Guardian v0.10.0:**
+```bash
+# Guardian will include complexity metrics!
+guardian metrics ./src --include-complexity
+```
+
+---
+
+## vs ESLint + Plugins
+
+### When ESLint Wins
+
+✅ **General code quality**
+```javascript
+// Best for:
+// - Code style
+// - Common bugs
+// - TypeScript errors
+// - React/Vue specific rules
+```
+
+✅ **Huge ecosystem**
+```bash
+# 10,000+ plugins
+eslint-plugin-react
+eslint-plugin-vue
+eslint-plugin-security
+# ...and many more
+```
+
+✅ **Auto-fix for syntax**
+```bash
+eslint --fix
+# Fixes semicolons, quotes, formatting, etc.
+```
+
+### When Guardian Wins
+
+✅ **Architecture enforcement**
+```typescript
+// ESLint doesn't understand:
+// - Clean Architecture layers
+// - DDD patterns
+// - Framework leaks
+// - Entity exposure
+
+// Guardian does!
+```
+
+✅ **Hardcode detection with context**
+```typescript
+// ESLint plugins check patterns
+// Guardian understands semantic context
+```
+
+✅ **AI workflow integration**
+```bash
+# Guardian optimized for AI assistants
+# ESLint generic output
+```
+
+### Complementary Usage
+
+**Best approach:** Use both!
+
+```bash
+# ESLint for code quality
+eslint src/
+
+# Guardian for architecture
+guardian check ./src
+```
+
+**Many teams run both in CI:**
+```yaml
+# .github/workflows/quality.yml
+- name: ESLint
+  run: npm run lint
+
+- name: Guardian
+  run: guardian check ./src --fail-on error
+```
+
+---
+
+## vs import-linter (Python)
+
+### When import-linter Wins
+
+✅ **Python projects**
+```ini
+# .importlinter
+[importlinter]
+root_package = myproject
+
+[importlinter:contract:1]
+name = Layers contract
+type = layers
+layers =
+    myproject.domain
+    myproject.application
+    myproject.infrastructure
+```
+
+✅ **Mature Python ecosystem**
+```python
+# Django, Flask, FastAPI integration
+```
+
+### When Guardian Wins
+
+✅ **TypeScript/JavaScript**
+```typescript
+// Guardian is for TS/JS
+// import-linter is Python-only
+```
+
+✅ **More than import checking**
+```typescript
+// Guardian checks:
+// - Hardcode
+// - Entity exposure
+// - Repository pattern
+// - Framework leaks
+
+// import-linter: Only imports
+```
+
+### Future Integration
+
+**Guardian v2.0+ (Planned):**
+```bash
+# Multi-language support coming
+guardian check ./python-src --language python
+guardian check ./ts-src --language typescript
+```
+
+---
+
+## 💰 Cost Comparison
+
+| Tool | Free Tier | Paid Plans | Enterprise |
+|------|-----------|------------|------------|
+| **Guardian** | ✅ MIT License (100% free) | - | - |
+| **SonarQube** | ✅ Community Edition | Developer: $150/yr | Custom pricing |
+| **dependency-cruiser** | ✅ MIT License | - | - |
+| **ArchUnit** | ✅ Apache 2.0 | - | - |
+| **FTA** | ✅ Open Source | - | - |
+| **ESLint** | ✅ MIT License | - | - |
+
+**Guardian will always be free and open-source (MIT License)**
+
+---
+
+## 🚀 Setup Time Comparison
+
+| Tool | Setup Time | Configuration Required |
+|------|------------|------------------------|
+| **Guardian** | ⚡ 2 minutes | ❌ Zero-config (DDD) |
+| **SonarQube** | 🐌 2-4 hours | ✅ Extensive setup |
+| **dependency-cruiser** | ⚡ 5 minutes | ⚠️ Rules configuration |
+| **ArchUnit** | ⚙️ 30 minutes | ✅ Write test rules |
+| **FTA** | ⚡ 1 minute | ❌ Zero-config |
+| **ESLint** | ⚡ 10 minutes | ⚠️ Plugin configuration |
+
+**Guardian Setup:**
+```bash
+# 1. Install (30 seconds)
+npm install -g @samiyev/guardian
+
+# 2. Run (90 seconds)
+cd your-project
+guardian check ./src
+
+# Done! 🎉
+```
+
+---
+
+## 📊 Real-World Performance
+
+### Analysis Speed (1000 TypeScript files)
+
+| Tool | Time | Notes |
+|------|------|-------|
+| **FTA** | ~0.6s | ⚡ Fastest (Rust) |
+| **Guardian** | ~2s | Fast (Node.js, tree-sitter) |
+| **dependency-cruiser** | ~3s | Fast |
+| **ESLint** | ~5s | Depends on rules |
+| **SonarQube** | ~15s | Slower (comprehensive) |
+
+### Memory Usage
+
+| Tool | RAM | Notes |
+|------|-----|-------|
+| **Guardian** | ~150MB | Efficient |
+| **FTA** | ~50MB | Minimal (Rust) |
+| **dependency-cruiser** | ~200MB | Moderate |
+| **ESLint** | ~300MB | Varies by plugins |
+| **SonarQube** | ~2GB | Heavy (server) |
+
+---
+
+## 🎯 Use Case Recommendations
+
+### Scenario 1: TypeScript Startup Using AI Coding
+
+**Best Stack:**
+```bash
+✅ Guardian (architecture + hardcode)
+✅ ESLint (code quality)
+✅ Prettier (formatting)
+```
+
+**Why:**
+- Fast setup
+- AI workflow integration
+- Zero-config DDD
+- Catches AI mistakes (hardcode)
+
+### Scenario 2: Enterprise Multi-Language
+
+**Best Stack:**
+```bash
+✅ SonarQube (security + multi-language)
+✅ Guardian (TypeScript DDD specialization)
+✅ ArchUnit (Java architecture)
+```
+
+**Why:**
+- Comprehensive coverage
+- Security scanning
+- Language-specific depth
+
+### Scenario 3: Clean Architecture Refactoring
+
+**Best Stack:**
+```bash
+✅ Guardian (architecture enforcement)
+✅ dependency-cruiser (visualization)
+✅ Guardian v0.9+ (auto-fix)
+```
+
+**Why:**
+- Visualize current state
+- Detect violations
+- Auto-fix issues
+
+### Scenario 4: Python + TypeScript Monorepo
+
+**Best Stack:**
+```bash
+✅ Guardian (TypeScript)
+✅ import-linter (Python)
+✅ SonarQube (security, both languages)
+```
+
+**Why:**
+- Language-specific depth
+- Unified security scanning
+
+---
+
+## 🏆 Winner by Category
+
+| Category | Winner | Runner-up |
+|----------|--------|-----------|
+| **TypeScript Architecture** | 🥇 Guardian | dependency-cruiser |
+| **Multi-Language** | 🥇 SonarQube | - |
+| **Visualization** | 🥇 dependency-cruiser | SonarQube |
+| **AI Workflow** | 🥇 Guardian | - (no competitor) |
+| **Security** | 🥇 SonarQube | - |
+| **Hardcode Detection** | 🥇 Guardian | - (no competitor) |
+| **DDD Patterns** | 🥇 Guardian | ArchUnit (Java) |
+| **Auto-Fix** | 🥇 ESLint (syntax) | Guardian v0.9+ (architecture) |
+| **Complexity Metrics** | 🥇 FTA | SonarQube |
+| **Setup Speed** | 🥇 FTA | Guardian |
+
+---
+
+## 🔮 Future Roadmap Comparison
+
+### Guardian v1.0.0 (Q4 2026)
+- ✅ Configuration & presets (v0.6)
+- ✅ Visualization (v0.7)
+- ✅ CI/CD kit (v0.8)
+- ✅ Auto-fix (v0.9) **UNIQUE!**
+- ✅ Metrics dashboard (v0.10)
+- ✅ 30+ DDD patterns (v0.11-v0.32)
+- ✅ VS Code extension
+- ✅ JetBrains plugin
+
+### Competitors
+- **SonarQube**: Incremental improvements, AI-powered fixes (experimental)
+- **dependency-cruiser**: Stable, no major changes planned
+- **ArchUnit**: Java focus, incremental improvements
+- **FTA**: Adding more metrics
+- **ESLint**: Flat config, performance improvements
+
+**Guardian's Advantage:** Only tool actively expanding DDD/architecture detection
+
+---
+
+## 💡 Migration Guides
+
+### From SonarQube to Guardian
+
+**When to migrate:**
+- TypeScript-only project
+- Want faster iteration
+- Need DDD-specific checks
+- Don't need multi-language/security
+
+**How to migrate:**
+```bash
+# Keep SonarQube for security
+# Add Guardian for architecture
+npm install -g @samiyev/guardian
+guardian check ./src
+
+# CI/CD: Run both
+# SonarQube (security) → Guardian (architecture)
+```
+
+### From ESLint-only to ESLint + Guardian
+
+**Why add Guardian:**
+```typescript
+// ESLint checks syntax
+// Guardian checks architecture
+```
+
+**How to add:**
+```bash
+# Keep ESLint
+npm run lint
+
+# Add Guardian
+guardian check ./src
+
+# Both in CI:
+npm run lint && guardian check ./src
+```
+
+### From dependency-cruiser to Guardian
+
+**Why migrate:**
+- Need more than circular deps
+- Want hardcode detection
+- Need DDD patterns
+- Want auto-fix (v0.9+)
+
+**How to migrate:**
+```bash
+# Replace:
+depcruise src --config .dependency-cruiser.js
+
+# With:
+guardian check ./src
+
+# Or keep both:
+# dependency-cruiser → visualization
+# Guardian → architecture + hardcode
+```
+
+---
+
+## 📚 Additional Resources
+
+### Guardian
+- [GitHub Repository](https://github.com/samiyev/puaros)
+- [Documentation](https://puaros.ailabs.uz)
+- [npm Package](https://www.npmjs.com/package/@samiyev/guardian)
+
+### Competitors
+- [SonarQube](https://www.sonarsource.com/products/sonarqube/)
+- [dependency-cruiser](https://github.com/sverweij/dependency-cruiser)
+- [ArchUnit](https://www.archunit.org/)
+- [FTA](https://ftaproject.dev/)
+- [import-linter](https://import-linter.readthedocs.io/)
+
+---
+
+## 🤝 Community & Support
+
+| Tool | Community | Support |
+|------|-----------|---------|
+| **Guardian** | GitHub Issues | Community (planned: Discord) |
+| **SonarQube** | Community Forum | Commercial support available |
+| **dependency-cruiser** | GitHub Issues | Community |
+| **ArchUnit** | GitHub Issues | Community |
+| **ESLint** | Discord, Twitter | Community |
+
+---
+
+**Guardian's Position in the Market:**
+
+> **"The AI-First Architecture Guardian for TypeScript teams practicing DDD/Clean Architecture"**
+
+**Guardian is NOT:**
+- ❌ A replacement for SonarQube's security scanning
+- ❌ A replacement for ESLint's code quality checks
+- ❌ A multi-language tool (yet)
+
+**Guardian IS:**
+- ✅ The best tool for TypeScript DDD/Clean Architecture
+- ✅ The only tool optimized for AI-assisted coding
+- ✅ The only tool with intelligent hardcode detection
+- ✅ The only tool with auto-fix for architecture (v0.9+)
+
+---
+
+**Questions? Feedback?**
+
+- 📧 Email: fozilbek.samiyev@gmail.com
+- 🐙 GitHub: https://github.com/samiyev/puaros/issues
+- 🌐 Website: https://puaros.ailabs.uz
--- a/packages/guardian/docs/COMPETITIVE_ANALYSIS_SUMMARY.md
+++ b/packages/guardian/docs/COMPETITIVE_ANALYSIS_SUMMARY.md
@@ -0,0 +1,323 @@
+# Competitive Analysis & Roadmap - Summary
+
+**Date:** 2025-01-24
+**Prepared for:** Puaros Guardian
+**Documents Created:**
+1. ROADMAP_NEW.md - Updated roadmap with reprioritized features
+2. COMPARISON.md - Comprehensive competitor comparison
+3. docs/v0.6.0-CONFIGURATION-SPEC.md - Configuration feature specification
+
+---
+
+## 🎯 Executive Summary
+
+Guardian has **5 unique features** that no competitor offers, positioning it as the **only tool built for AI-assisted DDD/Clean Architecture development**. However, to achieve enterprise adoption, we need to first match competitors' baseline features (configuration, visualization, CI/CD, metrics).
+
+### Current Position (v0.5.1)
+
+**Strengths:**
+- ✅ Hardcode detection with AI suggestions (UNIQUE)
+- ✅ Framework leak detection (UNIQUE)
+- ✅ Entity exposure detection (UNIQUE)
+- ✅ Repository pattern validation (UNIQUE)
+- ✅ DDD-specific naming conventions (UNIQUE)
+
+**Gaps:**
+- ❌ No configuration file support
+- ❌ No visualization/graphs
+- ❌ No ready-to-use CI/CD templates
+- ❌ No metrics/quality score
+- ❌ No auto-fix capabilities
+
+---
+
+## 📊 Competitive Landscape
+
+### Main Competitors
+
+| Tool | Strength | Weakness | Market Position |
+|------|----------|----------|-----------------|
+| **SonarQube** | Multi-language + Security | Complex setup, expensive | Enterprise leader |
+| **dependency-cruiser** | Best visualization | No hardcode/DDD | Dependency specialist |
+| **ArchUnit** | Java architecture | Java-only | Java ecosystem |
+| **FTA** | Fast metrics (Rust) | No architecture checks | Metrics tool |
+| **ESLint** | Huge ecosystem | No architecture | Code quality standard |
+
+### Guardian's Unique Position
+
+> **"The AI-First Architecture Guardian for TypeScript teams practicing DDD/Clean Architecture"**
+
+**Market Gap Filled:**
+- No tool optimizes for AI-assisted coding workflow
+- No tool deeply understands DDD patterns (except ArchUnit for Java)
+- No tool combines hardcode detection + architecture enforcement
+
+---
+
+## 🚀 Strategic Roadmap
+
+### Phase 1: Market Parity (v0.6-v0.10) - Q1-Q2 2026
+
+**Goal:** Match competitors' baseline features
+
+| Version | Feature | Why Critical | Competitor |
+|---------|---------|--------------|------------|
+| v0.6.0 | Configuration & Presets | All competitors have this | ESLint, SonarQube |
+| v0.7.0 | Visualization | dependency-cruiser's main advantage | dependency-cruiser |
+| v0.8.0 | CI/CD Integration Kit | Enterprise requirement | SonarQube |
+| v0.9.0 | **Auto-Fix (UNIQUE!)** | Game-changer, no one has this | None |
+| v0.10.0 | Metrics & Quality Score | Enterprise adoption | SonarQube |
+
+**After v0.10.0:** Guardian competes with SonarQube/dependency-cruiser on features
+
+### Phase 2: DDD Specialization (v0.11-v0.32) - Q3-Q4 2026
+
+**Goal:** Deepen DDD/Clean Architecture expertise
+
+30+ DDD pattern detectors:
+- Aggregate boundaries
+- Anemic domain model
+- Domain events
+- Value Object immutability
+- CQRS validation
+- Saga pattern
+- Anti-Corruption Layer
+- Ubiquitous Language
+- And 22+ more...
+
+**After Phase 2:** Guardian = THE tool for DDD/Clean Architecture
+
+### Phase 3: Enterprise Ecosystem (v1.0+) - Q4 2026+
+
+**Goal:** Full enterprise platform
+
+- VS Code extension
+- JetBrains plugin
+- Web dashboard
+- Team analytics
+- Multi-language support (Python, C#, Java)
+
+---
+
+## 🔥 Critical Changes to Current Roadmap
+
+### Old Roadmap Issues
+
+❌ **v0.6.0 was "Aggregate Boundaries"** → Too early for DDD-specific features
+❌ **v0.12.0 was "Configuration"** → Way too late! Critical feature postponed
+❌ **Missing:** Visualization, CI/CD, Auto-fix, Metrics
+❌ **Too many consecutive DDD features** → Need market parity first
+
+### New Roadmap Priorities
+
+✅ **v0.6.0 = Configuration (MOVED UP)** → Critical for adoption
+✅ **v0.7.0 = Visualization (NEW)** → Compete with dependency-cruiser
+✅ **v0.8.0 = CI/CD Kit (NEW)** → Enterprise requirement
+✅ **v0.9.0 = Auto-Fix (NEW, UNIQUE!)** → Game-changing differentiator
+✅ **v0.10.0 = Metrics (NEW)** → Compete with SonarQube
+✅ **v0.11+ = DDD Features** → After market parity
+
+---
+
+## 💡 Key Recommendations
+
+### Immediate Actions (Next 2 Weeks)
+
+1. **Review & Approve New Roadmap**
+   - Read ROADMAP_NEW.md
+   - Approve priority changes
+   - Create GitHub milestones
+
+2. **Start v0.6.0 Configuration**
+   - Read v0.6.0-CONFIGURATION-SPEC.md
+   - Create implementation tasks
+   - Start Phase 1 development
+
+3. **Update Documentation**
+   - Update main README.md with comparison table
+   - Add "Guardian vs Competitors" section
+   - Link to COMPARISON.md
+
+### Next 3 Months (Q1 2026)
+
+4. **Complete v0.6.0 (Configuration)**
+   - 8-week timeline
+   - Beta test with community
+   - Stable release
+
+5. **Start v0.7.0 (Visualization)**
+   - Design graph system
+   - Choose visualization library
+   - Prototype SVG/Mermaid output
+
+6. **Marketing & Positioning**
+   - Create comparison blog post
+   - Submit to Product Hunt
+   - Share on Reddit/HackerNews
+
+### Next 6 Months (Q1-Q2 2026)
+
+7. **Complete Market Parity (v0.6-v0.10)**
+   - Configuration ✅
+   - Visualization ✅
+   - CI/CD Integration ✅
+   - Auto-Fix ✅ (UNIQUE!)
+   - Metrics ✅
+
+8. **Community Growth**
+   - 1000+ GitHub stars
+   - 100+ weekly npm installs
+   - 10+ enterprise adopters
+
+---
+
+## 📈 Success Metrics
+
+### v0.10.0 (Market Parity Achieved) - June 2026
+
+**Feature Parity:**
+- ✅ Configuration support (compete with ESLint)
+- ✅ Visualization (compete with dependency-cruiser)
+- ✅ CI/CD integration (compete with SonarQube)
+- ✅ Auto-fix (UNIQUE! Game-changer)
+- ✅ Metrics dashboard (compete with SonarQube)
+
+**Adoption Metrics:**
+- 1,000+ GitHub stars
+- 100+ weekly npm installs
+- 50+ projects with guardian.config.js
+- 10+ enterprise teams
+
+### v1.0.0 (Enterprise Ready) - December 2026
+
+**Feature Completeness:**
+- ✅ All baseline features
+- ✅ 30+ DDD pattern detectors
+- ✅ IDE extensions (VS Code, JetBrains)
+- ✅ Web dashboard
+- ✅ Team analytics
+
+**Market Position:**
+- #1 tool for TypeScript DDD/Clean Architecture
+- Top 3 in static analysis for TypeScript
+- Known in enterprise as "the AI code reviewer"
+
+---
+
+## 🎯 Positioning Strategy
+
+### Target Segments
+
+1. **Primary:** TypeScript developers using AI coding assistants (GitHub Copilot, Cursor, Windsurf, Claude, ChatGPT, Cline)
+2. **Secondary:** Teams implementing DDD/Clean Architecture
+3. **Tertiary:** Startups/scale-ups needing fast quality enforcement
+
+### Messaging
+
+**Tagline:** "The AI-First Architecture Guardian"
+
+**Key Messages:**
+- "Catches the #1 AI mistake: hardcoded values everywhere"
+- "Enforces Clean Architecture that AI often ignores"
+- "Closes the AI feedback loop for cleaner code"
+- "The only tool with auto-fix for architecture" (v0.9+)
+
+### Differentiation
+
+**Guardian ≠ SonarQube:** We're specialized for TypeScript DDD, not multi-language security
+**Guardian ≠ dependency-cruiser:** We detect patterns, not just dependencies
+**Guardian ≠ ESLint:** We enforce architecture, not syntax
+
+**Guardian = ESLint for architecture + AI code reviewer**
+
+---
+
+## 📚 Document Guide
+
+### ROADMAP_NEW.md
+
+**Purpose:** Complete technical roadmap with reprioritized features
+**Audience:** Development team, contributors
+**Key Sections:**
+- Current state analysis
+- Phase 1: Market Parity (v0.6-v0.10)
+- Phase 2: DDD Specialization (v0.11-v0.32)
+- Phase 3: Enterprise Ecosystem (v1.0+)
+
+### COMPARISON.md
+
+**Purpose:** Marketing-focused comparison with all competitors
+**Audience:** Users, potential adopters, marketing
+**Key Sections:**
+- Feature comparison matrix
+- Detailed tool comparisons
+- When to use each tool
+- Use case recommendations
+- Winner by category
+
+### v0.6.0-CONFIGURATION-SPEC.md
+
+**Purpose:** Technical specification for Configuration feature
+**Audience:** Development team
+**Key Sections:**
+- Configuration file format
+- Preset system design
+- Rule configuration
+- Implementation plan (8 weeks)
+- Testing strategy
+
+---
+
+## 🎬 Next Steps
+
+### Week 1-2: Planning & Kickoff
+
+- [ ] Review all three documents
+- [ ] Approve new roadmap priorities
+- [ ] Create GitHub milestones for v0.6.0-v0.10.0
+- [ ] Create implementation issues for v0.6.0
+- [ ] Update main README.md with comparison table
+
+### Week 3-10: v0.6.0 Development
+
+- [ ] Phase 1: Core Configuration (Week 3-4)
+- [ ] Phase 2: Rule Configuration (Week 4-5)
+- [ ] Phase 3: Preset System (Week 5-6)
+- [ ] Phase 4: Ignore Patterns (Week 6-7)
+- [ ] Phase 5: CLI Integration (Week 7-8)
+- [ ] Phase 6: Documentation (Week 8-9)
+- [ ] Phase 7: Beta & Release (Week 9-10)
+
+### Post-v0.6.0
+
+- [ ] Start v0.7.0 (Visualization) planning
+- [ ] Marketing push (blog, Product Hunt, etc.)
+- [ ] Community feedback gathering
+
+---
+
+## ❓ Questions?
+
+**For technical questions:**
+- Email: fozilbek.samiyev@gmail.com
+- GitHub Issues: https://github.com/samiyev/puaros/issues
+
+**For strategic decisions:**
+- Review sessions: Schedule with team
+- Roadmap adjustments: Create GitHub discussion
+
+---
+
+## 📝 Changelog
+
+**2025-01-24:** Initial competitive analysis and roadmap revision
+- Created comprehensive competitor comparison
+- Reprioritized roadmap (Configuration moved to v0.6.0)
+- Added market parity phase (v0.6-v0.10)
+- Designed v0.6.0 Configuration specification
+
+---
+
+**Status:** ✅ Analysis complete, ready for implementation
+
+**Confidence Level:** HIGH - Analysis based on thorough competitor research and market positioning
--- a/packages/guardian/docs/RESEARCH_CITATIONS.md
+++ b/packages/guardian/docs/RESEARCH_CITATIONS.md
--- a/packages/guardian/docs/RESEARCH_PROJECT_STRUCTURE_DETECTION.md
+++ b/packages/guardian/docs/RESEARCH_PROJECT_STRUCTURE_DETECTION.md
@@ -0,0 +1,979 @@
+# Research: Project Structure Detection for Architecture Analysis
+
+This document provides comprehensive research on approaches to detecting and validating project architecture structure. It covers existing tools, academic research, algorithms, and industry best practices that inform Guardian's architecture detection strategy.
+
+---
+
+## Table of Contents
+
+1. [Executive Summary](#1-executive-summary)
+2. [Existing Tools Analysis](#2-existing-tools-analysis)
+3. [Academic Approaches to Architecture Recovery](#3-academic-approaches-to-architecture-recovery)
+4. [Graph Analysis Algorithms](#4-graph-analysis-algorithms)
+5. [Configuration Patterns and Best Practices](#5-configuration-patterns-and-best-practices)
+6. [Industry Consensus](#6-industry-consensus)
+7. [Recommendations for Guardian](#7-recommendations-for-guardian)
+8. [Additional Resources](#8-additional-resources)
+
+---
+
+## 1. Executive Summary
+
+### Key Finding
+
+**Industry consensus:** Automatic architecture detection is unreliable. All major tools (ArchUnit, eslint-plugin-boundaries, Nx, dependency-cruiser, SonarQube) require **explicit configuration** from users rather than attempting automatic detection.
+
+### Why Automatic Detection Fails
+
+1. **Too Many Variations**: Project structures vary wildly across teams, frameworks, and domains
+2. **False Positives**: Algorithms may "detect" non-existent architectural patterns
+3. **Performance**: Graph analysis is slow for large codebases (>2000 files)
+4. **Ambiguity**: Same folder names can mean different things in different contexts
+5. **Legacy Code**: Poorly structured code produces meaningless analysis results
+
+### Recommended Approach
+
+| Priority | Approach | Description |
+|----------|----------|-------------|
+| P0 | Pattern-based detection | Glob/regex patterns for layer identification |
+| P0 | Configuration file | `.guardianrc.json` for explicit rules |
+| P1 | Presets | Pre-configured patterns for common architectures |
+| P1 | Generic mode | Fallback with minimal checks |
+| P2 | Interactive setup | CLI wizard for configuration generation |
+| P2 | Graph visualization | Visual dependency analysis (informational only) |
+| ❌ | Auto-detection | NOT recommended as primary strategy |
+
+---
+
+## 2. Existing Tools Analysis
+
+### 2.1 ArchUnit (Java)
+
+**Approach:** Fully declarative - user defines all layers explicitly.
+
+**Official Website:** https://www.archunit.org/
+
+**User Guide:** https://www.archunit.org/userguide/html/000_Index.html
+
+**GitHub Repository:** https://github.com/TNG/ArchUnit
+
+**Key Characteristics:**
+- Does NOT detect architecture automatically
+- User explicitly defines layers via package patterns
+- Fluent API for rule definition
+- Supports Layered, Onion, and Hexagonal architectures out-of-box
+- Integrates with JUnit/TestNG test frameworks
+
+**Example Configuration:**
+```java
+layeredArchitecture()
+    .layer("Controller").definedBy("..controller..")
+    .layer("Service").definedBy("..service..")
+    .layer("Persistence").definedBy("..persistence..")
+    .whereLayer("Controller").mayNotBeAccessedByAnyLayer()
+    .whereLayer("Service").mayOnlyBeAccessedByLayers("Controller")
+    .whereLayer("Persistence").mayOnlyBeAccessedByLayers("Service")
+```
+
+**References:**
+- Baeldung Tutorial: https://www.baeldung.com/java-archunit-intro
+- InfoQ Article: https://www.infoq.com/news/2022/10/archunit/
+- Examples Repository: https://github.com/TNG/ArchUnit-Examples
+
+---
+
+### 2.2 eslint-plugin-boundaries (TypeScript/JavaScript)
+
+**Approach:** Pattern-based element definition with dependency rules.
+
+**NPM Package:** https://www.npmjs.com/package/eslint-plugin-boundaries
+
+**GitHub Repository:** https://github.com/javierbrea/eslint-plugin-boundaries
+
+**Key Characteristics:**
+- Does NOT detect architecture automatically
+- Uses micromatch/glob patterns for element identification
+- Supports capture groups for dynamic element naming
+- TypeScript import type awareness (`value` vs `type` imports)
+- Works with monorepos
+
+**Example Configuration:**
+```javascript
+settings: {
+    "boundaries/elements": [
+        {
+            type: "domain",
+            pattern: "src/domain/*",
+            mode: "folder",
+            capture: ["elementName"]
+        },
+        {
+            type: "application",
+            pattern: "src/application/*",
+            mode: "folder"
+        },
+        {
+            type: "infrastructure",
+            pattern: "src/infrastructure/*",
+            mode: "folder"
+        }
+    ]
+},
+rules: {
+    "boundaries/element-types": [2, {
+        default: "disallow",
+        rules: [
+            { from: "infrastructure", allow: ["application", "domain"] },
+            { from: "application", allow: ["domain"] },
+            { from: "domain", disallow: ["*"] }
+        ]
+    }]
+}
+```
+
+**References:**
+- TypeScript Example: https://github.com/javierbrea/epb-ts-example
+- Element Types Documentation: https://github.com/javierbrea/eslint-plugin-boundaries/blob/master/docs/rules/element-types.md
+- Medium Tutorial: https://medium.com/@taynan_duarte/ensuring-dependency-rules-in-a-nodejs-application-with-typescript-using-eslint-plugin-boundaries-68b70ce32437
+
+---
+
+### 2.3 SonarQube Architecture as Code
+
+**Approach:** YAML/JSON configuration with automatic code structure analysis.
+
+**Official Documentation:** https://docs.sonarsource.com/sonarqube-server/design-and-architecture/overview/
+
+**Configuration Guide:** https://docs.sonarsource.com/sonarqube-server/design-and-architecture/configuring-the-architecture-analysis/
+
+**Key Characteristics:**
+- Introduced in SonarQube 2025 Release 2
+- Automatic code structure analysis (basic)
+- YAML/JSON configuration for custom rules
+- Supports "Perspectives" (multiple views of architecture)
+- Hierarchical "Groups" for organization
+- Glob and regex pattern support
+- Works without configuration for basic checks (cycle detection)
+
+**Supported Languages:**
+- Java (SonarQube Server)
+- Java, JavaScript, TypeScript (SonarQube Cloud)
+- Python, C# (coming soon)
+- C++ (under consideration)
+
+**Example Configuration:**
+```yaml
+# architecture.yaml
+perspectives:
+  - name: "Clean Architecture"
+    groups:
+      - name: "Domain"
+        patterns:
+          - "src/domain/**"
+          - "src/core/**"
+      - name: "Application"
+        patterns:
+          - "src/application/**"
+          - "src/use-cases/**"
+      - name: "Infrastructure"
+        patterns:
+          - "src/infrastructure/**"
+          - "src/adapters/**"
+    constraints:
+      - from: "Domain"
+        deny: ["Application", "Infrastructure"]
+      - from: "Application"
+        deny: ["Infrastructure"]
+```
+
+**References:**
+- Blog Announcement: https://www.sonarsource.com/blog/introducing-architecture-as-code-in-sonarqube/
+- Security Boulevard Coverage: https://securityboulevard.com/2025/04/introducing-architecture-as-code-in-sonarqube-7/
+
+---
+
+### 2.4 Nx Enforce Module Boundaries
+
+**Approach:** Tag-based system with ESLint integration.
+
+**Official Documentation:** https://nx.dev/docs/features/enforce-module-boundaries
+
+**ESLint Rule Guide:** https://nx.dev/docs/technologies/eslint/eslint-plugin/guides/enforce-module-boundaries
+
+**Key Characteristics:**
+- Tag-based constraint system (scope, type)
+- Projects tagged in project.json or package.json
+- Supports regex patterns in tags
+- Two-dimensional constraints (scope + type)
+- External dependency blocking
+- Integration with Nx project graph
+
+**Example Configuration:**
+```json
+// project.json
+{
+    "name": "user-domain",
+    "tags": ["scope:user", "type:domain"]
+}
+
+// ESLint config
+{
+    "@nx/enforce-module-boundaries": ["error", {
+        "depConstraints": [
+            {
+                "sourceTag": "type:domain",
+                "onlyDependOnLibsWithTags": ["type:domain"]
+            },
+            {
+                "sourceTag": "type:application",
+                "onlyDependOnLibsWithTags": ["type:domain", "type:application"]
+            },
+            {
+                "sourceTag": "scope:user",
+                "onlyDependOnLibsWithTags": ["scope:user", "scope:shared"]
+            }
+        ]
+    }]
+}
+```
+
+**References:**
+- Project Dependency Rules: https://nx.dev/docs/concepts/decisions/project-dependency-rules
+- Blog Post on Module Boundaries: https://nx.dev/blog/mastering-the-project-boundaries-in-nx
+- Medium Tutorial: https://medium.com/rupesh-tiwari/enforcing-dependency-constraints-within-service-in-nx-monorepo-workspace-56e87e792c98
+
+---
+
+### 2.5 dependency-cruiser
+
+**Approach:** Rule-based validation with visualization capabilities.
+
+**NPM Package:** https://www.npmjs.com/package/dependency-cruiser
+
+**GitHub Repository:** https://github.com/sverweij/dependency-cruiser
+
+**Key Characteristics:**
+- Regex patterns for from/to rules
+- Multiple output formats (SVG, DOT, Mermaid, JSON, HTML)
+- CI/CD integration support
+- TypeScript pre-compilation dependency support
+- Does NOT detect architecture automatically
+
+**Example Configuration:**
+```javascript
+// .dependency-cruiser.js
+module.exports = {
+    forbidden: [
+        {
+            name: "no-domain-to-infrastructure",
+            severity: "error",
+            from: { path: "^src/domain" },
+            to: { path: "^src/infrastructure" }
+        },
+        {
+            name: "no-circular",
+            severity: "error",
+            from: {},
+            to: { circular: true }
+        }
+    ],
+    options: {
+        doNotFollow: { path: "node_modules" },
+        tsPreCompilationDeps: true
+    }
+}
+```
+
+**References:**
+- Options Reference: https://github.com/sverweij/dependency-cruiser/blob/main/doc/options-reference.md
+- Rules Reference: https://github.com/sverweij/dependency-cruiser/blob/main/doc/rules-reference.md
+- Clean Architecture Tutorial: https://betterprogramming.pub/validate-dependencies-according-to-clean-architecture-743077ea084c
+
+---
+
+### 2.6 ts-arch / ArchUnitTS (TypeScript)
+
+**Approach:** ArchUnit-like fluent API for TypeScript.
+
+**ts-arch GitHub:** https://github.com/ts-arch/ts-arch
+
+**ts-arch Documentation:** https://ts-arch.github.io/ts-arch/
+
+**ArchUnitTS GitHub:** https://github.com/LukasNiessen/ArchUnitTS
+
+**Key Characteristics:**
+- Fluent API similar to ArchUnit
+- PlantUML diagram validation support
+- Jest/Vitest integration
+- Nx monorepo support
+- Does NOT detect architecture automatically
+
+**Example Usage:**
+```typescript
+import { filesOfProject } from "tsarch"
+
+// Folder-based dependency check
+const rule = filesOfProject()
+    .inFolder("domain")
+    .shouldNot()
+    .dependOnFiles()
+    .inFolder("infrastructure")
+
+await expect(rule).toPassAsync()
+
+// PlantUML diagram validation
+const rule = await slicesOfProject()
+    .definedBy("src/(**/)")
+    .should()
+    .adhereToDiagramInFile("architecture.puml")
+```
+
+**References:**
+- NPM Package: https://www.npmjs.com/package/tsarch
+- ArchUnitTS Documentation: https://lukasniessen.github.io/ArchUnitTS/
+- DeepWiki Analysis: https://deepwiki.com/ts-arch/ts-arch
+
+---
+
+### 2.7 Madge
+
+**Approach:** Visualization and circular dependency detection.
+
+**NPM Package:** https://www.npmjs.com/package/madge
+
+**GitHub Repository:** https://github.com/pahen/madge
+
+**Key Characteristics:**
+- Dependency graph visualization
+- Circular dependency detection
+- Multiple layout algorithms (dot, neato, fdp, circo)
+- Simple CLI interface
+- Does NOT define or enforce layers
+
+**Usage:**
+```bash
+# Find circular dependencies
+npx madge --circular src/
+
+# Generate dependency graph
+npx madge src/ --image deps.svg
+
+# TypeScript support
+npx madge src/main.ts --ts-config tsconfig.json --image ./deps.png
+```
+
+**References:**
+- NestJS Integration: https://manishbit97.medium.com/identifying-circular-dependencies-in-nestjs-using-madge-de137cd7f74f
+- Angular Integration: https://www.angulartraining.com/daily-newsletter/visualizing-internal-dependencies-with-madge/
+- React/TypeScript Tutorial: https://dev.to/greenroach/detecting-circular-dependencies-in-a-reacttypescript-app-using-madge-229
+
+**Alternative: Skott**
+- Claims to be 7x faster than Madge
+- Reference: https://dev.to/antoinecoulon/introducing-skott-the-new-madge-1bfl
+
+---
+
+## 3. Academic Approaches to Architecture Recovery
+
+### 3.1 Software Architecture Recovery Overview
+
+**Wikipedia Definition:** https://en.wikipedia.org/wiki/Software_architecture_recovery
+
+Software architecture recovery is a set of methods for extracting architectural information from lower-level representations of a software system, such as source code. The abstraction process frequently involves clustering source code entities (files, classes, functions) into subsystems according to application-dependent or independent criteria.
+
+**Motivation:**
+- Legacy systems often lack architectural documentation
+- Existing documentation is frequently out of sync with implementation
+- Understanding architecture is essential for maintenance and evolution
+
+---
+
+### 3.2 Machine Learning Approaches
+
+**Research Paper:** "Automatic software architecture recovery: A machine learning approach"
+
+**Source:** ResearchGate - https://www.researchgate.net/publication/261309157_Automatic_software_architecture_recovery_A_machine_learning_approach
+
+**Key Points:**
+- Current architecture recovery techniques require heavy human intervention or fail to recover quality components
+- Machine learning techniques use multiple feature types:
+  - Structural features (dependencies, coupling)
+  - Runtime behavioral features
+  - Domain/textual features
+  - Contextual features (code authorship, line co-change)
+- Automatically recovering functional architecture facilitates developer understanding
+
+**Limitation:** Requires training data and may not generalize across project types.
+
+---
+
+### 3.3 Genetic Algorithms for Architecture Recovery
+
+**Research Paper:** "Parallelization of genetic algorithms for software architecture recovery"
+
+**Source:** Springer - https://link.springer.com/content/pdf/10.1007/s10515-024-00479-0.pdf
+
+**Key Points:**
+- Software Architecture Recovery (SAR) techniques analyze dependencies between modules
+- Automatically cluster modules to achieve high modularity
+- Many approaches employ Genetic Algorithms (GAs)
+- Major drawback: lack of scalability
+- Solution: parallel execution of GA subroutines
+
+**Finding:** Finding optimal software clustering is an NP-complete problem.
+
+---
+
+### 3.4 Clustering Algorithms Comparison
+
+**Research Paper:** "A comparative analysis of software architecture recovery techniques"
+
+**Source:** IEEE Xplore - https://ieeexplore.ieee.org/document/6693106/
+
+**Algorithms Compared:**
+| Algorithm | Description | Strengths | Weaknesses |
+|-----------|-------------|-----------|------------|
+| ACDC | Comprehension-Driven Clustering | Finds natural subsystems | Requires parameter tuning |
+| LIMBO | Information-Theoretic Clustering | Scalable | May miss domain patterns |
+| WCA | Weighted Combined Algorithm | Balances multiple factors | Complex configuration |
+| K-means | Baseline clustering | Simple, fast | Poor for code structure |
+
+**Key Finding:** Even the best techniques have surprisingly low accuracy when compared against verified ground truths.
+
+---
+
+### 3.5 ACDC Algorithm (Algorithm for Comprehension-Driven Clustering)
+
+**Original Paper:** "ACDC: An Algorithm for Comprehension-Driven Clustering"
+
+**Source:** ResearchGate - https://www.researchgate.net/publication/221200422_ACDC_An_Algorithm_for_Comprehension-Driven_Clustering
+
+**York University Wiki:** https://wiki.eecs.yorku.ca/project/cluster/protected:acdc
+
+**Algorithm Steps:**
+1. Build dependency graph
+2. Find "dominator" nodes (subsystem patterns)
+3. Group nodes with common dominators
+4. Apply orphan adoption for ungrouped nodes
+5. Iteratively improve clusters
+
+**Advantages:**
+- Considers human comprehension patterns
+- Finds natural subsystems
+- Works without prior knowledge
+
+**Disadvantages:**
+- Requires parameter tuning
+- Does not guarantee optimality
+- May not work well on poorly structured code
+
+---
+
+### 3.6 LLM-Based Architecture Recovery (Recent Research)
+
+**Research Paper:** "Automated Software Architecture Design Recovery from Source Code Using LLMs"
+
+**Source:** Springer - https://link.springer.com/chapter/10.1007/978-3-032-02138-0_5
+
+**Key Findings:**
+- LLMs show promise for automating software architecture recovery
+- Effective at identifying:
+  - ✅ Architectural styles
+  - ✅ Structural elements
+  - ✅ Basic design patterns
+- Struggle with:
+  - ❌ Complex abstractions
+  - ❌ Class relationships
+  - ❌ Fine-grained design patterns
+
+**Conclusion:** "LLMs can support SAR activities, particularly in identifying structural and stylistic elements, but they struggle with complex abstractions"
+
+**Additional Reference:** arXiv paper on design principles - https://arxiv.org/html/2508.11717
+
+---
+
+## 4. Graph Analysis Algorithms
+
+### 4.1 Louvain Algorithm for Community Detection
+
+**Wikipedia:** https://en.wikipedia.org/wiki/Louvain_method
+
+**Original Paper:** "Fast unfolding of communities in large networks" (2008)
+- Authors: Vincent D Blondel, Jean-Loup Guillaume, Renaud Lambiotte, Etienne Lefebvre
+- Journal: Journal of Statistical Mechanics: Theory and Experiment
+- Reference: https://perso.uclouvain.be/vincent.blondel/research/louvain.html
+
+**Algorithm Description:**
+1. Initialize each node as its own community
+2. For each node, try moving to neighboring communities
+3. Select move with maximum modularity gain
+4. Merge communities into "super-nodes"
+5. Repeat from step 2
+
+**Modularity Formula:**
+```
+Q = (1/2m) * Σ[Aij - (ki*kj)/(2m)] * δ(ci, cj)
+
+Where:
+- Aij = edge weight between i and j
+- ki, kj = node degrees
+- m = sum of all weights
+- δ = 1 if ci = cj (same cluster)
+```
+
+**Characteristics:**
+| Parameter | Value |
+|-----------|-------|
+| Time Complexity | O(n log n) |
+| Modularity Range | -1 to 1 |
+| Good Result | Q > 0.3 |
+| Resolution Limit | Yes (may hide small communities) |
+
+**Implementations:**
+- NetworkX: https://networkx.org/documentation/stable/reference/algorithms/generated/networkx.algorithms.community.louvain.louvain_communities.html
+- Neo4j: https://neo4j.com/docs/graph-data-science/current/algorithms/louvain/
+- Graphology: https://graphology.github.io/standard-library/communities-louvain.html
+- igraph: https://igraph.org/r/doc/cluster_louvain.html
+
+**Application to Code Analysis:**
+```
+Dependency Graph:
+User.ts → Email.ts, UserId.ts
+Order.ts → OrderId.ts, Money.ts
+UserController.ts → User.ts, CreateUser.ts
+
+Louvain detects communities:
+Community 1: [User.ts, Email.ts, UserId.ts]        // User aggregate
+Community 2: [Order.ts, OrderId.ts, Money.ts]      // Order aggregate
+Community 3: [UserController.ts, CreateUser.ts]   // User feature
+```
+
+---
+
+### 4.2 Modularity as Quality Metric
+
+**Wikipedia:** https://en.wikipedia.org/wiki/Modularity_(networks)
+
+**Definition:** Modularity measures the strength of division of a network into modules (groups, clusters, communities). Networks with high modularity have dense connections within modules but sparse connections between modules.
+
+**Interpretation:**
+| Modularity Value | Interpretation |
+|------------------|----------------|
+| Q < 0 | Non-modular (worse than random) |
+| 0 < Q < 0.3 | Weak community structure |
+| 0.3 < Q < 0.5 | Moderate community structure |
+| Q > 0.5 | Strong community structure |
+| Q → 1 | Perfect modularity |
+
+**Research Reference:** "Fast Algorithm for Modularity-Based Graph Clustering" - https://cdn.aaai.org/ojs/8455/8455-13-11983-1-2-20201228.pdf
+
+---
+
+### 4.3 Graph-Based Software Modularization
+
+**Research Paper:** "A graph-based clustering algorithm for software systems modularization"
+
+**Source:** ScienceDirect - https://www.sciencedirect.com/science/article/abs/pii/S0950584920302147
+
+**Key Points:**
+- Clustering algorithms partition source code into manageable modules
+- Resulting decomposition is called software system structure
+- Due to NP-hardness, evolutionary approaches are commonly used
+- Objectives:
+  - Minimize inter-cluster connections
+  - Maximize intra-cluster connections
+  - Maximize overall clustering quality
+
+---
+
+### 4.4 Topological Sorting for Layer Detection
+
+**Algorithm Description:**
+
+Layers can be inferred from dependency graph topology:
+- **Layer 0 (Domain)**: Nodes with no outgoing dependencies to other layers
+- **Layer 1 (Application)**: Nodes depending only on Layer 0
+- **Layer 2+ (Infrastructure)**: Nodes depending on lower layers
+
+**Pseudocode:**
+```
+function detectLayers(graph):
+    layers = Map()
+    visited = Set()
+
+    function dfs(node):
+        if layers.has(node): return layers.get(node)
+        if visited.has(node): return 0  // Cycle detected
+
+        visited.add(node)
+        deps = graph.getDependencies(node)
+
+        if deps.isEmpty():
+            layers.set(node, 0)  // Leaf node = Domain
+            return 0
+
+        maxDepth = max(deps.map(dfs))
+        layers.set(node, maxDepth + 1)
+        return maxDepth + 1
+
+    graph.nodes.forEach(dfs)
+    return layers
+```
+
+**Limitation:** Assumes acyclic graph; circular dependencies break this approach.
+
+---
+
+### 4.5 Graph Metrics for Code Quality Assessment
+
+**Useful Metrics:**
+| Metric | Description | Good Value |
+|--------|-------------|------------|
+| Modularity | Clustering quality | > 0.3 |
+| Density | Edge/node ratio | Low for good separation |
+| Clustering Coefficient | Local clustering | Domain-dependent |
+| Cyclic Rate | % of circular deps | < 0.1 (10%) |
+| Average Path Length | Mean dependency distance | Lower = more coupled |
+
+**Code Quality Interpretation:**
+```
+if cyclicRate > 0.5:
+    return "SPAGHETTI"  // Cannot determine architecture
+if modularity < 0.2:
+    return "MONOLITH"   // No clear separation
+if modularity > 0.5:
+    return "WELL_STRUCTURED"  // Can determine layers
+return "MODERATE"
+```
+
+---
+
+## 5. Configuration Patterns and Best Practices
+
+### 5.1 Pattern Hierarchy
+
+**Level 1: Minimal Configuration**
+```json
+{
+    "architecture": "clean-architecture"
+}
+```
+
+**Level 2: Custom Paths**
+```json
+{
+    "architecture": "clean-architecture",
+    "layers": {
+        "domain": ["src/core", "src/domain"],
+        "application": ["src/app", "src/use-cases"],
+        "infrastructure": ["src/infra", "src/adapters"]
+    }
+}
+```
+
+**Level 3: Full Control**
+```json
+{
+    "layers": [
+        {
+            "name": "domain",
+            "patterns": ["src/domain/**", "**/*.entity.ts"],
+            "allowDependOn": []
+        },
+        {
+            "name": "application",
+            "patterns": ["src/application/**", "**/*.use-case.ts"],
+            "allowDependOn": ["domain"]
+        },
+        {
+            "name": "infrastructure",
+            "patterns": ["src/infrastructure/**", "**/*.controller.ts"],
+            "allowDependOn": ["domain", "application"]
+        }
+    ]
+}
+```
+
+---
+
+### 5.2 Architecture Drift Detection in CI/CD
+
+**Best Practices from Industry:**
+
+**Source:** Firefly Academy - https://www.firefly.ai/academy/implementing-continuous-drift-detection-in-ci-cd-pipelines-with-github-actions-workflow
+
+**Source:** Brainboard Blog - https://blog.brainboard.co/drift-detection-best-practices/
+
+**Key Recommendations:**
+
+1. **Integrate into Pipeline**: Validate architecture on every code update
+2. **Continuous Monitoring**: Run automated scans daily minimum, hourly for active projects
+3. **Enforce IaC-Only Changes**: All changes through automated workflows
+4. **Automated Reconciliation**: Regular drift detection and correction
+5. **Proper Alerting**: Slack for minor drift, PagerDuty for critical
+6. **Least Privilege**: Limit who can bypass architecture checks
+7. **Emergency Process**: Document process for urgent manual changes
+8. **Environment Refresh**: Reset after each pipeline run
+
+**Example GitHub Actions Integration:**
+```yaml
+name: Architecture Check
+
+on: [push, pull_request]
+
+jobs:
+    architecture:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Check Architecture
+              run: npx guardian check --strict
+
+            - name: Generate Report
+              if: failure()
+              run: npx guardian report --format html
+
+            - name: Upload Report
+              if: failure()
+              uses: actions/upload-artifact@v3
+              with:
+                  name: architecture-report
+                  path: architecture-report.html
+```
+
+---
+
+### 5.3 Presets for Common Architectures
+
+**Clean Architecture Preset:**
+```json
+{
+    "preset": "clean-architecture",
+    "layers": {
+        "domain": {
+            "patterns": ["**/domain/**", "**/entities/**", "**/core/**"],
+            "allowDependOn": []
+        },
+        "application": {
+            "patterns": ["**/application/**", "**/use-cases/**", "**/services/**"],
+            "allowDependOn": ["domain"]
+        },
+        "infrastructure": {
+            "patterns": ["**/infrastructure/**", "**/adapters/**", "**/api/**"],
+            "allowDependOn": ["domain", "application"]
+        }
+    }
+}
+```
+
+**Hexagonal Architecture Preset:**
+```json
+{
+    "preset": "hexagonal",
+    "layers": {
+        "core": {
+            "patterns": ["**/core/**", "**/domain/**"],
+            "allowDependOn": []
+        },
+        "ports": {
+            "patterns": ["**/ports/**"],
+            "allowDependOn": ["core"]
+        },
+        "adapters": {
+            "patterns": ["**/adapters/**", "**/infrastructure/**"],
+            "allowDependOn": ["core", "ports"]
+        }
+    }
+}
+```
+
+**NestJS Preset:**
+```json
+{
+    "preset": "nestjs",
+    "layers": {
+        "domain": {
+            "patterns": ["**/*.entity.ts", "**/entities/**"],
+            "allowDependOn": []
+        },
+        "application": {
+            "patterns": ["**/*.service.ts", "**/*.use-case.ts"],
+            "allowDependOn": ["domain"]
+        },
+        "infrastructure": {
+            "patterns": ["**/*.controller.ts", "**/*.module.ts", "**/*.resolver.ts"],
+            "allowDependOn": ["domain", "application"]
+        }
+    }
+}
+```
+
+---
+
+## 6. Industry Consensus
+
+### 6.1 Why Major Tools Don't Auto-Detect
+
+| Tool | Auto-Detection | Reasoning |
+|------|----------------|-----------|
+| ArchUnit | ❌ No | "User knows their architecture best" |
+| eslint-plugin-boundaries | ❌ No | "Too many structure variations" |
+| Nx | ❌ No | "Tag-based approach is more flexible" |
+| dependency-cruiser | ❌ No | "Regex patterns cover all cases" |
+| SonarQube | ⚠️ Partial | "Basic analysis + config for accuracy" |
+
+### 6.2 Common Themes Across Tools
+
+1. **Explicit Configuration**: All tools require user-defined rules
+2. **Pattern Matching**: Glob/regex patterns are universal
+3. **Layered Rules**: Allow/deny dependencies between layers
+4. **CI/CD Integration**: All support pipeline integration
+5. **Visualization**: Optional but valuable for understanding
+
+### 6.3 Graph Analysis Position
+
+Graph analysis is used for:
+- ✅ Circular dependency detection
+- ✅ Visualization
+- ✅ Metrics calculation
+- ✅ Suggestion generation
+
+Graph analysis is NOT used for:
+- ❌ Primary layer detection
+- ❌ Automatic architecture classification
+- ❌ Rule enforcement
+
+---
+
+## 7. Recommendations for Guardian
+
+### 7.1 Recommended Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Configuration Layer                       │
+├─────────────────────────────────────────────────────────────┤
+│  .guardianrc.json │ package.json │ CLI args │ Interactive   │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Strategy Resolver                         │
+├─────────────────────────────────────────────────────────────┤
+│  1. Explicit Config (if .guardianrc.json exists)            │
+│  2. Preset Detection (if preset specified)                  │
+│  3. Smart Defaults (standard patterns)                      │
+│  4. Generic Mode (fallback - minimal checks)                │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Analysis Engine                           │
+├─────────────────────────────────────────────────────────────┤
+│  Pattern Matcher │ Layer Detector │ Dependency Analyzer     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 7.2 Implementation Priorities
+
+**Phase 1: Configuration File Support**
+- Add `.guardianrc.json` parser
+- Support custom layer patterns
+- Support custom DDD folder names
+- Validate configuration on load
+
+**Phase 2: Presets System**
+- Clean Architecture preset
+- Hexagonal Architecture preset
+- NestJS preset
+- Feature-based preset
+
+**Phase 3: Smart Defaults**
+- Try standard folder names first
+- Fall back to file naming patterns
+- Support common conventions
+
+**Phase 4: Interactive Setup**
+- `guardian init` command
+- Project structure scanning
+- Configuration file generation
+- Preset recommendations
+
+**Phase 5: Generic Mode**
+- Minimal checks without layer knowledge
+- Hardcode detection
+- Secret detection
+- Circular dependency detection
+- Basic naming conventions
+
+### 7.3 Graph Analysis - Optional Feature Only
+
+Graph analysis should be:
+- **Optional**: Not required for basic functionality
+- **Informational**: For visualization and metrics
+- **Suggestive**: Can propose configuration, not enforce it
+
+**CLI Commands:**
+```bash
+guardian analyze --graph --output deps.svg    # Visualization
+guardian metrics                               # Quality metrics
+guardian suggest                               # Configuration suggestions
+```
+
+---
+
+## 8. Additional Resources
+
+### Official Documentation
+
+- ArchUnit: https://www.archunit.org/userguide/html/000_Index.html
+- eslint-plugin-boundaries: https://github.com/javierbrea/eslint-plugin-boundaries
+- SonarQube Architecture: https://docs.sonarsource.com/sonarqube-server/design-and-architecture/overview/
+- Nx Module Boundaries: https://nx.dev/docs/features/enforce-module-boundaries
+- dependency-cruiser: https://github.com/sverweij/dependency-cruiser
+
+### Academic Papers
+
+- Software Architecture Recovery (Wikipedia): https://en.wikipedia.org/wiki/Software_architecture_recovery
+- ACDC Algorithm: https://www.researchgate.net/publication/221200422_ACDC_An_Algorithm_for_Comprehension-Driven_Clustering
+- Louvain Method: https://en.wikipedia.org/wiki/Louvain_method
+- Graph Modularity: https://en.wikipedia.org/wiki/Modularity_(networks)
+- LLM-based SAR: https://link.springer.com/chapter/10.1007/978-3-032-02138-0_5
+
+### Tutorials and Guides
+
+- Clean Architecture Validation: https://betterprogramming.pub/validate-dependencies-according-to-clean-architecture-743077ea084c
+- Drift Detection Best Practices: https://blog.brainboard.co/drift-detection-best-practices/
+- Louvain Algorithm Tutorial: https://medium.com/data-science-in-your-pocket/community-detection-in-a-graph-using-louvain-algorithm-with-example-7a77e5e4b079
+
+### Related Books
+
+- **Clean Architecture** by Robert C. Martin (2017) - ISBN: 978-0134494166
+- **Domain-Driven Design** by Eric Evans (2003) - ISBN: 978-0321125217
+- **Implementing Domain-Driven Design** by Vaughn Vernon (2013) - ISBN: 978-0321834577
+
+---
+
+## Conclusion
+
+The research conclusively shows that **automatic architecture detection is unreliable** and **not used by major industry tools**. The recommended approach for Guardian is:
+
+1. **Configuration-first**: Support explicit layer definitions via `.guardianrc.json`
+2. **Pattern-based**: Use glob/regex patterns for flexible matching
+3. **Presets**: Provide pre-configured patterns for common architectures
+4. **Smart defaults**: Try standard conventions when no config exists
+5. **Generic fallback**: Provide useful checks even without architecture knowledge
+6. **Graph analysis as optional**: Use for visualization and suggestions only
+
+This approach aligns with industry best practices from ArchUnit, eslint-plugin-boundaries, SonarQube, Nx, and dependency-cruiser.
+
+---
+
+**Document Version**: 1.0
+**Last Updated**: 2025-11-27
+**Author**: Guardian Research Team
+**Questions or contributions?**
+- 📧 Email: fozilbek.samiyev@gmail.com
+- 🐙 GitHub: https://github.com/samiyev/puaros/issues
+**Based on research as of**: November 2025
--- a/packages/guardian/docs/ROADMAP_NEW.md
+++ b/packages/guardian/docs/ROADMAP_NEW.md
@@ -0,0 +1,906 @@
+# Guardian Roadmap 🗺️
+
+**Last Updated:** 2025-01-24
+**Current Version:** 0.5.1
+
+This document outlines the current features and strategic roadmap for @puaros/guardian, prioritized based on market competition analysis and enterprise adoption requirements.
+
+---
+
+## 📊 Current State (v0.5.1) ✅
+
+### ✨ Unique Competitive Advantages
+
+Guardian currently has **5 unique features** that competitors don't offer:
+
+| Feature | Status | Competitors |
+|---------|--------|-------------|
+| **Hardcode Detection + AI Suggestions** | ✅ Released | ❌ None |
+| **Framework Leak Detection** | ✅ Released | ❌ None |
+| **Entity Exposure Detection** | ✅ Released (v0.3.0) | ❌ None |
+| **Dependency Direction Enforcement** | ✅ Released (v0.4.0) | ⚠️ dependency-cruiser (via rules) |
+| **Repository Pattern Validation** | ✅ Released (v0.5.0) | ❌ None |
+
+### 🛠️ Core Features (v0.1.0-v0.5.0)
+
+**Detection Capabilities:**
+- ✅ Hardcode detection (magic numbers, magic strings) with smart suggestions
+- ✅ Circular dependency detection
+- ✅ Naming convention enforcement (DDD layer-based rules)
+- ✅ Clean Architecture layer violations
+- ✅ Framework leak detection (domain importing frameworks)
+- ✅ Entity exposure in API responses (v0.3.0)
+- ✅ Dependency direction validation (v0.4.0)
+- ✅ Repository pattern validation (v0.5.0)
+
+**Developer Experience:**
+- ✅ CLI interface with `guardian check` command
+- ✅ Smart constant name suggestions
+- ✅ Layer distribution analysis
+- ✅ Detailed violation reports with file:line:column
+- ✅ Context snippets for each issue
+
+**Quality & Testing:**
+- ✅ 194 tests across 7 test files (all passing)
+- ✅ 80%+ code coverage on all metrics
+- ✅ Self-analysis: 0 violations (100% clean codebase)
+
+---
+
+## 🎯 Strategic Roadmap Overview
+
+### Phase 1: Market Parity (v0.6-v0.10) - Q1-Q2 2026
+**Goal:** Match competitors' baseline features to enable enterprise adoption
+
+- Configuration & Presets
+- Visualization & Dependency Graphs
+- CI/CD Integration Kit
+- Auto-Fix & Code Generation (UNIQUE!)
+- Metrics & Quality Score
+
+### Phase 2: DDD Specialization (v0.11-v0.27) - Q3-Q4 2026
+**Goal:** Deepen DDD/Clean Architecture expertise
+
+- Advanced DDD pattern detection (25+ features)
+- Aggregate boundaries, Domain Events, Value Objects
+- CQRS, Saga Pattern, Anti-Corruption Layer
+- Ubiquitous Language validation
+
+### Phase 3: Enterprise Ecosystem (v1.0+) - Q4 2026+
+**Goal:** Full-featured enterprise platform
+
+- VS Code extension
+- JetBrains plugin
+- Web dashboard
+- Team analytics
+- Multi-language support
+
+---
+
+## 📅 Detailed Roadmap
+
+## Version 0.6.0 - Configuration & Presets ⚙️
+**Target:** Q1 2026 (January-February)
+**Priority:** 🔥 CRITICAL
+
+> **Why Critical:** All competitors (SonarQube, ESLint, dependency-cruiser) have configuration. Without this, Guardian cannot be customized for different teams/projects.
+
+### Features
+
+#### 1. Configuration File Support
+
+```javascript
+// guardian.config.js (primary)
+export default {
+    // Zero-config presets
+    preset: 'clean-architecture',  // or 'ddd', 'hexagonal', 'onion'
+
+    // Rule configuration
+    rules: {
+        'hardcode/magic-numbers': 'error',
+        'hardcode/magic-strings': 'warn',
+        'architecture/layer-violation': 'error',
+        'architecture/framework-leak': 'error',
+        'architecture/entity-exposure': 'error',
+        'circular-dependency': 'error',
+        'naming-convention': 'warn',
+        'dependency-direction': 'error',
+        'repository-pattern': 'error',
+    },
+
+    // Custom layer paths
+    layers: {
+        domain: 'src/core/domain',
+        application: 'src/core/application',
+        infrastructure: 'src/adapters',
+        shared: 'src/shared',
+    },
+
+    // Exclusions
+    exclude: [
+        '**/*.test.ts',
+        '**/*.spec.ts',
+        'scripts/',
+        'migrations/',
+        'node_modules/',
+    ],
+
+    // Per-rule ignores
+    ignore: {
+        'hardcode/magic-numbers': {
+            'src/config/constants.ts': [3000, 8080],
+        },
+    },
+}
+```
+
+#### 2. Built-in Presets
+
+```javascript
+// Preset: clean-architecture (default)
+preset: 'clean-architecture'
+// Enables: layer-violation, dependency-direction, naming-convention
+
+// Preset: ddd
+preset: 'ddd'
+// Enables all DDD patterns: aggregates, value-objects, domain-events
+
+// Preset: hexagonal (Ports & Adapters)
+preset: 'hexagonal'
+// Validates port/adapter separation
+
+// Preset: minimal (for prototyping)
+preset: 'minimal'
+// Only critical rules: hardcode, circular-deps
+```
+
+#### 3. Framework-Specific Presets
+
+```javascript
+// NestJS
+preset: 'nestjs-clean-architecture'
+
+// Express
+preset: 'express-clean-architecture'
+
+// Next.js
+preset: 'nextjs-clean-architecture'
+```
+
+#### 4. Configuration Discovery
+
+Support multiple config file formats:
+- `guardian.config.js` (ES modules)
+- `guardian.config.cjs` (CommonJS)
+- `.guardianrc` (JSON)
+- `.guardianrc.json`
+- `package.json` (`guardian` field)
+
+#### 5. CLI Override
+
+```bash
+# Override config from CLI
+guardian check ./src --rule hardcode/magic-numbers=off
+
+# Use specific config file
+guardian check ./src --config custom-config.js
+
+# Generate config
+guardian init --preset clean-architecture
+```
+
+### Implementation Tasks
+- [ ] Create config parser and validator
+- [ ] Implement preset system
+- [ ] Add config discovery logic
+- [ ] Update AnalyzeProject use case to accept config
+- [ ] CLI integration for config override
+- [ ] Add `guardian init` command
+- [ ] Documentation and examples
+- [ ] Tests (config parsing, presets, overrides)
+
+---
+
+## Version 0.7.0 - Visualization & Dependency Graphs 🎨
+**Target:** Q1 2026 (March)
+**Priority:** 🔥 HIGH
+
+> **Why High:** dependency-cruiser's main advantage is visualization. Guardian needs this to compete.
+
+### Features
+
+#### 1. Dependency Graph Visualization
+
+```bash
+# Generate SVG graph
+guardian visualize ./src --output architecture.svg
+
+# Interactive HTML
+guardian visualize ./src --format html --output report.html
+
+# Mermaid diagram for docs
+guardian graph ./src --format mermaid > ARCHITECTURE.md
+
+# ASCII tree for terminal
+guardian visualize ./src --format ascii
+```
+
+#### 2. Layer Dependency Diagram
+
+```mermaid
+graph TD
+    I[Infrastructure Layer] --> A[Application Layer]
+    I --> D[Domain Layer]
+    A --> D
+    D --> S[Shared]
+    A --> S
+    I --> S
+
+    style D fill:#4CAF50
+    style A fill:#2196F3
+    style I fill:#FF9800
+    style S fill:#9E9E9E
+```
+
+#### 3. Violation Highlighting
+
+Visualize violations on graph:
+- 🔴 Circular dependencies (red arrows)
+- ⚠️ Framework leaks (yellow highlights)
+- 🚫 Wrong dependency direction (dashed red arrows)
+- ✅ Correct dependencies (green arrows)
+
+#### 4. Metrics Overlay
+
+```bash
+guardian visualize ./src --show-metrics
+
+# Shows on each node:
+# - File count per layer
+# - Hardcode violations count
+# - Complexity score
+```
+
+#### 5. Export Formats
+
+- SVG (for docs/website)
+- PNG (for presentations)
+- HTML (interactive, zoomable)
+- Mermaid (for markdown docs)
+- DOT (Graphviz format)
+- JSON (for custom processing)
+
+### Implementation Tasks
+- [ ] Implement graph generation engine
+- [ ] Add SVG/PNG renderer
+- [ ] Create Mermaid diagram generator
+- [ ] Build HTML interactive viewer
+- [ ] Add violation highlighting
+- [ ] Metrics overlay system
+- [ ] CLI commands (`visualize`, `graph`)
+- [ ] Documentation and examples
+- [ ] Tests (graph generation, formats)
+
+---
+
+## Version 0.8.0 - CI/CD Integration Kit 🚀
+**Target:** Q2 2026 (April)
+**Priority:** 🔥 HIGH
+
+> **Why High:** Enterprise requires CI/CD integration. SonarQube succeeds because of this.
+
+### Features
+
+#### 1. GitHub Actions
+
+```yaml
+# .github/workflows/guardian.yml (ready-to-use template)
+name: Guardian Quality Check
+
+on: [push, pull_request]
+
+jobs:
+  guardian:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+
+      - name: Guardian Analysis
+        uses: puaros/guardian-action@v1
+        with:
+          path: './src'
+          fail-on: 'error'
+          report-format: 'markdown'
+
+      - name: Comment PR
+        uses: actions/github-script@v6
+        if: github.event_name == 'pull_request'
+        with:
+          script: |
+            // Auto-comment violations on PR
+```
+
+#### 2. GitLab CI Template
+
+```yaml
+# .gitlab-ci.yml
+include:
+  - template: Guardian.gitlab-ci.yml
+
+guardian_check:
+  stage: test
+  extends: .guardian
+  variables:
+    GUARDIAN_FAIL_ON: "error"
+    GUARDIAN_FORMAT: "markdown"
+```
+
+#### 3. Quality Gate
+
+```bash
+# Fail build on violations
+guardian check ./src --fail-on error
+guardian check ./src --fail-on warning
+
+# Threshold-based
+guardian check ./src --max-violations 10
+guardian check ./src --max-hardcode 5
+```
+
+#### 4. PR Auto-Comments
+
+Automatically comment on PRs with:
+- Summary of violations
+- Comparison with base branch
+- Quality score change
+- Actionable suggestions
+
+```markdown
+## 🛡️ Guardian Report
+
+**Quality Score:** 87/100 (⬆️ +3 from main)
+
+### Violations Found: 5
+
+#### 🔴 Critical (2)
+- `src/api/server.ts:15` - Hardcoded port 3000
+- `src/domain/User.ts:10` - Framework leak (Express)
+
+#### ⚠️ Warnings (3)
+- `src/services/UserService.ts` - Naming convention
+- ...
+
+[View Full Report](link)
+```
+
+#### 5. Pre-commit Hook
+
+```bash
+# Install via npx
+npx guardian install-hooks
+
+# Creates .husky/pre-commit
+#!/bin/sh
+guardian check --staged --fail-on error
+```
+
+#### 6. Status Checks
+
+Integrate with GitHub/GitLab status checks:
+- ✅ No violations
+- ⚠️ Warnings only
+- ❌ Errors found
+
+### Implementation Tasks
+- [ ] Create GitHub Action
+- [ ] Create GitLab CI template
+- [ ] Implement quality gate logic
+- [ ] Build PR comment generator
+- [ ] Pre-commit hook installer
+- [ ] Status check integration
+- [ ] Bitbucket Pipelines support
+- [ ] Documentation and examples
+- [ ] Tests (CI/CD scenarios)
+
+---
+
+## Version 0.9.0 - Auto-Fix & Code Generation 🤖
+**Target:** Q2 2026 (May)
+**Priority:** 🚀 GAME-CHANGER (UNIQUE!)
+
+> **Why Game-Changer:** No competitor has intelligent auto-fix for architecture. This makes Guardian unique!
+
+### Features
+
+#### 1. Auto-Fix Hardcode
+
+```bash
+# Fix all hardcode violations automatically
+guardian fix ./src --auto
+
+# Preview changes
+guardian fix ./src --dry-run
+
+# Fix specific types
+guardian fix ./src --type hardcode
+guardian fix ./src --type naming
+```
+
+**Example:**
+
+```typescript
+// Before
+const timeout = 5000
+app.listen(3000)
+
+// After (auto-generated constants.ts)
+export const DEFAULT_TIMEOUT_MS = 5000
+export const DEFAULT_PORT = 3000
+
+// After (fixed code)
+import { DEFAULT_TIMEOUT_MS, DEFAULT_PORT } from './constants'
+const timeout = DEFAULT_TIMEOUT_MS
+app.listen(DEFAULT_PORT)
+```
+
+#### 2. Generate Constants File
+
+```bash
+# Extract all hardcodes to constants
+guardian generate constants ./src --output src/config/constants.ts
+
+# Generated file:
+// src/config/constants.ts
+export const DEFAULT_TIMEOUT_MS = 5000
+export const DEFAULT_PORT = 3000
+export const MAX_RETRIES = 3
+export const API_BASE_URL = 'http://localhost:8080'
+```
+
+#### 3. Fix Naming Violations
+
+```bash
+# Rename files to match conventions
+guardian fix naming ./src --auto
+
+# Before: src/application/use-cases/user.ts
+# After:  src/application/use-cases/CreateUser.ts
+```
+
+#### 4. AI-Friendly Fix Prompts
+
+```bash
+# Generate prompt for AI assistant
+guardian check ./src --format ai-prompt > fix-prompt.txt
+
+# Output (optimized for Claude/GPT):
+"""
+Fix the following Guardian violations:
+
+1. HARDCODE (src/api/server.ts:15)
+   - Replace: app.listen(3000)
+   - With: Extract 3000 to DEFAULT_PORT constant
+   - Location: Create src/config/constants.ts
+
+2. FRAMEWORK_LEAK (src/domain/User.ts:5)
+   - Remove: import { Request } from 'express'
+   - Reason: Domain layer cannot import frameworks
+   - Suggestion: Use dependency injection via interfaces
+
+[Complete fix suggestions...]
+"""
+
+# Then feed to Claude:
+# cat fix-prompt.txt | pbcopy
+# Paste into Claude: "Fix these Guardian violations"
+```
+
+#### 5. Interactive Fix Mode
+
+```bash
+# Interactive fix selection
+guardian fix ./src --interactive
+
+# Prompts:
+# ? Fix hardcode in server.ts:15 (3000)? (Y/n)
+# ? Suggested constant name: DEFAULT_PORT
+#   [Edit name] [Skip] [Fix All]
+```
+
+#### 6. Refactoring Commands
+
+```bash
+# Break circular dependency
+guardian refactor circular ./src/services/UserService.ts
+# Suggests: Extract shared interface
+
+# Fix layer violation
+guardian refactor layer ./src/domain/entities/User.ts
+# Suggests: Move framework imports to infrastructure
+```
+
+### Implementation Tasks
+- [ ] Implement auto-fix engine (AST transformation)
+- [ ] Constants extractor and generator
+- [ ] File renaming system
+- [ ] AI prompt generator
+- [ ] Interactive fix mode
+- [ ] Refactoring suggestions
+- [ ] Safe rollback mechanism
+- [ ] Documentation and examples
+- [ ] Tests (fix scenarios, edge cases)
+
+---
+
+## Version 0.10.0 - Metrics & Quality Score 📊
+**Target:** Q2 2026 (June)
+**Priority:** 🔥 HIGH
+
+> **Why High:** Enterprise needs metrics to justify investment. SonarQube's dashboard is a major selling point.
+
+### Features
+
+#### 1. Quality Score (0-100)
+
+```bash
+guardian score ./src
+
+# Output:
+# 🛡️ Guardian Quality Score: 87/100 (Good)
+#
+# Category Breakdown:
+# ✅ Architecture:     95/100 (Excellent)
+# ⚠️ Hardcode:         78/100 (Needs Improvement)
+# ✅ Naming:           92/100 (Excellent)
+# ✅ Dependencies:     89/100 (Good)
+```
+
+**Score Calculation:**
+- Architecture violations: -5 per error
+- Hardcode violations: -1 per occurrence
+- Circular dependencies: -10 per cycle
+- Naming violations: -2 per error
+
+#### 2. Metrics Dashboard (JSON/HTML)
+
+```bash
+# Export metrics
+guardian metrics ./src --format json > metrics.json
+guardian metrics ./src --format html > dashboard.html
+
+# Metrics included:
+{
+  "qualityScore": 87,
+  "violations": {
+    "hardcode": 12,
+    "circular": 0,
+    "architecture": 2,
+    "naming": 5
+  },
+  "metrics": {
+    "totalFiles": 45,
+    "totalLOC": 3500,
+    "hardcodePerKLOC": 3.4,
+    "averageFilesPerLayer": 11.25
+  },
+  "trends": {
+    "scoreChange": "+5",
+    "violationsChange": "-8"
+  }
+}
+```
+
+#### 3. Trend Analysis
+
+```bash
+# Compare with main branch
+guardian metrics ./src --compare-with main
+
+# Output:
+# Quality Score: 87/100 (⬆️ +3 from main)
+#
+# Changes:
+# ✅ Hardcode violations: 12 (⬇️ -5)
+# ⚠️ Naming violations: 5 (⬆️ +2)
+# ✅ Circular deps: 0 (⬇️ -1)
+```
+
+#### 4. Historical Tracking
+
+```bash
+# Store metrics history
+guardian metrics ./src --save
+
+# View trends
+guardian trends --last 30d
+
+# Output: ASCII graph showing quality score over time
+```
+
+#### 5. Export for Dashboards
+
+```bash
+# Prometheus format
+guardian metrics ./src --format prometheus
+
+# Grafana JSON
+guardian metrics ./src --format grafana
+
+# CSV for Excel
+guardian metrics ./src --format csv
+```
+
+#### 6. Badge Generation
+
+```bash
+# Generate badge for README
+guardian badge ./src --output badge.svg
+
+# Markdown badge
+![Guardian Score](badge.svg)
+```
+
+### Implementation Tasks
+- [ ] Quality score calculation algorithm
+- [ ] Metrics collection system
+- [ ] Trend analysis engine
+- [ ] JSON/HTML/Prometheus exporters
+- [ ] Historical data storage
+- [ ] Badge generator
+- [ ] CLI commands (`score`, `metrics`, `trends`, `badge`)
+- [ ] Documentation and examples
+- [ ] Tests (metrics calculation, exports)
+
+---
+
+## Version 0.11.0+ - DDD Specialization 🏗️
+**Target:** Q3-Q4 2026
+**Priority:** MEDIUM (After Market Parity)
+
+Now we can focus on Guardian's unique DDD/Clean Architecture specialization:
+
+### v0.11.0 - Aggregate Boundary Validation 🔒
+- Detect entity references across aggregates
+- Enforce ID-only references between aggregates
+- Validate aggregate root access patterns
+
+### v0.12.0 - Anemic Domain Model Detection 🩺
+- Detect entities with only getters/setters
+- Count methods vs properties ratio
+- Suggest moving logic from services to entities
+
+### v0.13.0 - Domain Event Validation 📢
+- Validate event publishing pattern
+- Check events inherit from DomainEvent base
+- Detect direct infrastructure calls from entities
+
+### v0.14.0 - Value Object Immutability 🔐
+- Ensure Value Objects have readonly fields
+- Detect public setters
+- Verify equals() method exists
+
+### v0.15.0 - Use Case Single Responsibility 🎯
+- Check Use Case has single public method (execute)
+- Detect multiple responsibilities
+- Suggest splitting large Use Cases
+
+### v0.16.0 - Interface Segregation 🔌
+- Count methods per interface (> 10 = warning)
+- Check method cohesion
+- Suggest interface splitting
+
+### v0.17.0 - Port-Adapter Pattern 🔌
+- Check Ports (interfaces) are in application/domain
+- Verify Adapters are in infrastructure
+- Detect external library imports in use cases
+
+### v0.18.0 - Command Query Separation (CQRS) 📝
+- Detect methods that both change state and return data
+- Check Use Case names for CQS violations
+- Validate Command Use Cases return void
+
+### v0.19.0 - Factory Pattern Validation 🏭
+- Detect complex logic in entity constructors
+- Check for `new Entity()` calls in use cases
+- Suggest extracting construction to Factory
+
+### v0.20.0 - Specification Pattern Detection 🔍
+- Detect complex business rules in use cases
+- Validate Specification classes in domain
+- Suggest extracting rules to Specifications
+
+### v0.21.0 - Layered Service Anti-pattern ⚠️
+- Detect service methods operating on single entity
+- Validate entities have behavior methods
+- Suggest moving service methods to entities
+
+### v0.22.0 - Bounded Context Leak Detection 🚧
+- Detect entity imports across contexts
+- Validate only ID references between contexts
+- Verify event-based integration
+
+### v0.23.0 - Transaction Script Detection 📜
+- Detect procedural logic in use cases
+- Check use case length (> 30-50 lines = warning)
+- Suggest moving logic to domain entities
+
+### v0.24.0 - Persistence Ignorance 💾
+- Detect ORM decorators in domain entities
+- Check for ORM library imports in domain
+- Suggest persistence ignorance pattern
+
+### v0.25.0 - Null Object Pattern Detection 🎭
+- Count null checks in use cases
+- Suggest Null Object pattern
+- Detect repositories returning null vs Null Object
+
+### v0.26.0 - Primitive Obsession Detection 🔢
+- Detect methods with > 3 primitive parameters
+- Check for common Value Object candidates
+- Suggest creating Value Objects
+
+### v0.27.0 - Service Locator Anti-pattern 🔍
+- Detect global ServiceLocator/Registry classes
+- Validate constructor injection
+- Suggest DI container usage
+
+### v0.28.0 - Double Dispatch Pattern 🎯
+- Detect frequent instanceof or type checking
+- Check for long if-else/switch by type
+- Suggest Visitor pattern
+
+### v0.29.0 - Entity Identity Validation 🆔
+- Detect public mutable ID fields
+- Validate ID is Value Object
+- Check for equals() method implementation
+
+### v0.30.0 - Saga Pattern Detection 🔄
+- Detect multiple external calls without compensation
+- Validate compensating transactions
+- Suggest Saga pattern for distributed operations
+
+### v0.31.0 - Anti-Corruption Layer Detection 🛡️
+- Detect direct legacy library imports
+- Check for domain adaptation to external APIs
+- Validate translator/adapter layer exists
+
+### v0.32.0 - Ubiquitous Language Validation 📖
+**Priority: HIGH**
+- Detect synonyms for same concepts (User/Customer/Client)
+- Check inconsistent verbs (Create/Register/SignUp)
+- Require Ubiquitous Language glossary
+
+---
+
+## Version 1.0.0 - Stable Release 🚀
+**Target:** Q4 2026 (December)
+**Priority:** 🔥 CRITICAL
+
+Production-ready stable release with ecosystem:
+
+### Core Features
+- ✅ All detection features stabilized
+- ✅ Configuration & presets
+- ✅ Visualization & graphs
+- ✅ CI/CD integration
+- ✅ Auto-fix & code generation
+- ✅ Metrics & quality score
+- ✅ 30+ DDD pattern detectors
+
+### Ecosystem
+
+#### VS Code Extension
+- Real-time detection as you type
+- Inline suggestions and quick fixes
+- Problem panel integration
+- Code actions for auto-fix
+
+#### JetBrains Plugin
+- IntelliJ IDEA, WebStorm support
+- Inspection integration
+- Quick fixes
+
+#### Web Dashboard
+- Team quality metrics
+- Historical trends
+- Per-developer analytics
+- Project comparison
+
+#### GitHub Integration
+- GitHub App
+- Code scanning integration
+- Dependency insights
+- Security alerts for architecture violations
+
+---
+
+## 💡 Future Ideas (Post-1.0.0)
+
+### Multi-Language Support
+- Python (Django/Flask + DDD)
+- C# (.NET + Clean Architecture)
+- Java (Spring Boot + DDD)
+- Go (Clean Architecture)
+
+### AI-Powered Features
+- LLM-based fix suggestions
+- AI generates code for complex refactorings
+- Claude/GPT API integration
+- Natural language architecture queries
+
+### Team Analytics
+- Per-developer quality metrics
+- Team quality trends dashboard
+- Technical debt tracking
+- Leaderboards (gamification)
+
+### Security Features
+- Secrets detection (API keys, passwords)
+- SQL injection pattern detection
+- XSS vulnerability patterns
+- Dependency vulnerability scanning
+
+### Code Quality Metrics
+- Maintainability index
+- Technical debt estimation
+- Code duplication detection
+- Complexity trends
+
+---
+
+## 🎯 Success Criteria
+
+### v0.10.0 (Market Parity Achieved)
+- ✅ Configuration support (compete with ESLint)
+- ✅ Visualization (compete with dependency-cruiser)
+- ✅ CI/CD integration (compete with SonarQube)
+- ✅ Auto-fix (UNIQUE! Game-changer)
+- ✅ Metrics dashboard (compete with SonarQube)
+
+### v1.0.0 (Enterprise Ready)
+- ✅ 1000+ GitHub stars
+- ✅ 100+ npm installs/week
+- ✅ 10+ enterprise adopters
+- ✅ 99%+ test coverage
+- ✅ Complete documentation
+- ✅ IDE extensions available
+
+---
+
+## 📊 Competitive Positioning
+
+| Feature | Guardian v1.0 | SonarQube | dependency-cruiser | ArchUnit | FTA |
+|---------|---------------|-----------|-------------------|----------|-----|
+| TypeScript Focus | ✅✅ | ⚠️ | ✅✅ | ❌ | ✅✅ |
+| Hardcode + AI Tips | ✅✅ UNIQUE | ⚠️ | ❌ | ❌ | ❌ |
+| Architecture (DDD) | ✅✅ UNIQUE | ⚠️ | ⚠️ | ✅ | ❌ |
+| Visualization | ✅ | ✅ | ✅✅ | ❌ | ⚠️ |
+| Auto-Fix | ✅✅ UNIQUE | ❌ | ❌ | ❌ | ❌ |
+| Configuration | ✅ | ✅✅ | ✅ | ✅ | ⚠️ |
+| CI/CD | ✅ | ✅✅ | ✅ | ✅ | ⚠️ |
+| Metrics | ✅ | ✅✅ | ⚠️ | ❌ | ✅✅ |
+| Security (SAST) | ❌ | ✅✅ | ❌ | ❌ | ❌ |
+| Multi-language | ❌ | ✅✅ | ⚠️ | ⚠️ | ❌ |
+
+**Guardian's Position:** The AI-First Architecture Guardian for TypeScript/DDD teams
+
+---
+
+## 🤝 Contributing
+
+Want to help build Guardian? Check out:
+- [GitHub Issues](https://github.com/samiyev/puaros/issues)
+- [CONTRIBUTING.md](../../CONTRIBUTING.md)
+- [Discord Community](#) (coming soon)
+
+---
+
+## 📈 Versioning
+
+Guardian follows [Semantic Versioning](https://semver.org/):
+- **MAJOR** (1.0.0) - Breaking changes
+- **MINOR** (0.x.0) - New features, backwards compatible
+- **PATCH** (0.x.y) - Bug fixes
+
+Until 1.0.0, minor versions may include breaking changes as we iterate on the API.
--- a/packages/guardian/docs/WHY.md
+++ b/packages/guardian/docs/WHY.md
@@ -0,0 +1,590 @@
+# Why Guardian's Rules Matter
+
+Guardian's detection rules are not invented - they're based on decades of software engineering research, industry standards, and expert opinion from leading authorities.
+
+**Quick Navigation:**
+- [Hardcode Detection](#hardcode-detection)
+- [Circular Dependencies](#circular-dependencies)
+- [Clean Architecture](#clean-architecture)
+- [Framework Leaks](#framework-leaks)
+- [Entity Exposure](#entity-exposure)
+- [Repository Pattern](#repository-pattern)
+- [Naming Conventions](#naming-conventions)
+- [Anemic Domain Model Detection](#anemic-domain-model-detection)
+- [Aggregate Boundary Validation](#aggregate-boundary-validation)
+- [Secret Detection](#secret-detection)
+- [Severity-Based Prioritization](#severity-based-prioritization)
+- [Full Research Citations](#full-research-citations)
+
+---
+
+## Hardcode Detection
+
+### Why it matters
+
+Magic numbers and strings make code:
+- ❌ **Hard to maintain** - Changing a value requires finding all occurrences
+- ❌ **Error-prone** - Typos in repeated values cause bugs
+- ❌ **Difficult to understand** - What does `3000` mean without context?
+- ❌ **Not ready for change** - Configuration changes require code modifications
+
+### Who says so?
+
+**Academia:**
+- **MIT Course 6.031: Software Construction**
+  > "Magic numbers fail three key measures: Safe from bugs, Easy to understand, Ready for change"
+  - Used in MIT's software engineering curriculum
+  - [Read the course material](https://web.mit.edu/6.031/www/sp17/classes/04-code-review/)
+
+**Industry Standards:**
+- **SonarQube Rule RSPEC-109**: "Magic numbers should not be used"
+  - Used by 400,000+ organizations worldwide
+  - Identifies hardcoded values as code smells
+  - [View the rule](https://rules.sonarsource.com/c/rspec-109/)
+
+**Research:**
+- **2022 ScienceDirect Study**: "What do developers consider magic literals?"
+  - Analyzed 24,000 literals from 3,500+ methods
+  - Surveyed 26 professional developers
+  - [Read the paper](https://www.sciencedirect.com/science/article/abs/pii/S0950584922000908)
+
+**Historical Context:**
+- Anti-pattern dating back to 1960s COBOL/FORTRAN manuals
+- One of the oldest rules of programming
+
+[Read full research →](./RESEARCH_CITATIONS.md#1-hardcode-detection-magic-numbers--strings)
+
+---
+
+## Circular Dependencies
+
+### Why it matters
+
+Circular dependencies create:
+- ❌ **Tight coupling** - Components cannot evolve independently
+- ❌ **Testing difficulties** - Impossible to test modules in isolation
+- ❌ **Maintenance nightmares** - Changes cause ripple effects across codebase
+- ❌ **Build complexity** - Compilation order becomes problematic
+
+### Who says so?
+
+**Expert Opinion:**
+- **Martin Fowler**: Enterprise architecture patterns expert
+  > "Putting abstract classes in supertype package is good way of breaking cycles in the dependency structure"
+  - Recommends using abstraction to break cycles
+  - [Read on TechTarget](https://www.techtarget.com/searchapparchitecture/tip/The-vicious-cycle-of-circular-dependencies-in-microservices)
+
+**Real-world Solutions:**
+- **Shopify Engineering**: "Remove Circular Dependencies by Using Dependency Injection"
+  - Demonstrates practical application of Repository Pattern
+  - Production-proven solution from major tech company
+  - [Read the article](https://shopify.engineering/repository-pattern-ruby)
+
+**Impact Studies:**
+- Services become hardly maintainable and highly coupled
+- Open the door to error-prone applications
+- Components cannot be tested in isolation
+
+[Read full research →](./RESEARCH_CITATIONS.md#2-circular-dependencies)
+
+---
+
+## Clean Architecture
+
+### Why it matters
+
+Clean Architecture principles ensure:
+- ✅ **Independence** - Business rules don't depend on frameworks
+- ✅ **Testability** - Business logic can be tested without UI/DB
+- ✅ **Flexibility** - Easy to swap frameworks and tools
+- ✅ **Maintainability** - Clear boundaries and responsibilities
+
+### The Dependency Rule
+
+**Robert C. Martin's Core Principle:**
+> "Source code dependencies can only point inwards. Nothing in an inner circle can know anything about something in an outer circle."
+
+**Layer Flow:**
+```
+Domain (innermost) ← Application ← Infrastructure (outermost)
+```
+
+### Who says so?
+
+**The Definitive Book:**
+- **Robert C. Martin (Uncle Bob): "Clean Architecture" (2017)**
+  - Published by O'Reilly (Prentice Hall)
+  - Based on SOLID principles and decades of experience
+  - [Get the book](https://www.amazon.com/Clean-Architecture-Craftsmans-Software-Structure/dp/0134494164)
+
+**Core Principles:**
+- **SOLID Principles (2000)**: Foundation of Clean Architecture
+  - Single Responsibility Principle
+  - Open-Closed Principle
+  - Liskov Substitution Principle
+  - Interface Segregation Principle
+  - **Dependency Inversion Principle** (critical for layer separation)
+  - [Learn SOLID](https://www.digitalocean.com/community/conceptual-articles/s-o-l-i-d-the-first-five-principles-of-object-oriented-design)
+
+**The Clean Architecture Blog:**
+- Original blog post by Uncle Bob (2012)
+- Defines the concentric circles architecture
+- [Read the original](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
+
+[Read full research →](./RESEARCH_CITATIONS.md#3-clean-architecture--layered-architecture)
+
+---
+
+## Framework Leaks
+
+### Why it matters
+
+Framework dependencies in domain layer:
+- ❌ **Coupling to infrastructure** - Business logic tied to technical details
+- ❌ **Testing difficulties** - Cannot test without framework setup
+- ❌ **Framework lock-in** - Migration becomes impossible
+- ❌ **Violates Clean Architecture** - Breaks the Dependency Rule
+
+### Who says so?
+
+**Original Research:**
+- **Alistair Cockburn (2005): "Hexagonal Architecture"**
+  - HaT Technical Report 2005.02
+  > "Create your application to work without either a UI or a database so you can run automated regression-tests against the application, work when the database becomes unavailable, and link applications together without any user involvement."
+  - Original Ports & Adapters pattern
+  - [Read the original paper](https://alistair.cockburn.us/hexagonal-architecture)
+
+**Industry Adoption:**
+- **Robert C. Martin: "Clean Architecture" (2017)**
+  > "Frameworks are tools, not architectures"
+  - Frameworks belong in outer layers only
+
+- **AWS Prescriptive Guidance**: Documents hexagonal architecture patterns
+- **GitHub: Domain-Driven Hexagon**: Comprehensive implementation guide
+  - [View the guide](https://github.com/Sairyss/domain-driven-hexagon)
+
+**Key Insight:**
+The goal is to isolate the application's business logic from external resources like databases, message queues, HTTP frameworks, etc.
+
+[Read full research →](./RESEARCH_CITATIONS.md#4-framework-leak-detection)
+
+---
+
+## Entity Exposure
+
+### Why it matters
+
+Exposing domain entities directly:
+- ❌ **Breaks encapsulation** - Exposes internal domain structure
+- ❌ **Security risks** - May leak sensitive data (passwords, tokens)
+- ❌ **Coupling** - API tied to domain model changes
+- ❌ **Violates Single Responsibility** - Entities serve two purposes
+
+### Use DTOs Instead
+
+**Data Transfer Object (DTO) Pattern:**
+- Transform domain entities into simple data structures
+- Control exactly what data is exposed
+- Decouple API contracts from domain model
+- Separate concerns: domain logic vs. data transfer
+
+### Who says so?
+
+**The Definitive Source:**
+- **Martin Fowler: "Patterns of Enterprise Application Architecture" (2002)**
+  - Defines the DTO pattern
+  - Published by Addison-Wesley
+  > "An object that carries data between processes in order to reduce the number of method calls"
+  - [Read on martinfowler.com](https://martinfowler.com/eaaCatalog/dataTransferObject.html)
+
+**Purpose:**
+- Originally designed to batch remote calls and reduce network overhead
+- Modern use: Separate domain model from external representation
+- Prevents "God objects" that do too much
+
+**Warning: LocalDTO Anti-pattern:**
+Martin Fowler also warns about overusing DTOs in local contexts where they add unnecessary complexity.
+
+[Read full research →](./RESEARCH_CITATIONS.md#5-entity-exposure-dto-pattern)
+
+---
+
+## Repository Pattern
+
+### Why it matters
+
+Repository pattern provides:
+- ✅ **Abstraction** - Domain doesn't know about persistence details
+- ✅ **Testability** - Easy to mock data access in tests
+- ✅ **Centralized queries** - Single place for data access logic
+- ✅ **Clean separation** - Domain logic separate from data access
+
+### Common Violations
+
+Guardian detects:
+- ORM types leaking into repository interfaces
+- Technical method names (`findOne`, `save`) instead of domain language
+- Direct ORM/database usage in use cases
+- `new Repository()` instantiation (should use DI)
+
+### Who says so?
+
+**The Definitive Source:**
+- **Martin Fowler: Enterprise Application Architecture Catalog**
+  > "Mediates between the domain and data mapping layers using a collection-like interface for accessing domain objects"
+  - Part of the Domain Logic Patterns
+  - [Read on martinfowler.com](https://martinfowler.com/eaaCatalog/repository.html)
+
+**Key Benefits:**
+- Minimizes duplicate query logic
+- Allows multiple repositories for different storage needs
+- Domain layer doesn't know about SQL, MongoDB, or any specific technology
+
+**Additional Support:**
+- **Microsoft Learn**: Official documentation on Repository Pattern
+- **Eric Evans**: Referenced in Domain-Driven Design book
+- **Listed as**: Data Source Architectural Pattern
+
+**Real-world Example:**
+```typescript
+// ❌ Bad: ORM leak in interface
+interface IUserRepository {
+    findOne(query: PrismaWhereInput): Promise<User>
+}
+
+// ✅ Good: Domain language
+interface IUserRepository {
+    findByEmail(email: Email): Promise<User | null>
+    findById(id: UserId): Promise<User | null>
+}
+```
+
+[Read full research →](./RESEARCH_CITATIONS.md#6-repository-pattern)
+
+---
+
+## Naming Conventions
+
+### Why it matters
+
+Consistent naming:
+- ✅ **Readability** - Code is self-documenting
+- ✅ **Predictability** - Developers know what to expect
+- ✅ **Maintainability** - Easier to navigate large codebases
+- ✅ **Team alignment** - Everyone follows same patterns
+
+### Guardian's Conventions
+
+**Domain Layer:**
+- Entities: `User.ts`, `Order.ts` (PascalCase nouns)
+- Services: `UserService.ts` (PascalCase + Service suffix)
+- Repositories: `IUserRepository.ts` (I prefix for interfaces)
+
+**Application Layer:**
+- Use cases: `CreateUser.ts`, `PlaceOrder.ts` (Verb + Noun)
+- DTOs: `UserDto.ts`, `CreateUserRequest.ts` (Dto/Request/Response suffix)
+- Mappers: `UserMapper.ts` (Mapper suffix)
+
+**Infrastructure Layer:**
+- Controllers: `UserController.ts` (Controller suffix)
+- Repositories: `MongoUserRepository.ts` (implementation name + Repository)
+
+### Who says so?
+
+**Industry Style Guides:**
+
+- **Google Java Style Guide**
+  - PascalCase for classes
+  - camelCase for methods and variables
+  - [Read the guide](https://google.github.io/styleguide/javaguide.html)
+
+- **Airbnb JavaScript Style Guide**
+  - 145,000+ GitHub stars
+  - Industry standard for JavaScript/TypeScript
+  - [Read the guide](https://github.com/airbnb/javascript)
+
+- **Microsoft .NET Guidelines**
+  - PascalCase for types and public members
+  - Consistent across entire .NET ecosystem
+  - Widely adopted in C# and TypeScript communities
+
+**Use Case Naming:**
+- **TM Forum Standard**: Verb + Noun pattern for operations
+  - Actions start with verbs: Create, Update, Delete, Get, Process
+  - Clear intent from filename
+  - Examples: `ProcessOrder.ts`, `ValidateInput.ts`
+
+**General Principle:**
+- **Wikipedia: Naming Convention (Programming)**
+  - "Classes are nouns, methods are verbs"
+  - Widely accepted across languages and paradigms
+
+[Read full research →](./RESEARCH_CITATIONS.md#7-naming-conventions)
+
+---
+
+## Anemic Domain Model Detection
+
+### Why it matters
+
+Anemic domain models violate core OOP principles:
+- ❌ **No behavior** - Entities become data bags with only getters/setters
+- ❌ **Logic in services** - Business logic scattered across service layers
+- ❌ **Violates OOP** - Separates data from behavior
+- ❌ **Higher complexity** - Loses benefits of domain modeling
+
+### Who says so?
+
+**Martin Fowler's Original Anti-Pattern:**
+- **Blog Post: "Anemic Domain Model"** (November 25, 2003)
+  > "The basic symptom of an Anemic Domain Model is that at first blush it looks like the real thing. There are objects, many named after the nouns in the domain space... The catch comes when you look at the behavior, and you realize that there is hardly any behavior on these objects."
+  - Published over 20 years ago, still relevant today
+  - [Read Fowler's post](https://martinfowler.com/bliki/AnemicDomainModel.html)
+
+**Why It's an Anti-pattern:**
+> "This is contrary to the basic idea of object-oriented design; which is to combine data and process together."
+- Incurs all costs of domain model without any benefits
+- Logic should be in domain objects: validations, calculations, business rules
+- [Wikipedia - Anemic Domain Model](https://en.wikipedia.org/wiki/Anemic_domain_model)
+
+**Rich Domain Model vs Transaction Script:**
+- **Transaction Script**: Good for simple logic (Fowler, 2002)
+- **Rich Domain Model**: Better for complex, ever-changing business rules
+- Can refactor from Transaction Script to Domain Model, but it's harder than starting right
+- [Martin Fowler - Transaction Script](https://martinfowler.com/eaaCatalog/transactionScript.html)
+
+**Domain-Driven Design Context:**
+- **Eric Evans (2003)**: Entities should have both identity AND behavior
+- Anemic models violate DDD by separating data from behavior
+- [Stack Overflow discussion](https://stackoverflow.com/questions/6293981/concrete-examples-on-why-the-anemic-domain-model-is-considered-an-anti-pattern)
+
+[Read full research →](./RESEARCH_CITATIONS.md#11-anemic-domain-model-detection)
+
+---
+
+## Aggregate Boundary Validation
+
+### Why it matters
+
+Proper aggregate boundaries ensure:
+- ✅ **Consistency** - Atomic changes within boundaries
+- ✅ **Low coupling** - Aggregates are loosely connected
+- ✅ **Clear transactions** - One aggregate = one transaction
+- ✅ **Maintainability** - Boundaries prevent complexity spread
+
+### The Rules
+
+**Vaughn Vernon's Four Rules (2013):**
+1. **Model True Invariants in Consistency Boundaries**
+2. **Design Small Aggregates**
+3. **Reference Other Aggregates by Identity**
+4. **Use Eventual Consistency Outside the Boundary**
+
+### Who says so?
+
+**Eric Evans: Domain-Driven Design (2003)**
+- **Original Definition**:
+  > "A cluster of associated objects that we treat as a unit for the purpose of data changes"
+- An aggregate defines a consistency boundary
+- Exactly one entity is the aggregate root
+- [Microsoft Learn - Tactical DDD](https://learn.microsoft.com/en-us/azure/architecture/microservices/model/tactical-ddd)
+
+**Vaughn Vernon: Implementing Domain-Driven Design (2013)**
+- **Chapter 10: Aggregates** (Page 347)
+- ISBN: 978-0321834577
+- Comprehensive rules for aggregate design
+- Three-part essay series: "Effective Aggregate Design"
+- [Available at Kalele](https://kalele.io/effective-aggregate-design/)
+
+**Why Boundaries Matter:**
+- **Transactional Boundary**: Changes must be atomic
+- **Reference by ID**: No direct entity references across aggregates
+- **Prevents tight coupling**: Maintains clear boundaries
+- [Medium - Mastering Aggregate Design](https://medium.com/ssense-tech/ddd-beyond-the-basics-mastering-aggregate-design-26591e218c8c)
+
+**Microsoft Azure Documentation:**
+- Official guide for microservices architecture
+- Comprehensive aggregate boundary patterns
+- [Microsoft Learn - Tactical DDD](https://learn.microsoft.com/en-us/azure/architecture/microservices/model/tactical-ddd)
+
+[Read full research →](./RESEARCH_CITATIONS.md#12-aggregate-boundary-validation-ddd-tactical-patterns)
+
+---
+
+## Secret Detection
+
+### Why it matters
+
+Hardcoded secrets create critical security risks:
+- 🔴 **Data breaches** - Exposed credentials lead to unauthorized access
+- 🔴 **Production incidents** - Leaked tokens cause service disruptions
+- 🔴 **Compliance violations** - GDPR, PCI-DSS, SOC 2 requirements
+- 🔴 **Impossible to rotate** - Secrets in code are difficult to change
+
+### Who says so?
+
+**OWASP Security Standards:**
+- **OWASP Secrets Management Cheat Sheet**
+  > "Secrets should not be hardcoded, should not be unencrypted, and should not be stored in source code."
+  - Official best practices from OWASP Foundation
+  - [Read the cheat sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html)
+
+- **OWASP Hardcoded Password Vulnerability**
+  > "It is never a good idea to hardcode a password, as it allows all of the project's developers to view the password and makes fixing the problem extremely difficult."
+  - [OWASP Documentation](https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password)
+
+**GitHub Secret Scanning:**
+- **Official GitHub Documentation**
+  - Automatically scans 350+ secret patterns
+  - Detects AWS, GitHub, NPM, SSH, GCP, Slack tokens
+  - AI-powered detection with Copilot Secret Scanning
+  - [GitHub Docs](https://docs.github.com/code-security/secret-scanning/about-secret-scanning)
+
+**Key Security Principles:**
+- **Centralized Management**: Use purpose-built secret management tools
+- **Prevention Tools**: Pre-commit hooks to prevent secrets entering codebase
+- **Encryption at Rest**: Never store secrets in plaintext
+- [OWASP SAMM - Secret Management](https://owaspsamm.org/model/implementation/secure-deployment/stream-b/)
+
+**Mobile Security:**
+- OWASP: "Secrets security is the most important issue for mobile applications"
+- Only safe way: keep secrets off the client side entirely
+- [GitGuardian - OWASP Top 10 Mobile](https://blog.gitguardian.com/owasp-top-10-for-mobile-secrets/)
+
+[Read full research →](./RESEARCH_CITATIONS.md#13-secret-detection--security)
+
+---
+
+## Severity-Based Prioritization
+
+### Why it matters
+
+Severity classification enables:
+- ✅ **Focus on critical issues** - Fix what matters most first
+- ✅ **Reduced technical debt** - Prioritize based on impact
+- ✅ **Better CI/CD integration** - Fail builds on critical issues only
+- ✅ **Team efficiency** - Don't waste time on low-impact issues
+
+### Who says so?
+
+**Academic Research:**
+- **Systematic Literature Review (2020)**
+  - Title: "A systematic literature review on Technical Debt prioritization"
+  - Analyzed 557 papers, included 44 primary studies
+  - Finding: Need for consensus on severity factors
+  - [ScienceDirect](https://www.sciencedirect.com/science/article/pii/S016412122030220X)
+
+- **IEEE Conference Paper (2021)**
+  - "Technical Debt Prioritization: Taxonomy, Methods Results"
+  - Reviewed 112 studies
+  - Classified methods in 10 categories
+  - [IEEE Xplore](https://ieeexplore.ieee.org/document/9582595/)
+
+- **Software Quality Journal (2023)**
+  - "Identifying the severity of technical debt issues"
+  - Problem: Most studies ignore severity degree
+  - Proposed semantic + structural approach
+  - [Springer](https://link.springer.com/article/10.1007/s11219-023-09651-3)
+
+**SonarQube Industry Standard:**
+- **Current Classification (10.2+)**:
+  - **Blocker/High**: Severe unintended consequences, fix immediately
+  - **Medium**: Impacts developer productivity
+  - **Low**: Slight impact on productivity
+  - **Info**: No expected impact
+  - [SonarQube Docs](https://docs.sonarsource.com/sonarqube-server/user-guide/code-metrics/metrics-definition)
+
+**Real-World Impact:**
+- Development teams integrate models into CI/CD pipelines
+- Automatically flag potential TD issues during code reviews
+- Prioritize based on severity
+- [arXiv - Technical Debt Management](https://arxiv.org/html/2403.06484v1)
+
+**Business Alignment:**
+- "Aligning Technical Debt Prioritization with Business Objectives" (2018)
+- Multiple-case study demonstrating importance
+- [ResearchGate](https://www.researchgate.net/publication/328903587_Aligning_Technical_Debt_Prioritization_with_Business_Objectives_A_Multiple-Case_Study)
+
+[Read full research →](./RESEARCH_CITATIONS.md#14-severity-based-prioritization--technical-debt)
+
+---
+
+## Full Research Citations
+
+For complete academic papers, books, and authoritative sources, see:
+
+📚 **[RESEARCH_CITATIONS.md](./RESEARCH_CITATIONS.md)**
+
+This document contains:
+- 50+ authoritative references
+- Academic papers with DOI/URLs
+- Book citations with authors and publication years
+- Industry standards from Google, Microsoft, AWS
+- Expert blogs from Martin Fowler, Uncle Bob, Kent Beck
+- Historical context dating back to 1960s
+
+---
+
+## Quality Standards
+
+Guardian's rules align with international standards:
+
+**ISO/IEC 25010:2011 (Software Quality Standard)**
+- Eight quality characteristics including **Maintainability**
+- Sub-characteristics: Modularity, Reusability, Analysability, Modifiability, Testability
+- [Learn more](https://www.iso.org/standard/35733.html)
+
+**SQuaRE Framework:**
+- System and Software Quality Requirements and Evaluation
+- Used throughout software development lifecycle
+
+---
+
+## Summary: Why Trust Guardian?
+
+Guardian's rules are backed by:
+
+✅ **6 Seminal Books** (1993-2017)
+- Clean Architecture (Robert C. Martin, 2017)
+- Implementing Domain-Driven Design (Vaughn Vernon, 2013)
+- Domain-Driven Design (Eric Evans, 2003)
+- Patterns of Enterprise Application Architecture (Martin Fowler, 2002)
+- Refactoring (Martin Fowler, 1999)
+- Code Complete (Steve McConnell, 1993)
+
+✅ **Academic Research** (1976-2024)
+- MIT Course 6.031
+- ScienceDirect peer-reviewed studies (2020-2023)
+- IEEE Conference papers on Technical Debt
+- Software Quality Journal (2023)
+- Cyclomatic Complexity (Thomas McCabe, 1976)
+
+✅ **Security Standards**
+- OWASP Secrets Management Cheat Sheet
+- GitHub Secret Scanning (350+ patterns)
+- OWASP Top 10 for Mobile
+
+✅ **International Standards**
+- ISO/IEC 25010:2011
+
+✅ **Industry Giants**
+- Google, Microsoft, Airbnb style guides
+- SonarQube (400,000+ organizations)
+- AWS documentation
+- GitHub security practices
+
+✅ **Thought Leaders**
+- Martin Fowler, Robert C. Martin (Uncle Bob), Eric Evans
+- Vaughn Vernon, Alistair Cockburn, Kent Beck, Thomas McCabe
+
+---
+
+**Questions or want to contribute research?**
+
+- 📧 Email: fozilbek.samiyev@gmail.com
+- 🐙 GitHub: https://github.com/samiyev/puaros/issues
+- 📚 Full citations: [RESEARCH_CITATIONS.md](./RESEARCH_CITATIONS.md)
+
+---
+
+*Last updated: 2025-11-26*
--- a/packages/guardian/docs/v0.6.0-CONFIGURATION-SPEC.md
+++ b/packages/guardian/docs/v0.6.0-CONFIGURATION-SPEC.md
--- a/packages/guardian/examples/aggregate-boundary/bad/Order-DirectEntityReference.ts
+++ b/packages/guardian/examples/aggregate-boundary/bad/Order-DirectEntityReference.ts
@@ -0,0 +1,40 @@
+/**
+ * ❌ BAD EXAMPLE: Direct Entity Reference Across Aggregates
+ *
+ * Violation: Order aggregate directly imports and uses User entity from User aggregate
+ *
+ * Problems:
+ * 1. Creates tight coupling between aggregates
+ * 2. Changes to User entity affect Order aggregate
+ * 3. Violates aggregate boundary principles in DDD
+ * 4. Makes aggregates not independently modifiable
+ */
+
+import { User } from "../user/User"
+import { Product } from "../product/Product"
+
+export class Order {
+    private id: string
+    private user: User
+    private product: Product
+    private quantity: number
+
+    constructor(id: string, user: User, product: Product, quantity: number) {
+        this.id = id
+        this.user = user
+        this.product = product
+        this.quantity = quantity
+    }
+
+    getUserEmail(): string {
+        return this.user.email
+    }
+
+    getProductPrice(): number {
+        return this.product.price
+    }
+
+    calculateTotal(): number {
+        return this.product.price * this.quantity
+    }
+}
--- a/packages/guardian/examples/aggregate-boundary/domain/aggregates/order/Order.ts
+++ b/packages/guardian/examples/aggregate-boundary/domain/aggregates/order/Order.ts
@@ -0,0 +1,16 @@
+import { User } from "../user/User"
+import { Product } from "../product/Product"
+
+export class Order {
+    private id: string
+    private user: User
+    private product: Product
+    private quantity: number
+
+    constructor(id: string, user: User, product: Product, quantity: number) {
+        this.id = id
+        this.user = user
+        this.product = product
+        this.quantity = quantity
+    }
+}
--- a/packages/guardian/examples/aggregate-boundary/domain/aggregates/product/Product.ts
+++ b/packages/guardian/examples/aggregate-boundary/domain/aggregates/product/Product.ts
@@ -0,0 +1,7 @@
+export class Product {
+    public price: number
+
+    constructor(price: number) {
+        this.price = price
+    }
+}
--- a/packages/guardian/examples/aggregate-boundary/domain/aggregates/user/User.ts
+++ b/packages/guardian/examples/aggregate-boundary/domain/aggregates/user/User.ts
@@ -0,0 +1,7 @@
+export class User {
+    public email: string
+
+    constructor(email: string) {
+        this.email = email
+    }
+}
--- a/packages/guardian/examples/aggregate-boundary/good/Order-IdReference.ts
+++ b/packages/guardian/examples/aggregate-boundary/good/Order-IdReference.ts
@@ -0,0 +1,40 @@
+/**
+ * ✅ GOOD EXAMPLE: Reference by ID
+ *
+ * Best Practice: Order aggregate references other aggregates only by their IDs
+ *
+ * Benefits:
+ * 1. Loose coupling between aggregates
+ * 2. Each aggregate can be modified independently
+ * 3. Follows DDD aggregate boundary principles
+ * 4. Clear separation of concerns
+ */
+
+import { UserId } from "../user/value-objects/UserId"
+import { ProductId } from "../product/value-objects/ProductId"
+
+export class Order {
+    private id: string
+    private userId: UserId
+    private productId: ProductId
+    private quantity: number
+
+    constructor(id: string, userId: UserId, productId: ProductId, quantity: number) {
+        this.id = id
+        this.userId = userId
+        this.productId = productId
+        this.quantity = quantity
+    }
+
+    getUserId(): UserId {
+        return this.userId
+    }
+
+    getProductId(): ProductId {
+        return this.productId
+    }
+
+    getQuantity(): number {
+        return this.quantity
+    }
+}
--- a/packages/guardian/examples/aggregate-boundary/good/Order-ValueObject.ts
+++ b/packages/guardian/examples/aggregate-boundary/good/Order-ValueObject.ts
@@ -0,0 +1,61 @@
+/**
+ * ✅ GOOD EXAMPLE: Using Value Objects for Needed Data
+ *
+ * Best Practice: When Order needs specific data from other aggregates,
+ * use Value Objects to store that data (denormalization)
+ *
+ * Benefits:
+ * 1. Order aggregate has all data it needs
+ * 2. No runtime dependency on other aggregates
+ * 3. Better performance (no joins needed)
+ * 4. Clear contract through Value Objects
+ */
+
+import { UserId } from "../user/value-objects/UserId"
+import { ProductId } from "../product/value-objects/ProductId"
+
+export class CustomerInfo {
+    constructor(
+        readonly customerId: UserId,
+        readonly customerName: string,
+        readonly customerEmail: string,
+    ) {}
+}
+
+export class ProductInfo {
+    constructor(
+        readonly productId: ProductId,
+        readonly productName: string,
+        readonly productPrice: number,
+    ) {}
+}
+
+export class Order {
+    private id: string
+    private customer: CustomerInfo
+    private product: ProductInfo
+    private quantity: number
+
+    constructor(id: string, customer: CustomerInfo, product: ProductInfo, quantity: number) {
+        this.id = id
+        this.customer = customer
+        this.product = product
+        this.quantity = quantity
+    }
+
+    getCustomerEmail(): string {
+        return this.customer.customerEmail
+    }
+
+    calculateTotal(): number {
+        return this.product.productPrice * this.quantity
+    }
+
+    getCustomerInfo(): CustomerInfo {
+        return this.customer
+    }
+
+    getProductInfo(): ProductInfo {
+        return this.product
+    }
+}
--- a/packages/guardian/examples/bad-architecture/dependency-direction/BadApplicationLayer.ts
+++ b/packages/guardian/examples/bad-architecture/dependency-direction/BadApplicationLayer.ts
@@ -0,0 +1,117 @@
+/**
+ * ❌ BAD: Application layer with incorrect dependencies
+ *
+ * Application importing from Infrastructure layer
+ * This violates Clean Architecture dependency rules!
+ */
+
+import { User } from "../../good-architecture/domain/entities/User"
+import { Email } from "../../good-architecture/domain/value-objects/Email"
+import { UserId } from "../../good-architecture/domain/value-objects/UserId"
+
+/**
+ * ❌ VIOLATION: Application importing from Infrastructure layer
+ */
+import { PrismaClient } from "@prisma/client"
+
+export class CreateUser {
+    /**
+     * ❌ VIOLATION: Application use case depending on concrete infrastructure (Prisma)
+     */
+    constructor(private prisma: PrismaClient) {}
+
+    async execute(email: string): Promise<User> {
+        const userId = UserId.generate()
+        const emailVO = Email.create(email).value
+
+        /**
+         * ❌ VIOLATION: Application logic directly accessing database
+         */
+        await this.prisma.user.create({
+            data: {
+                id: userId.getValue(),
+                email: emailVO.getValue(),
+            },
+        })
+
+        return new User(userId, emailVO)
+    }
+}
+
+/**
+ * ❌ VIOLATION: Application importing concrete email service from infrastructure
+ */
+import { SmtpEmailService } from "../../good-architecture/infrastructure/adapters/SmtpEmailService"
+
+export class SendWelcomeEmail {
+    /**
+     * ❌ VIOLATION: Application depending on concrete infrastructure implementation
+     * Should depend on IEmailService interface instead
+     */
+    constructor(
+        private prisma: PrismaClient,
+        private emailService: SmtpEmailService,
+    ) {}
+
+    async execute(userId: string): Promise<void> {
+        const user = await this.prisma.user.findUnique({
+            where: { id: userId },
+        })
+
+        if (!user) {
+            throw new Error("User not found")
+        }
+
+        await this.emailService.sendWelcomeEmail(user.email)
+    }
+}
+
+/**
+ * ❌ VIOLATION: Application importing from infrastructure controller
+ */
+import { UserController } from "../../good-architecture/infrastructure/controllers/UserController"
+
+export class ValidateUser {
+    /**
+     * ❌ VIOLATION: Application use case depending on infrastructure controller
+     * The dependency direction is completely wrong!
+     */
+    constructor(private userController: UserController) {}
+
+    async execute(userId: string): Promise<boolean> {
+        return true
+    }
+}
+
+/**
+ * ❌ VIOLATION: Application importing HTTP framework
+ */
+import express from "express"
+
+export class ProcessUserRequest {
+    /**
+     * ❌ VIOLATION: Application layer knows about HTTP/Express
+     * HTTP concerns should be in infrastructure layer
+     */
+    async execute(req: express.Request): Promise<void> {
+        const email = req.body.email
+        console.log(`Processing user: ${email}`)
+    }
+}
+
+/**
+ * ❌ VIOLATION: Application importing infrastructure repository implementation
+ */
+import { InMemoryUserRepository } from "../../good-architecture/infrastructure/repositories/InMemoryUserRepository"
+
+export class GetUser {
+    /**
+     * ❌ VIOLATION: Application depending on concrete repository implementation
+     * Should depend on IUserRepository interface from domain
+     */
+    constructor(private userRepo: InMemoryUserRepository) {}
+
+    async execute(userId: string): Promise<User | null> {
+        return await this.userRepo.findById(UserId.from(userId))
+    }
+}
--- a/packages/guardian/examples/bad-architecture/dependency-direction/BadDomainLayer.ts
+++ b/packages/guardian/examples/bad-architecture/dependency-direction/BadDomainLayer.ts
@@ -0,0 +1,90 @@
+/**
+ * ❌ BAD: Domain layer with incorrect dependencies
+ *
+ * Domain importing from Application and Infrastructure layers
+ * This violates Clean Architecture dependency rules!
+ */
+
+import { Email } from "../../good-architecture/domain/value-objects/Email"
+import { UserId } from "../../good-architecture/domain/value-objects/UserId"
+
+/**
+ * ❌ VIOLATION: Domain importing from Application layer
+ */
+import { UserResponseDto } from "../../good-architecture/application/dtos/UserResponseDto"
+
+export class User {
+    private readonly id: UserId
+    private email: Email
+
+    constructor(id: UserId, email: Email) {
+        this.id = id
+        this.email = email
+    }
+
+    /**
+     * ❌ VIOLATION: Domain entity returning DTO from application layer
+     */
+    toDto(): UserResponseDto {
+        return {
+            id: this.id.getValue(),
+            email: this.email.getValue(),
+            createdAt: new Date().toISOString(),
+        }
+    }
+}
+
+/**
+ * ❌ VIOLATION: Domain importing from Infrastructure layer
+ */
+import { PrismaClient } from "@prisma/client"
+
+export class UserService {
+    /**
+     * ❌ VIOLATION: Domain service depending on concrete infrastructure implementation
+     */
+    constructor(private prisma: PrismaClient) {}
+
+    async createUser(email: string): Promise<User> {
+        const userId = UserId.generate()
+        const emailVO = Email.create(email).value
+
+        /**
+         * ❌ VIOLATION: Domain logic directly accessing database
+         */
+        await this.prisma.user.create({
+            data: {
+                id: userId.getValue(),
+                email: emailVO.getValue(),
+            },
+        })
+
+        return new User(userId, emailVO)
+    }
+}
+
+/**
+ * ❌ VIOLATION: Domain importing email service from infrastructure
+ */
+import { SmtpEmailService } from "../../good-architecture/infrastructure/adapters/SmtpEmailService"
+
+export class UserRegistration {
+    /**
+     * ❌ VIOLATION: Domain depending on infrastructure email service
+     */
+    constructor(
+        private userService: UserService,
+        private emailService: SmtpEmailService,
+    ) {}
+
+    async register(email: string): Promise<User> {
+        const user = await this.userService.createUser(email)
+
+        /**
+         * ❌ VIOLATION: Domain calling infrastructure service directly
+         */
+        await this.emailService.sendWelcomeEmail(email)
+
+        return user
+    }
+}
--- a/packages/guardian/examples/bad-architecture/entity-exposure/infrastructure/controllers/BadOrderController.ts
+++ b/packages/guardian/examples/bad-architecture/entity-exposure/infrastructure/controllers/BadOrderController.ts
@@ -0,0 +1,33 @@
+// ❌ BAD: Exposing domain entity Order in API response
+
+class Order {
+    constructor(
+        public id: string,
+        public items: OrderItem[],
+        public total: number,
+        public customerId: string,
+    ) {}
+}
+
+class OrderItem {
+    constructor(
+        public productId: string,
+        public quantity: number,
+        public price: number,
+    ) {}
+}
+
+class BadOrderController {
+    async getOrder(orderId: string): Promise<Order> {
+        return {
+            id: orderId,
+            items: [],
+            total: 100,
+            customerId: "customer-123",
+        }
+    }
+
+    async listOrders(): Promise<Order[]> {
+        return []
+    }
+}
--- a/packages/guardian/examples/bad-architecture/entity-exposure/infrastructure/controllers/BadUserController.ts
+++ b/packages/guardian/examples/bad-architecture/entity-exposure/infrastructure/controllers/BadUserController.ts
--- a/packages/guardian/examples/bad/domain/entities/anemic-model-only-getters-setters.ts
+++ b/packages/guardian/examples/bad/domain/entities/anemic-model-only-getters-setters.ts
@@ -0,0 +1,38 @@
+/**
+ * BAD EXAMPLE: Anemic Domain Model
+ *
+ * This Order class only has getters and setters without any business logic.
+ * All business logic is likely scattered in services (procedural approach).
+ *
+ * This violates Domain-Driven Design principles.
+ */
+
+class Order {
+    private status: string
+    private total: number
+    private items: any[]
+
+    getStatus(): string {
+        return this.status
+    }
+
+    setStatus(status: string): void {
+        this.status = status
+    }
+
+    getTotal(): number {
+        return this.total
+    }
+
+    setTotal(total: number): void {
+        this.total = total
+    }
+
+    getItems(): any[] {
+        return this.items
+    }
+
+    setItems(items: any[]): void {
+        this.items = items
+    }
+}
--- a/packages/guardian/examples/bad/domain/entities/anemic-model-public-setters.ts
+++ b/packages/guardian/examples/bad/domain/entities/anemic-model-public-setters.ts
@@ -0,0 +1,34 @@
+/**
+ * BAD EXAMPLE: Anemic Domain Model with Public Setters
+ *
+ * This User class has public setters which is an anti-pattern in DDD.
+ * Public setters allow uncontrolled state changes without validation or business rules.
+ *
+ * This violates Domain-Driven Design principles and encapsulation.
+ */
+
+class User {
+    private email: string
+    private password: string
+    private status: string
+
+    public setEmail(email: string): void {
+        this.email = email
+    }
+
+    public getEmail(): string {
+        return this.email
+    }
+
+    public setPassword(password: string): void {
+        this.password = password
+    }
+
+    public setStatus(status: string): void {
+        this.status = status
+    }
+
+    public getStatus(): string {
+        return this.status
+    }
+}
--- a/packages/guardian/examples/good-architecture/dependency-direction/GoodApplicationLayer.ts
+++ b/packages/guardian/examples/good-architecture/dependency-direction/GoodApplicationLayer.ts
@@ -0,0 +1,91 @@
+/**
+ * ✅ GOOD: Application layer with correct dependencies
+ *
+ * Application should only import from:
+ * - Domain layer
+ * - Other application files
+ * - Shared utilities
+ *
+ * Application should NOT import from:
+ * - Infrastructure layer
+ */
+
+import { User } from "../domain/entities/User"
+import { Email } from "../domain/value-objects/Email"
+import { UserId } from "../domain/value-objects/UserId"
+import { IUserRepository } from "../domain/repositories/IUserRepository"
+import { Result } from "../../../src/shared/types/Result"
+
+/**
+ * ✅ Use case depends on domain interfaces (IUserRepository)
+ * NOT on infrastructure implementations
+ */
+export class CreateUser {
+    constructor(private readonly userRepo: IUserRepository) {}
+
+    async execute(request: CreateUserRequest): Promise<Result<UserResponseDto>> {
+        const emailResult = Email.create(request.email)
+        if (emailResult.isFailure) {
+            return Result.fail(emailResult.error)
+        }
+
+        const userId = UserId.generate()
+        const user = new User(userId, emailResult.value)
+
+        await this.userRepo.save(user)
+
+        return Result.ok(UserMapper.toDto(user))
+    }
+}
+
+/**
+ * ✅ DTO in application layer
+ */
+export interface CreateUserRequest {
+    email: string
+    name: string
+}
+
+export interface UserResponseDto {
+    id: string
+    email: string
+    createdAt: string
+}
+
+/**
+ * ✅ Mapper in application layer converting domain to DTO
+ */
+export class UserMapper {
+    static toDto(user: User): UserResponseDto {
+        return {
+            id: user.getId().getValue(),
+            email: user.getEmail().getValue(),
+            createdAt: user.getCreatedAt().toISOString(),
+        }
+    }
+}
+
+/**
+ * ✅ Application defines Port (interface) for email service
+ * Infrastructure will provide the Adapter (implementation)
+ */
+export interface IEmailService {
+    sendWelcomeEmail(email: string): Promise<void>
+}
+
+export class SendWelcomeEmail {
+    constructor(
+        private readonly userRepo: IUserRepository,
+        private readonly emailService: IEmailService,
+    ) {}
+
+    async execute(userId: string): Promise<Result<void>> {
+        const user = await this.userRepo.findById(UserId.from(userId))
+        if (!user) {
+            return Result.fail("User not found")
+        }
+
+        await this.emailService.sendWelcomeEmail(user.getEmail().getValue())
+        return Result.ok()
+    }
+}
--- a/packages/guardian/examples/good-architecture/dependency-direction/GoodDomainLayer.ts
+++ b/packages/guardian/examples/good-architecture/dependency-direction/GoodDomainLayer.ts
@@ -0,0 +1,56 @@
+/**
+ * ✅ GOOD: Domain layer with correct dependencies
+ *
+ * Domain should only import from:
+ * - Other domain files
+ * - Shared utilities
+ *
+ * Domain should NOT import from:
+ * - Application layer
+ * - Infrastructure layer
+ */
+
+import { Email } from "../domain/value-objects/Email"
+import { UserId } from "../domain/value-objects/UserId"
+import { Result } from "../../../src/shared/types/Result"
+
+/**
+ * ✅ Domain entity using only domain value objects and shared types
+ */
+export class User {
+    private readonly id: UserId
+    private email: Email
+    private readonly createdAt: Date
+
+    constructor(id: UserId, email: Email, createdAt: Date = new Date()) {
+        this.id = id
+        this.email = email
+        this.createdAt = createdAt
+    }
+
+    public getId(): UserId {
+        return this.id
+    }
+
+    public getEmail(): Email {
+        return this.email
+    }
+
+    public changeEmail(newEmail: Email): Result<void> {
+        if (this.email.equals(newEmail)) {
+            return Result.fail("Email is the same")
+        }
+
+        this.email = newEmail
+        return Result.ok()
+    }
+}
+
+/**
+ * ✅ Domain repository interface (not importing from infrastructure)
+ */
+export interface IUserRepository {
+    findById(id: UserId): Promise<User | null>
+    save(user: User): Promise<void>
+    delete(id: UserId): Promise<void>
+}
--- a/packages/guardian/examples/good-architecture/dependency-direction/GoodInfrastructureLayer.ts
+++ b/packages/guardian/examples/good-architecture/dependency-direction/GoodInfrastructureLayer.ts
@@ -0,0 +1,128 @@
+/**
+ * ✅ GOOD: Infrastructure layer with correct dependencies
+ *
+ * Infrastructure CAN import from:
+ * - Domain layer
+ * - Application layer
+ * - Other infrastructure files
+ * - Shared utilities
+ * - External libraries (ORM, frameworks, etc.)
+ */
+
+import { User } from "../domain/entities/User"
+import { UserId } from "../domain/value-objects/UserId"
+import { Email } from "../domain/value-objects/Email"
+import { IUserRepository } from "../domain/repositories/IUserRepository"
+import { CreateUser } from "../application/use-cases/CreateUser"
+import { UserResponseDto } from "../application/dtos/UserResponseDto"
+import { IEmailService } from "../application/ports/IEmailService"
+
+/**
+ * ✅ Infrastructure implements domain interface
+ */
+export class InMemoryUserRepository implements IUserRepository {
+    private users: Map<string, User> = new Map()
+
+    async findById(id: UserId): Promise<User | null> {
+        return this.users.get(id.getValue()) ?? null
+    }
+
+    async save(user: User): Promise<void> {
+        this.users.set(user.getId().getValue(), user)
+    }
+
+    async delete(id: UserId): Promise<void> {
+        this.users.delete(id.getValue())
+    }
+}
+
+/**
+ * ✅ Infrastructure provides Adapter implementing application Port
+ */
+export class SmtpEmailService implements IEmailService {
+    constructor(
+        private readonly host: string,
+        private readonly port: number,
+    ) {}
+
+    async sendWelcomeEmail(email: string): Promise<void> {
+        console.log(`Sending welcome email to ${email} via SMTP`)
+    }
+}
+
+/**
+ * ✅ Controller uses application use cases and DTOs
+ */
+export class UserController {
+    constructor(private readonly createUser: CreateUser) {}
+
+    async create(request: { email: string; name: string }): Promise<UserResponseDto> {
+        const result = await this.createUser.execute(request)
+
+        if (result.isFailure) {
+            throw new Error(result.error)
+        }
+
+        return result.value
+    }
+}
+
+/**
+ * ✅ Infrastructure can use external frameworks
+ */
+import express from "express"
+
+export class ExpressServer {
+    private app = express()
+
+    constructor(private readonly userController: UserController) {
+        this.setupRoutes()
+    }
+
+    private setupRoutes(): void {
+        this.app.post("/users", async (req, res) => {
+            const user = await this.userController.create(req.body)
+            res.json(user)
+        })
+    }
+}
+
+/**
+ * ✅ Infrastructure can use ORM
+ */
+import { PrismaClient } from "@prisma/client"
+
+export class PrismaUserRepository implements IUserRepository {
+    constructor(private readonly prisma: PrismaClient) {}
+
+    async findById(id: UserId): Promise<User | null> {
+        const userData = await this.prisma.user.findUnique({
+            where: { id: id.getValue() },
+        })
+
+        if (!userData) {
+            return null
+        }
+
+        return new User(UserId.from(userData.id), Email.create(userData.email).value)
+    }
+
+    async save(user: User): Promise<void> {
+        await this.prisma.user.upsert({
+            where: { id: user.getId().getValue() },
+            create: {
+                id: user.getId().getValue(),
+                email: user.getEmail().getValue(),
+            },
+            update: {
+                email: user.getEmail().getValue(),
+            },
+        })
+    }
+
+    async delete(id: UserId): Promise<void> {
+        await this.prisma.user.delete({
+            where: { id: id.getValue() },
+        })
+    }
+}
--- a/packages/guardian/examples/good-architecture/domain/entities/Customer.ts
+++ b/packages/guardian/examples/good-architecture/domain/entities/Customer.ts
@@ -0,0 +1,139 @@
+/**
+ * GOOD EXAMPLE: Rich Domain Model with Business Logic
+ *
+ * This Customer class encapsulates business rules and state transitions.
+ * No public setters - all changes go through business methods.
+ *
+ * This follows Domain-Driven Design and encapsulation principles.
+ */
+
+interface Address {
+    street: string
+    city: string
+    country: string
+    postalCode: string
+}
+
+interface DomainEvent {
+    type: string
+    data: any
+}
+
+class Customer {
+    private readonly id: string
+    private email: string
+    private isActive: boolean
+    private loyaltyPoints: number
+    private address: Address | null
+    private readonly events: DomainEvent[] = []
+
+    constructor(id: string, email: string) {
+        this.id = id
+        this.email = email
+        this.isActive = true
+        this.loyaltyPoints = 0
+        this.address = null
+    }
+
+    public activate(): void {
+        if (this.isActive) {
+            throw new Error("Customer is already active")
+        }
+        this.isActive = true
+        this.events.push({
+            type: "CustomerActivated",
+            data: { customerId: this.id },
+        })
+    }
+
+    public deactivate(reason: string): void {
+        if (!this.isActive) {
+            throw new Error("Customer is already inactive")
+        }
+        this.isActive = false
+        this.events.push({
+            type: "CustomerDeactivated",
+            data: { customerId: this.id, reason },
+        })
+    }
+
+    public changeEmail(newEmail: string): void {
+        if (!this.isValidEmail(newEmail)) {
+            throw new Error("Invalid email format")
+        }
+        if (this.email === newEmail) {
+            return
+        }
+        const oldEmail = this.email
+        this.email = newEmail
+        this.events.push({
+            type: "EmailChanged",
+            data: { customerId: this.id, oldEmail, newEmail },
+        })
+    }
+
+    public updateAddress(address: Address): void {
+        if (!this.isValidAddress(address)) {
+            throw new Error("Invalid address")
+        }
+        this.address = address
+        this.events.push({
+            type: "AddressUpdated",
+            data: { customerId: this.id },
+        })
+    }
+
+    public addLoyaltyPoints(points: number): void {
+        if (points <= 0) {
+            throw new Error("Points must be positive")
+        }
+        if (!this.isActive) {
+            throw new Error("Cannot add points to inactive customer")
+        }
+        this.loyaltyPoints += points
+        this.events.push({
+            type: "LoyaltyPointsAdded",
+            data: { customerId: this.id, points },
+        })
+    }
+
+    public redeemLoyaltyPoints(points: number): void {
+        if (points <= 0) {
+            throw new Error("Points must be positive")
+        }
+        if (this.loyaltyPoints < points) {
+            throw new Error("Insufficient loyalty points")
+        }
+        this.loyaltyPoints -= points
+        this.events.push({
+            type: "LoyaltyPointsRedeemed",
+            data: { customerId: this.id, points },
+        })
+    }
+
+    public getEmail(): string {
+        return this.email
+    }
+
+    public getLoyaltyPoints(): number {
+        return this.loyaltyPoints
+    }
+
+    public getAddress(): Address | null {
+        return this.address ? { ...this.address } : null
+    }
+
+    public getEvents(): DomainEvent[] {
+        return [...this.events]
+    }
+
+    private isValidEmail(email: string): boolean {
+        return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
+    }
+
+    private isValidAddress(address: Address): boolean {
+        return !!address.street && !!address.city && !!address.country && !!address.postalCode
+    }
+}
+
+export { Customer }
--- a/packages/guardian/examples/good-architecture/domain/entities/Order.ts
+++ b/packages/guardian/examples/good-architecture/domain/entities/Order.ts
@@ -0,0 +1,104 @@
+/**
+ * GOOD EXAMPLE: Rich Domain Model
+ *
+ * This Order class contains business logic and enforces business rules.
+ * State changes are made through business methods, not setters.
+ *
+ * This follows Domain-Driven Design principles.
+ */
+
+type OrderStatus = "pending" | "approved" | "rejected" | "shipped"
+
+interface OrderItem {
+    productId: string
+    quantity: number
+    price: number
+}
+
+interface DomainEvent {
+    type: string
+    data: any
+}
+
+class Order {
+    private readonly id: string
+    private status: OrderStatus
+    private items: OrderItem[]
+    private readonly events: DomainEvent[] = []
+
+    constructor(id: string, items: OrderItem[]) {
+        this.id = id
+        this.status = "pending"
+        this.items = items
+    }
+
+    public approve(): void {
+        if (!this.canBeApproved()) {
+            throw new Error("Cannot approve order in current state")
+        }
+        this.status = "approved"
+        this.events.push({
+            type: "OrderApproved",
+            data: { orderId: this.id },
+        })
+    }
+
+    public reject(reason: string): void {
+        if (!this.canBeRejected()) {
+            throw new Error("Cannot reject order in current state")
+        }
+        this.status = "rejected"
+        this.events.push({
+            type: "OrderRejected",
+            data: { orderId: this.id, reason },
+        })
+    }
+
+    public ship(): void {
+        if (!this.canBeShipped()) {
+            throw new Error("Order must be approved before shipping")
+        }
+        this.status = "shipped"
+        this.events.push({
+            type: "OrderShipped",
+            data: { orderId: this.id },
+        })
+    }
+
+    public addItem(item: OrderItem): void {
+        if (this.status !== "pending") {
+            throw new Error("Cannot modify approved or shipped order")
+        }
+        this.items.push(item)
+    }
+
+    public calculateTotal(): number {
+        return this.items.reduce((sum, item) => sum + item.price * item.quantity, 0)
+    }
+
+    public getStatus(): OrderStatus {
+        return this.status
+    }
+
+    public getItems(): OrderItem[] {
+        return [...this.items]
+    }
+
+    public getEvents(): DomainEvent[] {
+        return [...this.events]
+    }
+
+    private canBeApproved(): boolean {
+        return this.status === "pending" && this.items.length > 0
+    }
+
+    private canBeRejected(): boolean {
+        return this.status === "pending"
+    }
+
+    private canBeShipped(): boolean {
+        return this.status === "approved"
+    }
+}
+
+export { Order }
--- a/packages/guardian/examples/good-architecture/entity-exposure/GoodUserController.ts
+++ b/packages/guardian/examples/good-architecture/entity-exposure/GoodUserController.ts
@@ -0,0 +1,42 @@
+// ✅ GOOD: Using DTOs and Mappers instead of exposing domain entities
+
+class User {
+    constructor(
+        private readonly id: string,
+        private email: string,
+        private password: string,
+    ) {}
+
+    getId(): string {
+        return this.id
+    }
+
+    getEmail(): string {
+        return this.email
+    }
+}
+
+class UserResponseDto {
+    constructor(
+        public readonly id: string,
+        public readonly email: string,
+    ) {}
+}
+
+class UserMapper {
+    static toDto(user: User): UserResponseDto {
+        return new UserResponseDto(user.getId(), user.getEmail())
+    }
+}
+
+class GoodUserController {
+    async getUser(userId: string): Promise<UserResponseDto> {
+        const user = new User(userId, "user@example.com", "hashed-password")
+        return UserMapper.toDto(user)
+    }
+
+    async listUsers(): Promise<UserResponseDto[]> {
+        const users = [new User("1", "user1@example.com", "password")]
+        return users.map((user) => UserMapper.toDto(user))
+    }
+}
--- a/packages/guardian/examples/repository-pattern/README.md
+++ b/packages/guardian/examples/repository-pattern/README.md
@@ -0,0 +1,220 @@
+# Repository Pattern Examples
+
+This directory contains examples demonstrating proper and improper implementations of the Repository Pattern.
+
+## Overview
+
+The Repository Pattern provides an abstraction layer between domain logic and data access. A well-implemented repository:
+
+1. Uses domain types, not ORM-specific types
+2. Depends on interfaces, not concrete implementations
+3. Uses dependency injection, not direct instantiation
+4. Uses domain language, not technical database terms
+
+## Examples
+
+### ❌ Bad Examples
+
+#### 1. ORM Types in Interface
+**File:** `bad-orm-types-in-interface.ts`
+
+**Problem:** Repository interface exposes Prisma-specific types (`Prisma.UserWhereInput`, `Prisma.UserCreateInput`). This couples the domain layer to infrastructure concerns.
+
+**Violations:**
+- Domain depends on ORM library
+- Cannot swap ORM without changing domain
+- Breaks Clean Architecture principles
+
+#### 2. Concrete Repository in Use Case
+**File:** `bad-concrete-repository-in-use-case.ts`
+
+**Problem:** Use case depends on `PrismaUserRepository` instead of `IUserRepository` interface.
+
+**Violations:**
+- Violates Dependency Inversion Principle
+- Cannot easily mock for testing
+- Tightly coupled to specific implementation
+
+#### 3. Creating Repository with 'new'
+**File:** `bad-new-repository.ts`
+
+**Problem:** Use case instantiates repositories with `new UserRepository()` instead of receiving them through constructor.
+
+**Violations:**
+- Violates Dependency Injection principle
+- Hard to test (cannot mock dependencies)
+- Hidden dependencies
+- Creates tight coupling
+
+#### 4. Technical Method Names
+**File:** `bad-technical-method-names.ts`
+
+**Problem:** Repository methods use database/SQL terminology (`findOne`, `insert`, `query`, `execute`).
+
+**Violations:**
+- Uses technical terms instead of domain language
+- Exposes implementation details
+- Not aligned with ubiquitous language
+
+### ✅ Good Examples
+
+#### 1. Clean Interface
+**File:** `good-clean-interface.ts`
+
+**Benefits:**
+- Uses only domain types (UserId, Email, User)
+- ORM-agnostic interface
+- Easy to understand and maintain
+- Follows Clean Architecture
+
+```typescript
+interface IUserRepository {
+    findById(id: UserId): Promise<User | null>
+    findByEmail(email: Email): Promise<User | null>
+    save(user: User): Promise<void>
+    delete(id: UserId): Promise<void>
+}
+```
+
+#### 2. Interface in Use Case
+**File:** `good-interface-in-use-case.ts`
+
+**Benefits:**
+- Depends on interface, not concrete class
+- Easy to test with mocks
+- Can swap implementations
+- Follows Dependency Inversion Principle
+
+```typescript
+class CreateUser {
+    constructor(private readonly userRepo: IUserRepository) {}
+
+    async execute(data: CreateUserRequest): Promise<UserResponseDto> {
+        // Uses interface, not concrete implementation
+    }
+}
+```
+
+#### 3. Dependency Injection
+**File:** `good-dependency-injection.ts`
+
+**Benefits:**
+- All dependencies injected through constructor
+- Explicit dependencies (no hidden coupling)
+- Easy to test with mocks
+- Follows SOLID principles
+
+```typescript
+class CreateUser {
+    constructor(
+        private readonly userRepo: IUserRepository,
+        private readonly emailService: IEmailService
+    ) {}
+}
+```
+
+#### 4. Domain Language
+**File:** `good-domain-language.ts`
+
+**Benefits:**
+- Methods use business-oriented names
+- Self-documenting interface
+- Aligns with ubiquitous language
+- Hides implementation details
+
+```typescript
+interface IUserRepository {
+    findById(id: UserId): Promise<User | null>
+    findByEmail(email: Email): Promise<User | null>
+    findActiveUsers(): Promise<User[]>
+    save(user: User): Promise<void>
+    search(criteria: UserSearchCriteria): Promise<User[]>
+}
+```
+
+## Key Principles
+
+### 1. Persistence Ignorance
+Domain entities and repositories should not know about how data is persisted.
+
+```typescript
+// ❌ Bad: Domain knows about Prisma
+interface IUserRepository {
+    find(query: Prisma.UserWhereInput): Promise<User>
+}
+
+// ✅ Good: Domain uses own types
+interface IUserRepository {
+    findById(id: UserId): Promise<User | null>
+}
+```
+
+### 2. Dependency Inversion
+High-level modules (use cases) should not depend on low-level modules (repositories). Both should depend on abstractions (interfaces).
+
+```typescript
+// ❌ Bad: Use case depends on concrete repository
+class CreateUser {
+    constructor(private repo: PrismaUserRepository) {}
+}
+
+// ✅ Good: Use case depends on interface
+class CreateUser {
+    constructor(private repo: IUserRepository) {}
+}
+```
+
+### 3. Dependency Injection
+Don't create dependencies inside classes. Inject them through constructor.
+
+```typescript
+// ❌ Bad: Creates dependency
+class CreateUser {
+    execute() {
+        const repo = new UserRepository()
+    }
+}
+
+// ✅ Good: Injects dependency
+class CreateUser {
+    constructor(private readonly repo: IUserRepository) {}
+}
+```
+
+### 4. Ubiquitous Language
+Use domain language everywhere, including repository methods.
+
+```typescript
+// ❌ Bad: Technical terminology
+interface IUserRepository {
+    findOne(id: string): Promise<User>
+    insert(user: User): Promise<void>
+}
+
+// ✅ Good: Domain language
+interface IUserRepository {
+    findById(id: UserId): Promise<User | null>
+    save(user: User): Promise<void>
+}
+```
+
+## Testing with Guardian
+
+Run Guardian to detect Repository Pattern violations:
+
+```bash
+guardian check --root ./examples/repository-pattern
+```
+
+Guardian will detect:
+- ORM types in repository interfaces
+- Concrete repository usage in use cases
+- Repository instantiation with 'new'
+- Technical method names in repositories
+
+## Further Reading
+
+- [Clean Architecture by Robert C. Martin](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
+- [Domain-Driven Design by Eric Evans](https://www.domainlanguage.com/ddd/)
+- [Repository Pattern - Martin Fowler](https://martinfowler.com/eaaCatalog/repository.html)
+- [SOLID Principles](https://en.wikipedia.org/wiki/SOLID)
--- a/packages/guardian/examples/repository-pattern/bad-concrete-repository-in-use-case.ts
+++ b/packages/guardian/examples/repository-pattern/bad-concrete-repository-in-use-case.ts
@@ -0,0 +1,67 @@
+/**
+ * ❌ BAD EXAMPLE: Concrete repository in use case
+ *
+ * Use case depends on concrete repository implementation instead of interface.
+ * This violates Dependency Inversion Principle.
+ */
+
+class CreateUser {
+    constructor(private userRepo: PrismaUserRepository) {}
+
+    async execute(data: CreateUserRequest): Promise<UserResponseDto> {
+        const user = User.create(data.email, data.name)
+        await this.userRepo.save(user)
+        return UserMapper.toDto(user)
+    }
+}
+
+class PrismaUserRepository {
+    constructor(private prisma: any) {}
+
+    async save(user: User): Promise<void> {
+        await this.prisma.user.create({
+            data: {
+                email: user.getEmail(),
+                name: user.getName(),
+            },
+        })
+    }
+}
+
+class User {
+    static create(email: string, name: string): User {
+        return new User(email, name)
+    }
+
+    constructor(
+        private email: string,
+        private name: string,
+    ) {}
+
+    getEmail(): string {
+        return this.email
+    }
+
+    getName(): string {
+        return this.name
+    }
+}
+
+interface CreateUserRequest {
+    email: string
+    name: string
+}
+
+interface UserResponseDto {
+    email: string
+    name: string
+}
+
+class UserMapper {
+    static toDto(user: User): UserResponseDto {
+        return {
+            email: user.getEmail(),
+            name: user.getName(),
+        }
+    }
+}
--- a/packages/guardian/examples/repository-pattern/bad-new-repository.ts
+++ b/packages/guardian/examples/repository-pattern/bad-new-repository.ts
@@ -0,0 +1,69 @@
+/**
+ * ❌ BAD EXAMPLE: Creating repository with 'new' in use case
+ *
+ * Use case creates repository instances directly.
+ * This violates Dependency Injection principle and makes testing difficult.
+ */
+
+class CreateUser {
+    async execute(data: CreateUserRequest): Promise<UserResponseDto> {
+        const userRepo = new UserRepository()
+        const emailService = new EmailService()
+
+        const user = User.create(data.email, data.name)
+        await userRepo.save(user)
+        await emailService.sendWelcomeEmail(user.getEmail())
+
+        return UserMapper.toDto(user)
+    }
+}
+
+class UserRepository {
+    async save(user: User): Promise<void> {
+        console.warn("Saving user to database")
+    }
+}
+
+class EmailService {
+    async sendWelcomeEmail(email: string): Promise<void> {
+        console.warn(`Sending welcome email to ${email}`)
+    }
+}
+
+class User {
+    static create(email: string, name: string): User {
+        return new User(email, name)
+    }
+
+    constructor(
+        private email: string,
+        private name: string,
+    ) {}
+
+    getEmail(): string {
+        return this.email
+    }
+
+    getName(): string {
+        return this.name
+    }
+}
+
+interface CreateUserRequest {
+    email: string
+    name: string
+}
+
+interface UserResponseDto {
+    email: string
+    name: string
+}
+
+class UserMapper {
+    static toDto(user: User): UserResponseDto {
+        return {
+            email: user.getEmail(),
+            name: user.getName(),
+        }
+    }
+}
--- a/packages/guardian/examples/repository-pattern/bad-orm-types-in-interface.ts
+++ b/packages/guardian/examples/repository-pattern/bad-orm-types-in-interface.ts
@@ -0,0 +1,26 @@
+/**
+ * ❌ BAD EXAMPLE: ORM-specific types in repository interface
+ *
+ * This violates Repository Pattern by coupling domain layer to infrastructure (ORM).
+ * Domain should remain persistence-agnostic.
+ */
+
+import { Prisma, PrismaClient } from "@prisma/client"
+
+interface IUserRepository {
+    findOne(query: Prisma.UserWhereInput): Promise<User | null>
+
+    findMany(query: Prisma.UserFindManyArgs): Promise<User[]>
+
+    create(data: Prisma.UserCreateInput): Promise<User>
+
+    update(id: string, data: Prisma.UserUpdateInput): Promise<User>
+}
+
+class User {
+    constructor(
+        public id: string,
+        public email: string,
+        public name: string,
+    ) {}
+}
--- a/packages/guardian/examples/repository-pattern/bad-technical-method-names.ts
+++ b/packages/guardian/examples/repository-pattern/bad-technical-method-names.ts
@@ -0,0 +1,32 @@
+/**
+ * ❌ BAD EXAMPLE: Technical method names
+ *
+ * Repository interface uses database/ORM terminology instead of domain language.
+ * Methods should reflect business operations, not technical implementation.
+ */
+
+interface IUserRepository {
+    findOne(id: string): Promise<User | null>
+
+    findMany(filter: any): Promise<User[]>
+
+    insert(user: User): Promise<void>
+
+    updateOne(id: string, data: any): Promise<void>
+
+    deleteOne(id: string): Promise<void>
+
+    query(sql: string): Promise<any>
+
+    execute(command: string): Promise<void>
+
+    select(fields: string[]): Promise<User[]>
+}
+
+class User {
+    constructor(
+        public id: string,
+        public email: string,
+        public name: string,
+    ) {}
+}
--- a/packages/guardian/examples/repository-pattern/good-clean-interface.ts
+++ b/packages/guardian/examples/repository-pattern/good-clean-interface.ts
@@ -0,0 +1,61 @@
+/**
+ * ✅ GOOD EXAMPLE: Clean repository interface
+ *
+ * Repository interface uses only domain types, keeping it persistence-agnostic.
+ * ORM implementation details stay in infrastructure layer.
+ */
+
+interface IUserRepository {
+    findById(id: UserId): Promise<User | null>
+
+    findByEmail(email: Email): Promise<User | null>
+
+    save(user: User): Promise<void>
+
+    delete(id: UserId): Promise<void>
+
+    findAll(criteria: UserSearchCriteria): Promise<User[]>
+}
+
+class UserId {
+    constructor(private readonly value: string) {}
+
+    getValue(): string {
+        return this.value
+    }
+}
+
+class Email {
+    constructor(private readonly value: string) {}
+
+    getValue(): string {
+        return this.value
+    }
+}
+
+class UserSearchCriteria {
+    constructor(
+        public readonly isActive?: boolean,
+        public readonly registeredAfter?: Date,
+    ) {}
+}
+
+class User {
+    constructor(
+        private readonly id: UserId,
+        private email: Email,
+        private name: string,
+    ) {}
+
+    getId(): UserId {
+        return this.id
+    }
+
+    getEmail(): Email {
+        return this.email
+    }
+
+    getName(): string {
+        return this.name
+    }
+}
--- a/packages/guardian/examples/repository-pattern/good-dependency-injection.ts
+++ b/packages/guardian/examples/repository-pattern/good-dependency-injection.ts
@@ -0,0 +1,98 @@
+/**
+ * ✅ GOOD EXAMPLE: Dependency Injection
+ *
+ * Use case receives dependencies through constructor.
+ * This makes code testable and follows SOLID principles.
+ */
+
+class CreateUser {
+    constructor(
+        private readonly userRepo: IUserRepository,
+        private readonly emailService: IEmailService,
+    ) {}
+
+    async execute(data: CreateUserRequest): Promise<UserResponseDto> {
+        const user = User.create(Email.from(data.email), data.name)
+        await this.userRepo.save(user)
+        await this.emailService.sendWelcomeEmail(user.getEmail())
+        return UserMapper.toDto(user)
+    }
+}
+
+interface IUserRepository {
+    save(user: User): Promise<void>
+    findByEmail(email: Email): Promise<User | null>
+}
+
+interface IEmailService {
+    sendWelcomeEmail(email: Email): Promise<void>
+}
+
+class Email {
+    private constructor(private readonly value: string) {}
+
+    static from(value: string): Email {
+        if (!value.includes("@")) {
+            throw new Error("Invalid email")
+        }
+        return new Email(value)
+    }
+
+    getValue(): string {
+        return this.value
+    }
+}
+
+class User {
+    static create(email: Email, name: string): User {
+        return new User(email, name)
+    }
+
+    private constructor(
+        private readonly email: Email,
+        private readonly name: string,
+    ) {}
+
+    getEmail(): Email {
+        return this.email
+    }
+
+    getName(): string {
+        return this.name
+    }
+}
+
+interface CreateUserRequest {
+    email: string
+    name: string
+}
+
+interface UserResponseDto {
+    email: string
+    name: string
+}
+
+class UserMapper {
+    static toDto(user: User): UserResponseDto {
+        return {
+            email: user.getEmail().getValue(),
+            name: user.getName(),
+        }
+    }
+}
+
+class UserRepository implements IUserRepository {
+    async save(_user: User): Promise<void> {
+        console.warn("Saving user to database")
+    }
+
+    async findByEmail(_email: Email): Promise<User | null> {
+        return null
+    }
+}
+
+class EmailService implements IEmailService {
+    async sendWelcomeEmail(email: Email): Promise<void> {
+        console.warn(`Sending welcome email to ${email.getValue()}`)
+    }
+}
--- a/packages/guardian/examples/repository-pattern/good-domain-language.ts
+++ b/packages/guardian/examples/repository-pattern/good-domain-language.ts
@@ -0,0 +1,81 @@
+/**
+ * ✅ GOOD EXAMPLE: Domain language in repository
+ *
+ * Repository interface uses domain-driven method names that reflect business operations.
+ * Method names are self-documenting and align with ubiquitous language.
+ */
+
+interface IUserRepository {
+    findById(id: UserId): Promise<User | null>
+
+    findByEmail(email: Email): Promise<User | null>
+
+    findActiveUsers(): Promise<User[]>
+
+    save(user: User): Promise<void>
+
+    delete(id: UserId): Promise<void>
+
+    search(criteria: UserSearchCriteria): Promise<User[]>
+
+    countActiveUsers(): Promise<number>
+
+    existsByEmail(email: Email): Promise<boolean>
+}
+
+class UserId {
+    constructor(private readonly value: string) {}
+
+    getValue(): string {
+        return this.value
+    }
+}
+
+class Email {
+    constructor(private readonly value: string) {}
+
+    getValue(): string {
+        return this.value
+    }
+}
+
+class UserSearchCriteria {
+    constructor(
+        public readonly isActive?: boolean,
+        public readonly registeredAfter?: Date,
+        public readonly department?: string,
+    ) {}
+}
+
+class User {
+    constructor(
+        private readonly id: UserId,
+        private email: Email,
+        private name: string,
+        private isActive: boolean,
+    ) {}
+
+    getId(): UserId {
+        return this.id
+    }
+
+    getEmail(): Email {
+        return this.email
+    }
+
+    getName(): string {
+        return this.name
+    }
+
+    isUserActive(): boolean {
+        return this.isActive
+    }
+
+    activate(): void {
+        this.isActive = true
+    }
+
+    deactivate(): void {
+        this.isActive = false
+    }
+}
--- a/packages/guardian/examples/repository-pattern/good-interface-in-use-case.ts
+++ b/packages/guardian/examples/repository-pattern/good-interface-in-use-case.ts
@@ -0,0 +1,74 @@
+/**
+ * ✅ GOOD EXAMPLE: Repository interface in use case
+ *
+ * Use case depends on repository interface, not concrete implementation.
+ * This follows Dependency Inversion Principle.
+ */
+
+class CreateUser {
+    constructor(private readonly userRepo: IUserRepository) {}
+
+    async execute(data: CreateUserRequest): Promise<UserResponseDto> {
+        const user = User.create(Email.from(data.email), data.name)
+        await this.userRepo.save(user)
+        return UserMapper.toDto(user)
+    }
+}
+
+interface IUserRepository {
+    save(user: User): Promise<void>
+    findByEmail(email: Email): Promise<User | null>
+}
+
+class Email {
+    private constructor(private readonly value: string) {}
+
+    static from(value: string): Email {
+        if (!value.includes("@")) {
+            throw new Error("Invalid email")
+        }
+        return new Email(value)
+    }
+
+    getValue(): string {
+        return this.value
+    }
+}
+
+class User {
+    static create(email: Email, name: string): User {
+        return new User(email, name)
+    }
+
+    private constructor(
+        private readonly email: Email,
+        private readonly name: string,
+    ) {}
+
+    getEmail(): Email {
+        return this.email
+    }
+
+    getName(): string {
+        return this.name
+    }
+}
+
+interface CreateUserRequest {
+    email: string
+    name: string
+}
+
+interface UserResponseDto {
+    email: string
+    name: string
+}
+
+class UserMapper {
+    static toDto(user: User): UserResponseDto {
+        return {
+            email: user.getEmail().getValue(),
+            name: user.getName(),
+        }
+    }
+}
--- a/packages/guardian/package.json
+++ b/packages/guardian/package.json
@@ -1,7 +1,7 @@
 {
    "name": "@samiyev/guardian",
-    "version": "0.1.0",
-    "description": "Code quality guardian for vibe coders and enterprise teams - catch hardcodes, architecture violations, and circular deps. Enforce Clean Architecture at scale. Works with Claude, GPT, Copilot.",
+    "version": "0.9.4",
+    "description": "Research-backed code quality guardian for AI-assisted development. Detects hardcodes, secrets, circular deps, framework leaks, entity exposure, and 9 architecture violations. Enforces Clean Architecture/DDD principles. Works with GitHub Copilot, Cursor, Windsurf, Claude, ChatGPT, Cline, and any AI coding tool.",
    "keywords": [
        "puaros",
        "guardian",
@@ -40,7 +40,7 @@
    "license": "MIT",
    "repository": {
        "type": "git",
-        "url": "https://github.com/samiyev/puaros.git",
+        "url": "git+https://github.com/samiyev/puaros.git",
        "directory": "packages/guardian"
    },
    "bugs": {
@@ -82,6 +82,10 @@
        "guardian": "./bin/guardian.js"
    },
    "dependencies": {
+        "@secretlint/core": "^11.2.5",
+        "@secretlint/node": "^11.2.5",
+        "@secretlint/secretlint-rule-preset-recommend": "^11.2.5",
+        "@secretlint/types": "^11.2.5",
        "commander": "^12.1.0",
        "simple-git": "^3.30.0",
        "tree-sitter": "^0.21.1",
--- a/packages/guardian/src/api.ts
+++ b/packages/guardian/src/api.ts
@@ -8,11 +8,25 @@ import { ICodeParser } from "./domain/services/ICodeParser"
 import { IHardcodeDetector } from "./domain/services/IHardcodeDetector"
 import { INamingConventionDetector } from "./domain/services/INamingConventionDetector"
 import { IFrameworkLeakDetector } from "./domain/services/IFrameworkLeakDetector"
+import { IEntityExposureDetector } from "./domain/services/IEntityExposureDetector"
+import { IDependencyDirectionDetector } from "./domain/services/IDependencyDirectionDetector"
+import { IRepositoryPatternDetector } from "./domain/services/RepositoryPatternDetectorService"
+import { IAggregateBoundaryDetector } from "./domain/services/IAggregateBoundaryDetector"
+import { ISecretDetector } from "./domain/services/ISecretDetector"
+import { IAnemicModelDetector } from "./domain/services/IAnemicModelDetector"
+import { IDuplicateValueTracker } from "./domain/services/IDuplicateValueTracker"
 import { FileScanner } from "./infrastructure/scanners/FileScanner"
 import { CodeParser } from "./infrastructure/parsers/CodeParser"
 import { HardcodeDetector } from "./infrastructure/analyzers/HardcodeDetector"
 import { NamingConventionDetector } from "./infrastructure/analyzers/NamingConventionDetector"
 import { FrameworkLeakDetector } from "./infrastructure/analyzers/FrameworkLeakDetector"
+import { EntityExposureDetector } from "./infrastructure/analyzers/EntityExposureDetector"
+import { DependencyDirectionDetector } from "./infrastructure/analyzers/DependencyDirectionDetector"
+import { RepositoryPatternDetector } from "./infrastructure/analyzers/RepositoryPatternDetector"
+import { AggregateBoundaryDetector } from "./infrastructure/analyzers/AggregateBoundaryDetector"
+import { SecretDetector } from "./infrastructure/analyzers/SecretDetector"
+import { AnemicModelDetector } from "./infrastructure/analyzers/AnemicModelDetector"
+import { DuplicateValueTracker } from "./infrastructure/analyzers/DuplicateValueTracker"
 import { ERROR_MESSAGES } from "./shared/constants"

 /**
@@ -66,12 +80,27 @@ export async function analyzeProject(
    const hardcodeDetector: IHardcodeDetector = new HardcodeDetector()
    const namingConventionDetector: INamingConventionDetector = new NamingConventionDetector()
    const frameworkLeakDetector: IFrameworkLeakDetector = new FrameworkLeakDetector()
+    const entityExposureDetector: IEntityExposureDetector = new EntityExposureDetector()
+    const dependencyDirectionDetector: IDependencyDirectionDetector =
+        new DependencyDirectionDetector()
+    const repositoryPatternDetector: IRepositoryPatternDetector = new RepositoryPatternDetector()
+    const aggregateBoundaryDetector: IAggregateBoundaryDetector = new AggregateBoundaryDetector()
+    const secretDetector: ISecretDetector = new SecretDetector()
+    const anemicModelDetector: IAnemicModelDetector = new AnemicModelDetector()
+    const duplicateValueTracker: IDuplicateValueTracker = new DuplicateValueTracker()
    const useCase = new AnalyzeProject(
        fileScanner,
        codeParser,
        hardcodeDetector,
        namingConventionDetector,
        frameworkLeakDetector,
+        entityExposureDetector,
+        dependencyDirectionDetector,
+        repositoryPatternDetector,
+        aggregateBoundaryDetector,
+        secretDetector,
+        anemicModelDetector,
+        duplicateValueTracker,
    )

    const result = await useCase.execute(options)
@@ -91,5 +120,10 @@ export type {
    CircularDependencyViolation,
    NamingConventionViolation,
    FrameworkLeakViolation,
+    EntityExposureViolation,
+    DependencyDirectionViolation,
+    RepositoryPatternViolation,
+    AggregateBoundaryViolation,
+    AnemicModelViolation,
    ProjectMetrics,
 } from "./application/use-cases/AnalyzeProject"
--- a/packages/guardian/src/application/use-cases/AnalyzeProject.ts
+++ b/packages/guardian/src/application/use-cases/AnalyzeProject.ts
@@ -5,17 +5,26 @@ import { ICodeParser } from "../../domain/services/ICodeParser"
 import { IHardcodeDetector } from "../../domain/services/IHardcodeDetector"
 import { INamingConventionDetector } from "../../domain/services/INamingConventionDetector"
 import { IFrameworkLeakDetector } from "../../domain/services/IFrameworkLeakDetector"
+import { IEntityExposureDetector } from "../../domain/services/IEntityExposureDetector"
+import { IDependencyDirectionDetector } from "../../domain/services/IDependencyDirectionDetector"
+import { IRepositoryPatternDetector } from "../../domain/services/RepositoryPatternDetectorService"
+import { IAggregateBoundaryDetector } from "../../domain/services/IAggregateBoundaryDetector"
+import { ISecretDetector } from "../../domain/services/ISecretDetector"
+import { IAnemicModelDetector } from "../../domain/services/IAnemicModelDetector"
+import { IDuplicateValueTracker } from "../../domain/services/IDuplicateValueTracker"
 import { SourceFile } from "../../domain/entities/SourceFile"
 import { DependencyGraph } from "../../domain/entities/DependencyGraph"
-import { ProjectPath } from "../../domain/value-objects/ProjectPath"
+import { CollectFiles } from "./pipeline/CollectFiles"
+import { ParseSourceFiles } from "./pipeline/ParseSourceFiles"
+import { ExecuteDetection } from "./pipeline/ExecuteDetection"
+import { AggregateResults } from "./pipeline/AggregateResults"
 import {
    ERROR_MESSAGES,
    HARDCODE_TYPES,
-    LAYERS,
    NAMING_VIOLATION_TYPES,
-    REGEX_PATTERNS,
+    REPOSITORY_VIOLATION_TYPES,
    RULES,
-    SEVERITY_LEVELS,
+    type SeverityLevel,
 } from "../../shared/constants"

 export interface AnalyzeProjectRequest {
@@ -32,6 +41,12 @@ export interface AnalyzeProjectResponse {
    circularDependencyViolations: CircularDependencyViolation[]
    namingViolations: NamingConventionViolation[]
    frameworkLeakViolations: FrameworkLeakViolation[]
+    entityExposureViolations: EntityExposureViolation[]
+    dependencyDirectionViolations: DependencyDirectionViolation[]
+    repositoryPatternViolations: RepositoryPatternViolation[]
+    aggregateBoundaryViolations: AggregateBoundaryViolation[]
+    secretViolations: SecretViolation[]
+    anemicModelViolations: AnemicModelViolation[]
    metrics: ProjectMetrics
 }

@@ -40,6 +55,7 @@ export interface ArchitectureViolation {
    message: string
    file: string
    line?: number
+    severity: SeverityLevel
 }

 export interface HardcodeViolation {
@@ -47,8 +63,9 @@ export interface HardcodeViolation {
    type:
        | typeof HARDCODE_TYPES.MAGIC_NUMBER
        | typeof HARDCODE_TYPES.MAGIC_STRING
+        | typeof HARDCODE_TYPES.MAGIC_BOOLEAN
        | typeof HARDCODE_TYPES.MAGIC_CONFIG
-    value: string | number
+    value: string | number | boolean
    file: string
    line: number
    column: number
@@ -57,13 +74,14 @@ export interface HardcodeViolation {
        constantName: string
        location: string
    }
+    severity: SeverityLevel
 }

 export interface CircularDependencyViolation {
    rule: typeof RULES.CIRCULAR_DEPENDENCY
    message: string
    cycle: string[]
-    severity: typeof SEVERITY_LEVELS.ERROR
+    severity: SeverityLevel
 }

 export interface NamingConventionViolation {
@@ -81,6 +99,7 @@ export interface NamingConventionViolation {
    actual: string
    message: string
    suggestion?: string
+    severity: SeverityLevel
 }

 export interface FrameworkLeakViolation {
@@ -93,6 +112,87 @@ export interface FrameworkLeakViolation {
    line?: number
    message: string
    suggestion: string
+    severity: SeverityLevel
+}
+
+export interface EntityExposureViolation {
+    rule: typeof RULES.ENTITY_EXPOSURE
+    entityName: string
+    returnType: string
+    file: string
+    layer: string
+    line?: number
+    methodName?: string
+    message: string
+    suggestion: string
+    severity: SeverityLevel
+}
+
+export interface DependencyDirectionViolation {
+    rule: typeof RULES.DEPENDENCY_DIRECTION
+    fromLayer: string
+    toLayer: string
+    importPath: string
+    file: string
+    line?: number
+    message: string
+    suggestion: string
+    severity: SeverityLevel
+}
+
+export interface RepositoryPatternViolation {
+    rule: typeof RULES.REPOSITORY_PATTERN
+    violationType:
+        | typeof REPOSITORY_VIOLATION_TYPES.ORM_TYPE_IN_INTERFACE
+        | typeof REPOSITORY_VIOLATION_TYPES.CONCRETE_REPOSITORY_IN_USE_CASE
+        | typeof REPOSITORY_VIOLATION_TYPES.NEW_REPOSITORY_IN_USE_CASE
+        | typeof REPOSITORY_VIOLATION_TYPES.NON_DOMAIN_METHOD_NAME
+    file: string
+    layer: string
+    line?: number
+    details: string
+    message: string
+    suggestion: string
+    severity: SeverityLevel
+}
+
+export interface AggregateBoundaryViolation {
+    rule: typeof RULES.AGGREGATE_BOUNDARY
+    fromAggregate: string
+    toAggregate: string
+    entityName: string
+    importPath: string
+    file: string
+    line?: number
+    message: string
+    suggestion: string
+    severity: SeverityLevel
+}
+
+export interface SecretViolation {
+    rule: typeof RULES.SECRET_EXPOSURE
+    secretType: string
+    file: string
+    line: number
+    column: number
+    message: string
+    suggestion: string
+    severity: SeverityLevel
+}
+
+export interface AnemicModelViolation {
+    rule: typeof RULES.ANEMIC_MODEL
+    className: string
+    file: string
+    layer: string
+    line?: number
+    methodCount: number
+    propertyCount: number
+    hasOnlyGettersSetters: boolean
+    hasPublicSetters: boolean
+    message: string
+    suggestion: string
+    severity: SeverityLevel
 }

 export interface ProjectMetrics {
@@ -104,286 +204,81 @@ export interface ProjectMetrics {

 /**
 * Main use case for analyzing a project's codebase
+ * Orchestrates the analysis pipeline through focused components
 */
 export class AnalyzeProject extends UseCase<
    AnalyzeProjectRequest,
    ResponseDto<AnalyzeProjectResponse>
 > {
+    private readonly fileCollectionStep: CollectFiles
+    private readonly parsingStep: ParseSourceFiles
+    private readonly detectionPipeline: ExecuteDetection
+    private readonly resultAggregator: AggregateResults
+
+    // eslint-disable-next-line max-params
    constructor(
-        private readonly fileScanner: IFileScanner,
-        private readonly codeParser: ICodeParser,
-        private readonly hardcodeDetector: IHardcodeDetector,
-        private readonly namingConventionDetector: INamingConventionDetector,
-        private readonly frameworkLeakDetector: IFrameworkLeakDetector,
+        fileScanner: IFileScanner,
+        codeParser: ICodeParser,
+        hardcodeDetector: IHardcodeDetector,
+        namingConventionDetector: INamingConventionDetector,
+        frameworkLeakDetector: IFrameworkLeakDetector,
+        entityExposureDetector: IEntityExposureDetector,
+        dependencyDirectionDetector: IDependencyDirectionDetector,
+        repositoryPatternDetector: IRepositoryPatternDetector,
+        aggregateBoundaryDetector: IAggregateBoundaryDetector,
+        secretDetector: ISecretDetector,
+        anemicModelDetector: IAnemicModelDetector,
+        duplicateValueTracker: IDuplicateValueTracker,
    ) {
        super()
+        this.fileCollectionStep = new CollectFiles(fileScanner)
+        this.parsingStep = new ParseSourceFiles(codeParser)
+        this.detectionPipeline = new ExecuteDetection(
+            hardcodeDetector,
+            namingConventionDetector,
+            frameworkLeakDetector,
+            entityExposureDetector,
+            dependencyDirectionDetector,
+            repositoryPatternDetector,
+            aggregateBoundaryDetector,
+            secretDetector,
+            anemicModelDetector,
+            duplicateValueTracker,
+        )
+        this.resultAggregator = new AggregateResults()
    }

    public async execute(
        request: AnalyzeProjectRequest,
    ): Promise<ResponseDto<AnalyzeProjectResponse>> {
        try {
-            const filePaths = await this.fileScanner.scan({
+            const { sourceFiles } = await this.fileCollectionStep.execute({
                rootDir: request.rootDir,
                include: request.include,
                exclude: request.exclude,
            })

-            const sourceFiles: SourceFile[] = []
-            const dependencyGraph = new DependencyGraph()
-            let totalFunctions = 0
-
-            for (const filePath of filePaths) {
-                const content = await this.fileScanner.readFile(filePath)
-                const projectPath = ProjectPath.create(filePath, request.rootDir)
-
-                const imports = this.extractImports(content)
-                const exports = this.extractExports(content)
-
-                const sourceFile = new SourceFile(projectPath, content, imports, exports)
-
-                sourceFiles.push(sourceFile)
-                dependencyGraph.addFile(sourceFile)
-
-                if (projectPath.isTypeScript()) {
-                    const tree = this.codeParser.parseTypeScript(content)
-                    const functions = this.codeParser.extractFunctions(tree)
-                    totalFunctions += functions.length
-                }
-
-                for (const imp of imports) {
-                    dependencyGraph.addDependency(
-                        projectPath.relative,
-                        this.resolveImportPath(imp, filePath, request.rootDir),
-                    )
-                }
-            }
-
-            const violations = this.detectViolations(sourceFiles)
-            const hardcodeViolations = this.detectHardcode(sourceFiles)
-            const circularDependencyViolations = this.detectCircularDependencies(dependencyGraph)
-            const namingViolations = this.detectNamingConventions(sourceFiles)
-            const frameworkLeakViolations = this.detectFrameworkLeaks(sourceFiles)
-            const metrics = this.calculateMetrics(sourceFiles, totalFunctions, dependencyGraph)
-
-            return ResponseDto.ok({
-                files: sourceFiles,
-                dependencyGraph,
-                violations,
-                hardcodeViolations,
-                circularDependencyViolations,
-                namingViolations,
-                frameworkLeakViolations,
-                metrics,
+            const { dependencyGraph, totalFunctions } = this.parsingStep.execute({
+                sourceFiles,
+                rootDir: request.rootDir,
            })
+
+            const detectionResult = await this.detectionPipeline.execute({
+                sourceFiles,
+                dependencyGraph,
+            })
+
+            const response = this.resultAggregator.execute({
+                sourceFiles,
+                dependencyGraph,
+                totalFunctions,
+                ...detectionResult,
+            })
+
+            return ResponseDto.ok(response)
        } catch (error) {
            const errorMessage = `${ERROR_MESSAGES.FAILED_TO_ANALYZE}: ${error instanceof Error ? error.message : String(error)}`
            return ResponseDto.fail(errorMessage)
        }
    }
-
-    private extractImports(content: string): string[] {
-        const imports: string[] = []
-        let match
-
-        while ((match = REGEX_PATTERNS.IMPORT_STATEMENT.exec(content)) !== null) {
-            imports.push(match[1])
-        }
-
-        return imports
-    }
-
-    private extractExports(content: string): string[] {
-        const exports: string[] = []
-        let match
-
-        while ((match = REGEX_PATTERNS.EXPORT_STATEMENT.exec(content)) !== null) {
-            exports.push(match[1])
-        }
-
-        return exports
-    }
-
-    private resolveImportPath(importPath: string, _currentFile: string, _rootDir: string): string {
-        if (importPath.startsWith(".")) {
-            return importPath
-        }
-        return importPath
-    }
-
-    private detectViolations(sourceFiles: SourceFile[]): ArchitectureViolation[] {
-        const violations: ArchitectureViolation[] = []
-
-        const layerRules: Record<string, string[]> = {
-            [LAYERS.DOMAIN]: [LAYERS.SHARED],
-            [LAYERS.APPLICATION]: [LAYERS.DOMAIN, LAYERS.SHARED],
-            [LAYERS.INFRASTRUCTURE]: [LAYERS.DOMAIN, LAYERS.APPLICATION, LAYERS.SHARED],
-            [LAYERS.SHARED]: [],
-        }
-
-        for (const file of sourceFiles) {
-            if (!file.layer) {
-                continue
-            }
-
-            const allowedLayers = layerRules[file.layer]
-
-            for (const imp of file.imports) {
-                const importedLayer = this.detectLayerFromImport(imp)
-
-                if (
-                    importedLayer &&
-                    importedLayer !== file.layer &&
-                    !allowedLayers.includes(importedLayer)
-                ) {
-                    violations.push({
-                        rule: RULES.CLEAN_ARCHITECTURE,
-                        message: `Layer "${file.layer}" cannot import from "${importedLayer}"`,
-                        file: file.path.relative,
-                    })
-                }
-            }
-        }
-
-        return violations
-    }
-
-    private detectLayerFromImport(importPath: string): string | undefined {
-        const layers = Object.values(LAYERS)
-
-        for (const layer of layers) {
-            if (importPath.toLowerCase().includes(layer)) {
-                return layer
-            }
-        }
-
-        return undefined
-    }
-
-    private detectHardcode(sourceFiles: SourceFile[]): HardcodeViolation[] {
-        const violations: HardcodeViolation[] = []
-
-        for (const file of sourceFiles) {
-            const hardcodedValues = this.hardcodeDetector.detectAll(
-                file.content,
-                file.path.relative,
-            )
-
-            for (const hardcoded of hardcodedValues) {
-                violations.push({
-                    rule: RULES.HARDCODED_VALUE,
-                    type: hardcoded.type,
-                    value: hardcoded.value,
-                    file: file.path.relative,
-                    line: hardcoded.line,
-                    column: hardcoded.column,
-                    context: hardcoded.context,
-                    suggestion: {
-                        constantName: hardcoded.suggestConstantName(),
-                        location: hardcoded.suggestLocation(file.layer),
-                    },
-                })
-            }
-        }
-
-        return violations
-    }
-
-    private detectCircularDependencies(
-        dependencyGraph: DependencyGraph,
-    ): CircularDependencyViolation[] {
-        const violations: CircularDependencyViolation[] = []
-        const cycles = dependencyGraph.findCycles()
-
-        for (const cycle of cycles) {
-            const cycleChain = [...cycle, cycle[0]].join(" → ")
-            violations.push({
-                rule: RULES.CIRCULAR_DEPENDENCY,
-                message: `Circular dependency detected: ${cycleChain}`,
-                cycle,
-                severity: SEVERITY_LEVELS.ERROR,
-            })
-        }
-
-        return violations
-    }
-
-    private detectNamingConventions(sourceFiles: SourceFile[]): NamingConventionViolation[] {
-        const violations: NamingConventionViolation[] = []
-
-        for (const file of sourceFiles) {
-            const namingViolations = this.namingConventionDetector.detectViolations(
-                file.path.filename,
-                file.layer,
-                file.path.relative,
-            )
-
-            for (const violation of namingViolations) {
-                violations.push({
-                    rule: RULES.NAMING_CONVENTION,
-                    type: violation.violationType,
-                    fileName: violation.fileName,
-                    layer: violation.layer,
-                    file: violation.filePath,
-                    expected: violation.expected,
-                    actual: violation.actual,
-                    message: violation.getMessage(),
-                    suggestion: violation.suggestion,
-                })
-            }
-        }
-
-        return violations
-    }
-
-    private detectFrameworkLeaks(sourceFiles: SourceFile[]): FrameworkLeakViolation[] {
-        const violations: FrameworkLeakViolation[] = []
-
-        for (const file of sourceFiles) {
-            const leaks = this.frameworkLeakDetector.detectLeaks(
-                file.imports,
-                file.path.relative,
-                file.layer,
-            )
-
-            for (const leak of leaks) {
-                violations.push({
-                    rule: RULES.FRAMEWORK_LEAK,
-                    packageName: leak.packageName,
-                    category: leak.category,
-                    categoryDescription: leak.getCategoryDescription(),
-                    file: file.path.relative,
-                    layer: leak.layer,
-                    line: leak.line,
-                    message: leak.getMessage(),
-                    suggestion: leak.getSuggestion(),
-                })
-            }
-        }
-
-        return violations
-    }
-
-    private calculateMetrics(
-        sourceFiles: SourceFile[],
-        totalFunctions: number,
-        _dependencyGraph: DependencyGraph,
-    ): ProjectMetrics {
-        const layerDistribution: Record<string, number> = {}
-        let totalImports = 0
-
-        for (const file of sourceFiles) {
-            if (file.layer) {
-                layerDistribution[file.layer] = (layerDistribution[file.layer] || 0) + 1
-            }
-            totalImports += file.imports.length
-        }
-
-        return {
-            totalFiles: sourceFiles.length,
-            totalFunctions,
-            totalImports,
-            layerDistribution,
-        }
-    }
 }
--- a/packages/guardian/src/application/use-cases/pipeline/AggregateResults.ts
+++ b/packages/guardian/src/application/use-cases/pipeline/AggregateResults.ts
@@ -0,0 +1,87 @@
+import { SourceFile } from "../../../domain/entities/SourceFile"
+import { DependencyGraph } from "../../../domain/entities/DependencyGraph"
+import type {
+    AggregateBoundaryViolation,
+    AnalyzeProjectResponse,
+    AnemicModelViolation,
+    ArchitectureViolation,
+    CircularDependencyViolation,
+    DependencyDirectionViolation,
+    EntityExposureViolation,
+    FrameworkLeakViolation,
+    HardcodeViolation,
+    NamingConventionViolation,
+    ProjectMetrics,
+    RepositoryPatternViolation,
+    SecretViolation,
+} from "../AnalyzeProject"
+
+export interface AggregationRequest {
+    sourceFiles: SourceFile[]
+    dependencyGraph: DependencyGraph
+    totalFunctions: number
+    violations: ArchitectureViolation[]
+    hardcodeViolations: HardcodeViolation[]
+    circularDependencyViolations: CircularDependencyViolation[]
+    namingViolations: NamingConventionViolation[]
+    frameworkLeakViolations: FrameworkLeakViolation[]
+    entityExposureViolations: EntityExposureViolation[]
+    dependencyDirectionViolations: DependencyDirectionViolation[]
+    repositoryPatternViolations: RepositoryPatternViolation[]
+    aggregateBoundaryViolations: AggregateBoundaryViolation[]
+    secretViolations: SecretViolation[]
+    anemicModelViolations: AnemicModelViolation[]
+}
+
+/**
+ * Pipeline step responsible for building final response DTO
+ */
+export class AggregateResults {
+    public execute(request: AggregationRequest): AnalyzeProjectResponse {
+        const metrics = this.calculateMetrics(
+            request.sourceFiles,
+            request.totalFunctions,
+            request.dependencyGraph,
+        )
+
+        return {
+            files: request.sourceFiles,
+            dependencyGraph: request.dependencyGraph,
+            violations: request.violations,
+            hardcodeViolations: request.hardcodeViolations,
+            circularDependencyViolations: request.circularDependencyViolations,
+            namingViolations: request.namingViolations,
+            frameworkLeakViolations: request.frameworkLeakViolations,
+            entityExposureViolations: request.entityExposureViolations,
+            dependencyDirectionViolations: request.dependencyDirectionViolations,
+            repositoryPatternViolations: request.repositoryPatternViolations,
+            aggregateBoundaryViolations: request.aggregateBoundaryViolations,
+            secretViolations: request.secretViolations,
+            anemicModelViolations: request.anemicModelViolations,
+            metrics,
+        }
+    }
+
+    private calculateMetrics(
+        sourceFiles: SourceFile[],
+        totalFunctions: number,
+        _dependencyGraph: DependencyGraph,
+    ): ProjectMetrics {
+        const layerDistribution: Record<string, number> = {}
+        let totalImports = 0
+
+        for (const file of sourceFiles) {
+            if (file.layer) {
+                layerDistribution[file.layer] = (layerDistribution[file.layer] || 0) + 1
+            }
+            totalImports += file.imports.length
+        }
+
+        return {
+            totalFiles: sourceFiles.length,
+            totalFunctions,
+            totalImports,
+            layerDistribution,
+        }
+    }
+}
--- a/packages/guardian/src/application/use-cases/pipeline/CollectFiles.ts
+++ b/packages/guardian/src/application/use-cases/pipeline/CollectFiles.ts
@@ -0,0 +1,66 @@
+import { IFileScanner } from "../../../domain/services/IFileScanner"
+import { SourceFile } from "../../../domain/entities/SourceFile"
+import { ProjectPath } from "../../../domain/value-objects/ProjectPath"
+import { REGEX_PATTERNS } from "../../../shared/constants"
+
+export interface FileCollectionRequest {
+    rootDir: string
+    include?: string[]
+    exclude?: string[]
+}
+
+export interface FileCollectionResult {
+    sourceFiles: SourceFile[]
+}
+
+/**
+ * Pipeline step responsible for file collection and basic parsing
+ */
+export class CollectFiles {
+    constructor(private readonly fileScanner: IFileScanner) {}
+
+    public async execute(request: FileCollectionRequest): Promise<FileCollectionResult> {
+        const filePaths = await this.fileScanner.scan({
+            rootDir: request.rootDir,
+            include: request.include,
+            exclude: request.exclude,
+        })
+
+        const sourceFiles: SourceFile[] = []
+
+        for (const filePath of filePaths) {
+            const content = await this.fileScanner.readFile(filePath)
+            const projectPath = ProjectPath.create(filePath, request.rootDir)
+
+            const imports = this.extractImports(content)
+            const exports = this.extractExports(content)
+
+            const sourceFile = new SourceFile(projectPath, content, imports, exports)
+            sourceFiles.push(sourceFile)
+        }
+
+        return { sourceFiles }
+    }
+
+    private extractImports(content: string): string[] {
+        const imports: string[] = []
+        let match
+
+        while ((match = REGEX_PATTERNS.IMPORT_STATEMENT.exec(content)) !== null) {
+            imports.push(match[1])
+        }
+
+        return imports
+    }
+
+    private extractExports(content: string): string[] {
+        const exports: string[] = []
+        let match
+
+        while ((match = REGEX_PATTERNS.EXPORT_STATEMENT.exec(content)) !== null) {
+            exports.push(match[1])
+        }
+
+        return exports
+    }
+}
--- a/packages/guardian/src/application/use-cases/pipeline/ExecuteDetection.ts
+++ b/packages/guardian/src/application/use-cases/pipeline/ExecuteDetection.ts
@@ -0,0 +1,482 @@
+import { IHardcodeDetector } from "../../../domain/services/IHardcodeDetector"
+import { INamingConventionDetector } from "../../../domain/services/INamingConventionDetector"
+import { IFrameworkLeakDetector } from "../../../domain/services/IFrameworkLeakDetector"
+import { IEntityExposureDetector } from "../../../domain/services/IEntityExposureDetector"
+import { IDependencyDirectionDetector } from "../../../domain/services/IDependencyDirectionDetector"
+import { IRepositoryPatternDetector } from "../../../domain/services/RepositoryPatternDetectorService"
+import { IAggregateBoundaryDetector } from "../../../domain/services/IAggregateBoundaryDetector"
+import { ISecretDetector } from "../../../domain/services/ISecretDetector"
+import { IAnemicModelDetector } from "../../../domain/services/IAnemicModelDetector"
+import { IDuplicateValueTracker } from "../../../domain/services/IDuplicateValueTracker"
+import { SourceFile } from "../../../domain/entities/SourceFile"
+import { DependencyGraph } from "../../../domain/entities/DependencyGraph"
+import { HardcodedValue } from "../../../domain/value-objects/HardcodedValue"
+import {
+    LAYERS,
+    REPOSITORY_VIOLATION_TYPES,
+    RULES,
+    SEVERITY_ORDER,
+    type SeverityLevel,
+    VIOLATION_SEVERITY_MAP,
+} from "../../../shared/constants"
+import type {
+    AggregateBoundaryViolation,
+    AnemicModelViolation,
+    ArchitectureViolation,
+    CircularDependencyViolation,
+    DependencyDirectionViolation,
+    EntityExposureViolation,
+    FrameworkLeakViolation,
+    HardcodeViolation,
+    NamingConventionViolation,
+    RepositoryPatternViolation,
+    SecretViolation,
+} from "../AnalyzeProject"
+
+export interface DetectionRequest {
+    sourceFiles: SourceFile[]
+    dependencyGraph: DependencyGraph
+}
+
+export interface DetectionResult {
+    violations: ArchitectureViolation[]
+    hardcodeViolations: HardcodeViolation[]
+    circularDependencyViolations: CircularDependencyViolation[]
+    namingViolations: NamingConventionViolation[]
+    frameworkLeakViolations: FrameworkLeakViolation[]
+    entityExposureViolations: EntityExposureViolation[]
+    dependencyDirectionViolations: DependencyDirectionViolation[]
+    repositoryPatternViolations: RepositoryPatternViolation[]
+    aggregateBoundaryViolations: AggregateBoundaryViolation[]
+    secretViolations: SecretViolation[]
+    anemicModelViolations: AnemicModelViolation[]
+}
+
+/**
+ * Pipeline step responsible for running all detectors
+ */
+export class ExecuteDetection {
+    // eslint-disable-next-line max-params
+    constructor(
+        private readonly hardcodeDetector: IHardcodeDetector,
+        private readonly namingConventionDetector: INamingConventionDetector,
+        private readonly frameworkLeakDetector: IFrameworkLeakDetector,
+        private readonly entityExposureDetector: IEntityExposureDetector,
+        private readonly dependencyDirectionDetector: IDependencyDirectionDetector,
+        private readonly repositoryPatternDetector: IRepositoryPatternDetector,
+        private readonly aggregateBoundaryDetector: IAggregateBoundaryDetector,
+        private readonly secretDetector: ISecretDetector,
+        private readonly anemicModelDetector: IAnemicModelDetector,
+        private readonly duplicateValueTracker: IDuplicateValueTracker,
+    ) {}
+
+    public async execute(request: DetectionRequest): Promise<DetectionResult> {
+        const secretViolations = await this.detectSecrets(request.sourceFiles)
+
+        return {
+            violations: this.sortBySeverity(this.detectViolations(request.sourceFiles)),
+            hardcodeViolations: this.sortBySeverity(this.detectHardcode(request.sourceFiles)),
+            circularDependencyViolations: this.sortBySeverity(
+                this.detectCircularDependencies(request.dependencyGraph),
+            ),
+            namingViolations: this.sortBySeverity(
+                this.detectNamingConventions(request.sourceFiles),
+            ),
+            frameworkLeakViolations: this.sortBySeverity(
+                this.detectFrameworkLeaks(request.sourceFiles),
+            ),
+            entityExposureViolations: this.sortBySeverity(
+                this.detectEntityExposures(request.sourceFiles),
+            ),
+            dependencyDirectionViolations: this.sortBySeverity(
+                this.detectDependencyDirections(request.sourceFiles),
+            ),
+            repositoryPatternViolations: this.sortBySeverity(
+                this.detectRepositoryPatternViolations(request.sourceFiles),
+            ),
+            aggregateBoundaryViolations: this.sortBySeverity(
+                this.detectAggregateBoundaryViolations(request.sourceFiles),
+            ),
+            secretViolations: this.sortBySeverity(secretViolations),
+            anemicModelViolations: this.sortBySeverity(
+                this.detectAnemicModels(request.sourceFiles),
+            ),
+        }
+    }
+
+    private detectViolations(sourceFiles: SourceFile[]): ArchitectureViolation[] {
+        const violations: ArchitectureViolation[] = []
+
+        const layerRules: Record<string, string[]> = {
+            [LAYERS.DOMAIN]: [LAYERS.SHARED],
+            [LAYERS.APPLICATION]: [LAYERS.DOMAIN, LAYERS.SHARED],
+            [LAYERS.INFRASTRUCTURE]: [LAYERS.DOMAIN, LAYERS.APPLICATION, LAYERS.SHARED],
+            [LAYERS.SHARED]: [],
+        }
+
+        for (const file of sourceFiles) {
+            if (!file.layer) {
+                continue
+            }
+
+            const allowedLayers = layerRules[file.layer]
+
+            for (const imp of file.imports) {
+                const importedLayer = this.detectLayerFromImport(imp)
+
+                if (
+                    importedLayer &&
+                    importedLayer !== file.layer &&
+                    !allowedLayers.includes(importedLayer)
+                ) {
+                    violations.push({
+                        rule: RULES.CLEAN_ARCHITECTURE,
+                        message: `Layer "${file.layer}" cannot import from "${importedLayer}"`,
+                        file: file.path.relative,
+                        severity: VIOLATION_SEVERITY_MAP.ARCHITECTURE,
+                    })
+                }
+            }
+        }
+
+        return violations
+    }
+
+    private detectLayerFromImport(importPath: string): string | undefined {
+        const layers = Object.values(LAYERS)
+
+        for (const layer of layers) {
+            if (importPath.toLowerCase().includes(layer)) {
+                return layer
+            }
+        }
+
+        return undefined
+    }
+
+    private detectHardcode(sourceFiles: SourceFile[]): HardcodeViolation[] {
+        const allHardcodedValues: {
+            value: HardcodedValue
+            file: SourceFile
+        }[] = []
+
+        for (const file of sourceFiles) {
+            const hardcodedValues = this.hardcodeDetector.detectAll(
+                file.content,
+                file.path.relative,
+            )
+
+            for (const hardcoded of hardcodedValues) {
+                allHardcodedValues.push({ value: hardcoded, file })
+            }
+        }
+
+        this.duplicateValueTracker.clear()
+        for (const { value, file } of allHardcodedValues) {
+            this.duplicateValueTracker.track(value, file.path.relative)
+        }
+
+        const violations: HardcodeViolation[] = []
+        for (const { value, file } of allHardcodedValues) {
+            const duplicateLocations = this.duplicateValueTracker.getDuplicateLocations(
+                value.value,
+                value.type,
+            )
+            const enrichedValue = duplicateLocations
+                ? HardcodedValue.create(
+                      value.value,
+                      value.type,
+                      value.line,
+                      value.column,
+                      value.context,
+                      value.valueType,
+                      duplicateLocations.filter((loc) => loc.file !== file.path.relative),
+                  )
+                : value
+
+            if (enrichedValue.shouldSkip(file.layer)) {
+                continue
+            }
+
+            violations.push({
+                rule: RULES.HARDCODED_VALUE,
+                type: enrichedValue.type,
+                value: enrichedValue.value,
+                file: file.path.relative,
+                line: enrichedValue.line,
+                column: enrichedValue.column,
+                context: enrichedValue.context,
+                suggestion: {
+                    constantName: enrichedValue.suggestConstantName(),
+                    location: enrichedValue.suggestLocation(file.layer),
+                },
+                severity: VIOLATION_SEVERITY_MAP.HARDCODE,
+            })
+        }
+
+        return violations
+    }
+
+    private detectCircularDependencies(
+        dependencyGraph: DependencyGraph,
+    ): CircularDependencyViolation[] {
+        const violations: CircularDependencyViolation[] = []
+        const cycles = dependencyGraph.findCycles()
+
+        for (const cycle of cycles) {
+            const cycleChain = [...cycle, cycle[0]].join(" → ")
+            violations.push({
+                rule: RULES.CIRCULAR_DEPENDENCY,
+                message: `Circular dependency detected: ${cycleChain}`,
+                cycle,
+                severity: VIOLATION_SEVERITY_MAP.CIRCULAR_DEPENDENCY,
+            })
+        }
+
+        return violations
+    }
+
+    private detectNamingConventions(sourceFiles: SourceFile[]): NamingConventionViolation[] {
+        const violations: NamingConventionViolation[] = []
+
+        for (const file of sourceFiles) {
+            const namingViolations = this.namingConventionDetector.detectViolations(
+                file.content,
+                file.path.filename,
+                file.layer,
+                file.path.relative,
+            )
+
+            for (const violation of namingViolations) {
+                violations.push({
+                    rule: RULES.NAMING_CONVENTION,
+                    type: violation.violationType,
+                    fileName: violation.fileName,
+                    layer: violation.layer,
+                    file: violation.filePath,
+                    expected: violation.expected,
+                    actual: violation.actual,
+                    message: violation.getMessage(),
+                    suggestion: violation.suggestion,
+                    severity: VIOLATION_SEVERITY_MAP.NAMING_CONVENTION,
+                })
+            }
+        }
+
+        return violations
+    }
+
+    private detectFrameworkLeaks(sourceFiles: SourceFile[]): FrameworkLeakViolation[] {
+        const violations: FrameworkLeakViolation[] = []
+
+        for (const file of sourceFiles) {
+            const leaks = this.frameworkLeakDetector.detectLeaks(
+                file.imports,
+                file.path.relative,
+                file.layer,
+            )
+
+            for (const leak of leaks) {
+                violations.push({
+                    rule: RULES.FRAMEWORK_LEAK,
+                    packageName: leak.packageName,
+                    category: leak.category,
+                    categoryDescription: leak.getCategoryDescription(),
+                    file: file.path.relative,
+                    layer: leak.layer,
+                    line: leak.line,
+                    message: leak.getMessage(),
+                    suggestion: leak.getSuggestion(),
+                    severity: VIOLATION_SEVERITY_MAP.FRAMEWORK_LEAK,
+                })
+            }
+        }
+
+        return violations
+    }
+
+    private detectEntityExposures(sourceFiles: SourceFile[]): EntityExposureViolation[] {
+        const violations: EntityExposureViolation[] = []
+
+        for (const file of sourceFiles) {
+            const exposures = this.entityExposureDetector.detectExposures(
+                file.content,
+                file.path.relative,
+                file.layer,
+            )
+
+            for (const exposure of exposures) {
+                violations.push({
+                    rule: RULES.ENTITY_EXPOSURE,
+                    entityName: exposure.entityName,
+                    returnType: exposure.returnType,
+                    file: file.path.relative,
+                    layer: exposure.layer,
+                    line: exposure.line,
+                    methodName: exposure.methodName,
+                    message: exposure.getMessage(),
+                    suggestion: exposure.getSuggestion(),
+                    severity: VIOLATION_SEVERITY_MAP.ENTITY_EXPOSURE,
+                })
+            }
+        }
+
+        return violations
+    }
+
+    private detectDependencyDirections(sourceFiles: SourceFile[]): DependencyDirectionViolation[] {
+        const violations: DependencyDirectionViolation[] = []
+
+        for (const file of sourceFiles) {
+            const directionViolations = this.dependencyDirectionDetector.detectViolations(
+                file.content,
+                file.path.relative,
+                file.layer,
+            )
+
+            for (const violation of directionViolations) {
+                violations.push({
+                    rule: RULES.DEPENDENCY_DIRECTION,
+                    fromLayer: violation.fromLayer,
+                    toLayer: violation.toLayer,
+                    importPath: violation.importPath,
+                    file: file.path.relative,
+                    line: violation.line,
+                    message: violation.getMessage(),
+                    suggestion: violation.getSuggestion(),
+                    severity: VIOLATION_SEVERITY_MAP.DEPENDENCY_DIRECTION,
+                })
+            }
+        }
+
+        return violations
+    }
+
+    private detectRepositoryPatternViolations(
+        sourceFiles: SourceFile[],
+    ): RepositoryPatternViolation[] {
+        const violations: RepositoryPatternViolation[] = []
+
+        for (const file of sourceFiles) {
+            const patternViolations = this.repositoryPatternDetector.detectViolations(
+                file.content,
+                file.path.relative,
+                file.layer,
+            )
+
+            for (const violation of patternViolations) {
+                violations.push({
+                    rule: RULES.REPOSITORY_PATTERN,
+                    violationType: violation.violationType as
+                        | typeof REPOSITORY_VIOLATION_TYPES.ORM_TYPE_IN_INTERFACE
+                        | typeof REPOSITORY_VIOLATION_TYPES.CONCRETE_REPOSITORY_IN_USE_CASE
+                        | typeof REPOSITORY_VIOLATION_TYPES.NEW_REPOSITORY_IN_USE_CASE
+                        | typeof REPOSITORY_VIOLATION_TYPES.NON_DOMAIN_METHOD_NAME,
+                    file: file.path.relative,
+                    layer: violation.layer,
+                    line: violation.line,
+                    details: violation.details,
+                    message: violation.getMessage(),
+                    suggestion: violation.getSuggestion(),
+                    severity: VIOLATION_SEVERITY_MAP.REPOSITORY_PATTERN,
+                })
+            }
+        }
+
+        return violations
+    }
+
+    private detectAggregateBoundaryViolations(
+        sourceFiles: SourceFile[],
+    ): AggregateBoundaryViolation[] {
+        const violations: AggregateBoundaryViolation[] = []
+
+        for (const file of sourceFiles) {
+            const boundaryViolations = this.aggregateBoundaryDetector.detectViolations(
+                file.content,
+                file.path.relative,
+                file.layer,
+            )
+
+            for (const violation of boundaryViolations) {
+                violations.push({
+                    rule: RULES.AGGREGATE_BOUNDARY,
+                    fromAggregate: violation.fromAggregate,
+                    toAggregate: violation.toAggregate,
+                    entityName: violation.entityName,
+                    importPath: violation.importPath,
+                    file: file.path.relative,
+                    line: violation.line,
+                    message: violation.getMessage(),
+                    suggestion: violation.getSuggestion(),
+                    severity: VIOLATION_SEVERITY_MAP.AGGREGATE_BOUNDARY,
+                })
+            }
+        }
+
+        return violations
+    }
+
+    private async detectSecrets(sourceFiles: SourceFile[]): Promise<SecretViolation[]> {
+        const violations: SecretViolation[] = []
+
+        for (const file of sourceFiles) {
+            const secretViolations = await this.secretDetector.detectAll(
+                file.content,
+                file.path.relative,
+            )
+
+            for (const secret of secretViolations) {
+                violations.push({
+                    rule: RULES.SECRET_EXPOSURE,
+                    secretType: secret.secretType,
+                    file: file.path.relative,
+                    line: secret.line,
+                    column: secret.column,
+                    message: secret.getMessage(),
+                    suggestion: secret.getSuggestion(),
+                    severity: "critical",
+                })
+            }
+        }
+
+        return violations
+    }
+
+    private detectAnemicModels(sourceFiles: SourceFile[]): AnemicModelViolation[] {
+        const violations: AnemicModelViolation[] = []
+
+        for (const file of sourceFiles) {
+            const anemicModels = this.anemicModelDetector.detectAnemicModels(
+                file.content,
+                file.path.relative,
+                file.layer,
+            )
+
+            for (const anemicModel of anemicModels) {
+                violations.push({
+                    rule: RULES.ANEMIC_MODEL,
+                    className: anemicModel.className,
+                    file: file.path.relative,
+                    layer: anemicModel.layer,
+                    line: anemicModel.line,
+                    methodCount: anemicModel.methodCount,
+                    propertyCount: anemicModel.propertyCount,
+                    hasOnlyGettersSetters: anemicModel.hasOnlyGettersSetters,
+                    hasPublicSetters: anemicModel.hasPublicSetters,
+                    message: anemicModel.getMessage(),
+                    suggestion: anemicModel.getSuggestion(),
+                    severity: VIOLATION_SEVERITY_MAP.ANEMIC_MODEL,
+                })
+            }
+        }
+
+        return violations
+    }
+
+    private sortBySeverity<T extends { severity: SeverityLevel }>(violations: T[]): T[] {
+        return violations.sort((a, b) => {
+            return SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]
+        })
+    }
+}
--- a/packages/guardian/src/application/use-cases/pipeline/ParseSourceFiles.ts
+++ b/packages/guardian/src/application/use-cases/pipeline/ParseSourceFiles.ts
@@ -0,0 +1,51 @@
+import { ICodeParser } from "../../../domain/services/ICodeParser"
+import { SourceFile } from "../../../domain/entities/SourceFile"
+import { DependencyGraph } from "../../../domain/entities/DependencyGraph"
+
+export interface ParsingRequest {
+    sourceFiles: SourceFile[]
+    rootDir: string
+}
+
+export interface ParsingResult {
+    dependencyGraph: DependencyGraph
+    totalFunctions: number
+}
+
+/**
+ * Pipeline step responsible for AST parsing and dependency graph construction
+ */
+export class ParseSourceFiles {
+    constructor(private readonly codeParser: ICodeParser) {}
+
+    public execute(request: ParsingRequest): ParsingResult {
+        const dependencyGraph = new DependencyGraph()
+        let totalFunctions = 0
+
+        for (const sourceFile of request.sourceFiles) {
+            dependencyGraph.addFile(sourceFile)
+
+            if (sourceFile.path.isTypeScript()) {
+                const tree = this.codeParser.parseTypeScript(sourceFile.content)
+                const functions = this.codeParser.extractFunctions(tree)
+                totalFunctions += functions.length
+            }
+
+            for (const imp of sourceFile.imports) {
+                dependencyGraph.addDependency(
+                    sourceFile.path.relative,
+                    this.resolveImportPath(imp, sourceFile.path.relative, request.rootDir),
+                )
+            }
+        }
+
+        return { dependencyGraph, totalFunctions }
+    }
+
+    private resolveImportPath(importPath: string, _currentFile: string, _rootDir: string): string {
+        if (importPath.startsWith(".")) {
+            return importPath
+        }
+        return importPath
+    }
+}
--- a/packages/guardian/src/cli/constants.ts
+++ b/packages/guardian/src/cli/constants.ts
@@ -13,13 +13,43 @@ export const CLI_COMMANDS = {
 } as const

 export const CLI_DESCRIPTIONS = {
-    MAIN: "🛡️  Code quality guardian - detect hardcoded values and architecture violations",
-    CHECK: "Analyze project for code quality issues",
-    PATH_ARG: "Path to analyze",
-    EXCLUDE_OPTION: "Directories to exclude",
-    VERBOSE_OPTION: "Verbose output",
-    NO_HARDCODE_OPTION: "Skip hardcode detection",
-    NO_ARCHITECTURE_OPTION: "Skip architecture checks",
+    MAIN:
+        "🛡️  Guardian - Code quality analyzer for TypeScript/JavaScript projects\n\n" +
+        "DETECTS:\n" +
+        "  • Hardcoded values (magic numbers/strings) - extract to constants\n" +
+        "  • Circular dependencies - refactor module structure\n" +
+        "  • Framework leaks in domain - move framework imports to infrastructure\n" +
+        "  • Naming violations - rename files to match layer conventions\n" +
+        "  • Architecture violations - respect Clean Architecture layers\n" +
+        "  • Entity exposure - use DTOs instead of returning entities\n" +
+        "  • Dependency direction - ensure dependencies flow inward\n" +
+        "  • Repository pattern - enforce repository interfaces in domain\n\n" +
+        "SEVERITY LEVELS:\n" +
+        "  🔴 CRITICAL - Must fix immediately (breaks architecture)\n" +
+        "  🟠 HIGH     - Should fix soon (major quality issue)\n" +
+        "  🟡 MEDIUM   - Should fix (moderate quality issue)\n" +
+        "  🟢 LOW      - Nice to fix (minor quality issue)\n\n" +
+        "BACKED BY RESEARCH:\n" +
+        "  Guardian's rules are based on established software engineering principles\n" +
+        "  from MIT, Martin Fowler, Robert C. Martin, and industry standards.\n" +
+        "  Learn more: https://github.com/samiyev/puaros/blob/main/packages/guardian/docs/WHY.md",
+    CHECK:
+        "Analyze project for code quality and architecture issues\n\n" +
+        "WORKFLOW:\n" +
+        "  1. Run: guardian check ./src\n" +
+        "  2. Review violations by severity\n" +
+        "  3. Read the suggestion for each violation\n" +
+        "  4. Fix violations starting with CRITICAL\n" +
+        "  5. Re-run to verify fixes",
+    PATH_ARG: "Path to analyze (e.g., ./src or ./packages/api)",
+    EXCLUDE_OPTION:
+        "Exclude dirs/patterns (default: node_modules,dist,build,coverage,tests,**/*.test.ts)",
+    VERBOSE_OPTION: "Show additional help and analysis details",
+    NO_HARDCODE_OPTION: "Skip hardcode detection (only check architecture)",
+    NO_ARCHITECTURE_OPTION: "Skip architecture checks (only check hardcodes)",
+    MIN_SEVERITY_OPTION: "Filter by severity: critical|high|medium|low (e.g., --min-severity high)",
+    ONLY_CRITICAL_OPTION: "Show only 🔴 CRITICAL issues (shortcut for --min-severity critical)",
+    LIMIT_OPTION: "Limit violations shown per category (e.g., -l 10 shows first 10)",
 } as const

 export const CLI_OPTIONS = {
@@ -27,13 +57,44 @@ export const CLI_OPTIONS = {
    VERBOSE: "-v, --verbose",
    NO_HARDCODE: "--no-hardcode",
    NO_ARCHITECTURE: "--no-architecture",
+    MIN_SEVERITY: "--min-severity <level>",
+    ONLY_CRITICAL: "--only-critical",
+    LIMIT: "-l, --limit <number>",
+} as const
+
+export const SEVERITY_DISPLAY_LABELS = {
+    CRITICAL: "🔴 CRITICAL",
+    HIGH: "🟠 HIGH",
+    MEDIUM: "🟡 MEDIUM",
+    LOW: "🟢 LOW",
+} as const
+
+export const SEVERITY_SECTION_HEADERS = {
+    CRITICAL:
+        "\n═══════════════════════════════════════════\n🔴 CRITICAL SEVERITY\n═══════════════════════════════════════════",
+    HIGH: "\n═══════════════════════════════════════════\n🟠 HIGH SEVERITY\n═══════════════════════════════════════════",
+    MEDIUM: "\n═══════════════════════════════════════════\n🟡 MEDIUM SEVERITY\n═══════════════════════════════════════════",
+    LOW: "\n═══════════════════════════════════════════\n🟢 LOW SEVERITY\n═══════════════════════════════════════════",
 } as const

 export const CLI_ARGUMENTS = {
    PATH: "<path>",
 } as const

-export const DEFAULT_EXCLUDES = ["node_modules", "dist", "build", "coverage"] as const
+export const DEFAULT_EXCLUDES = [
+    "node_modules",
+    "dist",
+    "build",
+    "coverage",
+    "tests",
+    "test",
+    "__tests__",
+    "examples",
+    "**/*.test.ts",
+    "**/*.test.js",
+    "**/*.spec.ts",
+    "**/*.spec.js",
+] as const

 export const CLI_MESSAGES = {
    ANALYZING: "\n🛡️  Guardian - Analyzing your code...\n",
@@ -61,3 +122,58 @@ export const CLI_LABELS = {
    HARDCODE_VIOLATIONS: "hardcoded values:",
    ISSUES_TOTAL: "issues total",
 } as const
+
+export const CLI_HELP_TEXT = {
+    POSITION: "after",
+    EXAMPLES_HEADER: "\nEXAMPLES:\n",
+    EXAMPLE_BASIC: "  $ guardian check ./src                          # Analyze src directory\n",
+    EXAMPLE_CRITICAL:
+        "  $ guardian check ./src --only-critical          # Show only critical issues\n",
+    EXAMPLE_SEVERITY:
+        "  $ guardian check ./src --min-severity high      # Show high and critical\n",
+    EXAMPLE_LIMIT:
+        "  $ guardian check ./src --limit 10               # Limit output to 10 per category\n",
+    EXAMPLE_NO_HARDCODE:
+        "  $ guardian check ./src --no-hardcode            # Skip hardcode detection\n",
+    EXAMPLE_NO_ARCHITECTURE:
+        "  $ guardian check ./src --no-architecture        # Skip architecture checks\n",
+    EXAMPLE_EXCLUDE:
+        "  $ guardian check ./src -e dist build            # Exclude additional dirs\n\n",
+    FIX_HEADER: "HOW TO FIX COMMON ISSUES:\n",
+    FIX_HARDCODE: "  Hardcoded values    → Extract to constants file\n",
+    FIX_CIRCULAR: "  Circular deps       → Break cycle by extracting shared code\n",
+    FIX_FRAMEWORK: "  Framework leaks     → Move Express/NestJS imports to infrastructure layer\n",
+    FIX_NAMING: "  Naming violations   → Rename file (e.g., UserEntity.ts, CreateUserUseCase.ts)\n",
+    FIX_ENTITY: "  Entity exposure     → Create DTO and map entity to DTO before returning\n",
+    FIX_DEPENDENCY:
+        "  Dependency direction → Move import to correct layer (domain ← app ← infra)\n",
+    FIX_REPOSITORY:
+        "  Repository pattern  → Create IUserRepository in domain, implement in infra\n\n",
+    FOOTER: "Each violation includes a 💡 Suggestion with specific fix instructions.\n",
+    AI_AGENT_HEADER: "AI AGENT INSTRUCTIONS:\n",
+    AI_AGENT_INTRO:
+        "  When an AI coding assistant (Claude, Copilot, Cursor, etc.) uses Guardian:\n\n",
+    AI_AGENT_STEP1: "  STEP 1: Run initial scan\n",
+    AI_AGENT_STEP1_CMD: "    $ guardian check ./src --only-critical --limit 5\n\n",
+    AI_AGENT_STEP2: "  STEP 2: For each violation in output:\n",
+    AI_AGENT_STEP2_DETAIL:
+        "    - Read the file at reported location (file:line:column)\n" +
+        "    - Apply the 💡 Suggestion provided\n" +
+        "    - The suggestion contains exact fix instructions\n\n",
+    AI_AGENT_STEP3: "  STEP 3: After fixing, verify:\n",
+    AI_AGENT_STEP3_CMD: "    $ guardian check ./src --only-critical\n\n",
+    AI_AGENT_STEP4: "  STEP 4: Expand scope progressively:\n",
+    AI_AGENT_STEP4_CMDS:
+        "    $ guardian check ./src --min-severity high    # Fix HIGH issues\n" +
+        "    $ guardian check ./src --min-severity medium  # Fix MEDIUM issues\n" +
+        "    $ guardian check ./src                        # Full scan\n\n",
+    AI_AGENT_OUTPUT: "  OUTPUT FORMAT (parse this):\n",
+    AI_AGENT_OUTPUT_DETAIL:
+        "    <index>. <file>:<line>:<column>\n" +
+        "       Severity: <emoji> <LEVEL>\n" +
+        "       Type: <violation-type>\n" +
+        "       Value: <problematic-value>\n" +
+        "       Context: <code-snippet>\n" +
+        "       💡 Suggestion: <exact-fix-instruction>\n\n",
+    AI_AGENT_PRIORITY: "  PRIORITY ORDER: CRITICAL → HIGH → MEDIUM → LOW\n\n",
+} as const
--- a/packages/guardian/src/cli/formatters/OutputFormatter.ts
+++ b/packages/guardian/src/cli/formatters/OutputFormatter.ts
@@ -0,0 +1,235 @@
+import { SEVERITY_LEVELS, type SeverityLevel } from "../../shared/constants"
+import type {
+    AggregateBoundaryViolation,
+    AnemicModelViolation,
+    ArchitectureViolation,
+    CircularDependencyViolation,
+    DependencyDirectionViolation,
+    EntityExposureViolation,
+    FrameworkLeakViolation,
+    HardcodeViolation,
+    NamingConventionViolation,
+    RepositoryPatternViolation,
+    SecretViolation,
+} from "../../application/use-cases/AnalyzeProject"
+import { SEVERITY_DISPLAY_LABELS, SEVERITY_SECTION_HEADERS } from "../constants"
+import { ViolationGrouper } from "../groupers/ViolationGrouper"
+
+const SEVERITY_LABELS: Record<SeverityLevel, string> = {
+    [SEVERITY_LEVELS.CRITICAL]: SEVERITY_DISPLAY_LABELS.CRITICAL,
+    [SEVERITY_LEVELS.HIGH]: SEVERITY_DISPLAY_LABELS.HIGH,
+    [SEVERITY_LEVELS.MEDIUM]: SEVERITY_DISPLAY_LABELS.MEDIUM,
+    [SEVERITY_LEVELS.LOW]: SEVERITY_DISPLAY_LABELS.LOW,
+}
+
+const SEVERITY_HEADER: Record<SeverityLevel, string> = {
+    [SEVERITY_LEVELS.CRITICAL]: SEVERITY_SECTION_HEADERS.CRITICAL,
+    [SEVERITY_LEVELS.HIGH]: SEVERITY_SECTION_HEADERS.HIGH,
+    [SEVERITY_LEVELS.MEDIUM]: SEVERITY_SECTION_HEADERS.MEDIUM,
+    [SEVERITY_LEVELS.LOW]: SEVERITY_SECTION_HEADERS.LOW,
+}
+
+export class OutputFormatter {
+    private readonly grouper = new ViolationGrouper()
+
+    displayGroupedViolations<T extends { severity: SeverityLevel }>(
+        violations: T[],
+        displayFn: (v: T, index: number) => void,
+        limit?: number,
+    ): void {
+        const grouped = this.grouper.groupBySeverity(violations)
+        const severities: SeverityLevel[] = [
+            SEVERITY_LEVELS.CRITICAL,
+            SEVERITY_LEVELS.HIGH,
+            SEVERITY_LEVELS.MEDIUM,
+            SEVERITY_LEVELS.LOW,
+        ]
+
+        let totalDisplayed = 0
+        const totalAvailable = violations.length
+
+        for (const severity of severities) {
+            const items = grouped.get(severity)
+            if (items && items.length > 0) {
+                console.warn(SEVERITY_HEADER[severity])
+                console.warn(`Found ${String(items.length)} issue(s)\n`)
+
+                const itemsToDisplay =
+                    limit !== undefined ? items.slice(0, limit - totalDisplayed) : items
+                itemsToDisplay.forEach((item, index) => {
+                    displayFn(item, totalDisplayed + index)
+                })
+                totalDisplayed += itemsToDisplay.length
+
+                if (limit !== undefined && totalDisplayed >= limit) {
+                    break
+                }
+            }
+        }
+
+        if (limit !== undefined && totalAvailable > limit) {
+            console.warn(
+                `\n⚠️  Showing first ${String(limit)} of ${String(totalAvailable)} issues (use --limit to adjust)\n`,
+            )
+        }
+    }
+
+    formatArchitectureViolation(v: ArchitectureViolation, index: number): void {
+        console.log(`${String(index + 1)}. ${v.file}`)
+        console.log(`   Severity: ${SEVERITY_LABELS[v.severity]}`)
+        console.log(`   Rule: ${v.rule}`)
+        console.log(`   ${v.message}`)
+        console.log("")
+    }
+
+    formatCircularDependency(cd: CircularDependencyViolation, index: number): void {
+        console.log(`${String(index + 1)}. ${cd.message}`)
+        console.log(`   Severity: ${SEVERITY_LABELS[cd.severity]}`)
+        console.log("   Cycle path:")
+        cd.cycle.forEach((file, i) => {
+            console.log(`     ${String(i + 1)}. ${file}`)
+        })
+        console.log(`     ${String(cd.cycle.length + 1)}. ${cd.cycle[0]} (back to start)`)
+        console.log("")
+    }
+
+    formatNamingViolation(nc: NamingConventionViolation, index: number): void {
+        console.log(`${String(index + 1)}. ${nc.file}`)
+        console.log(`   Severity: ${SEVERITY_LABELS[nc.severity]}`)
+        console.log(`   File: ${nc.fileName}`)
+        console.log(`   Layer: ${nc.layer}`)
+        console.log(`   Type: ${nc.type}`)
+        console.log(`   Message: ${nc.message}`)
+        if (nc.suggestion) {
+            console.log(`   💡 Suggestion: ${nc.suggestion}`)
+        }
+        console.log("")
+    }
+
+    formatFrameworkLeak(fl: FrameworkLeakViolation, index: number): void {
+        console.log(`${String(index + 1)}. ${fl.file}`)
+        console.log(`   Severity: ${SEVERITY_LABELS[fl.severity]}`)
+        console.log(`   Package: ${fl.packageName}`)
+        console.log(`   Category: ${fl.categoryDescription}`)
+        console.log(`   Layer: ${fl.layer}`)
+        console.log(`   Rule: ${fl.rule}`)
+        console.log(`   ${fl.message}`)
+        console.log(`   💡 Suggestion: ${fl.suggestion}`)
+        console.log("")
+    }
+
+    formatEntityExposure(ee: EntityExposureViolation, index: number): void {
+        const location = ee.line ? `${ee.file}:${String(ee.line)}` : ee.file
+        console.log(`${String(index + 1)}. ${location}`)
+        console.log(`   Severity: ${SEVERITY_LABELS[ee.severity]}`)
+        console.log(`   Entity: ${ee.entityName}`)
+        console.log(`   Return Type: ${ee.returnType}`)
+        if (ee.methodName) {
+            console.log(`   Method: ${ee.methodName}`)
+        }
+        console.log(`   Layer: ${ee.layer}`)
+        console.log(`   Rule: ${ee.rule}`)
+        console.log(`   ${ee.message}`)
+        console.log("   💡 Suggestion:")
+        ee.suggestion.split("\n").forEach((line) => {
+            if (line.trim()) {
+                console.log(`      ${line}`)
+            }
+        })
+        console.log("")
+    }
+
+    formatDependencyDirection(dd: DependencyDirectionViolation, index: number): void {
+        console.log(`${String(index + 1)}. ${dd.file}`)
+        console.log(`   Severity: ${SEVERITY_LABELS[dd.severity]}`)
+        console.log(`   From Layer: ${dd.fromLayer}`)
+        console.log(`   To Layer: ${dd.toLayer}`)
+        console.log(`   Import: ${dd.importPath}`)
+        console.log(`   ${dd.message}`)
+        console.log(`   💡 Suggestion: ${dd.suggestion}`)
+        console.log("")
+    }
+
+    formatRepositoryPattern(rp: RepositoryPatternViolation, index: number): void {
+        console.log(`${String(index + 1)}. ${rp.file}`)
+        console.log(`   Severity: ${SEVERITY_LABELS[rp.severity]}`)
+        console.log(`   Layer: ${rp.layer}`)
+        console.log(`   Type: ${rp.violationType}`)
+        console.log(`   Details: ${rp.details}`)
+        console.log(`   ${rp.message}`)
+        console.log(`   💡 Suggestion: ${rp.suggestion}`)
+        console.log("")
+    }
+
+    formatAggregateBoundary(ab: AggregateBoundaryViolation, index: number): void {
+        const location = ab.line ? `${ab.file}:${String(ab.line)}` : ab.file
+        console.log(`${String(index + 1)}. ${location}`)
+        console.log(`   Severity: ${SEVERITY_LABELS[ab.severity]}`)
+        console.log(`   From Aggregate: ${ab.fromAggregate}`)
+        console.log(`   To Aggregate: ${ab.toAggregate}`)
+        console.log(`   Entity: ${ab.entityName}`)
+        console.log(`   Import: ${ab.importPath}`)
+        console.log(`   ${ab.message}`)
+        console.log("   💡 Suggestion:")
+        ab.suggestion.split("\n").forEach((line) => {
+            if (line.trim()) {
+                console.log(`      ${line}`)
+            }
+        })
+        console.log("")
+    }
+
+    formatSecretViolation(sv: SecretViolation, index: number): void {
+        const location = `${sv.file}:${String(sv.line)}:${String(sv.column)}`
+        console.log(`${String(index + 1)}. ${location}`)
+        console.log(`   Severity: ${SEVERITY_LABELS[sv.severity]} ⚠️`)
+        console.log(`   Secret Type: ${sv.secretType}`)
+        console.log(`   ${sv.message}`)
+        console.log("   🔐 CRITICAL: Rotate this secret immediately!")
+        console.log("   💡 Suggestion:")
+        sv.suggestion.split("\n").forEach((line) => {
+            if (line.trim()) {
+                console.log(`      ${line}`)
+            }
+        })
+        console.log("")
+    }
+
+    formatHardcodeViolation(hc: HardcodeViolation, index: number): void {
+        console.log(`${String(index + 1)}. ${hc.file}:${String(hc.line)}:${String(hc.column)}`)
+        console.log(`   Severity: ${SEVERITY_LABELS[hc.severity]}`)
+        console.log(`   Type: ${hc.type}`)
+        console.log(`   Value: ${JSON.stringify(hc.value)}`)
+        console.log(`   Context: ${hc.context.trim()}`)
+        console.log(`   💡 Suggested: ${hc.suggestion.constantName}`)
+        console.log(`   📁 Location: ${hc.suggestion.location}`)
+        console.log("")
+    }
+
+    formatAnemicModelViolation(am: AnemicModelViolation, index: number): void {
+        const location = am.line ? `${am.file}:${String(am.line)}` : am.file
+        console.log(`${String(index + 1)}. ${location}`)
+        console.log(`   Severity: ${SEVERITY_LABELS[am.severity]}`)
+        console.log(`   Class: ${am.className}`)
+        console.log(`   Layer: ${am.layer}`)
+        console.log(
+            `   Methods: ${String(am.methodCount)} | Properties: ${String(am.propertyCount)}`,
+        )
+
+        if (am.hasPublicSetters) {
+            console.log("   ⚠️  Has public setters (DDD anti-pattern)")
+        }
+        if (am.hasOnlyGettersSetters) {
+            console.log("   ⚠️  Only getters/setters (no business logic)")
+        }
+
+        console.log(`   ${am.message}`)
+        console.log("   💡 Suggestion:")
+        am.suggestion.split("\n").forEach((line) => {
+            if (line.trim()) {
+                console.log(`      ${line}`)
+            }
+        })
+        console.log("")
+    }
+}
--- a/packages/guardian/src/cli/formatters/StatisticsFormatter.ts
+++ b/packages/guardian/src/cli/formatters/StatisticsFormatter.ts
@@ -0,0 +1,59 @@
+import { CLI_LABELS, CLI_MESSAGES } from "../constants"
+
+interface ProjectMetrics {
+    totalFiles: number
+    totalFunctions: number
+    totalImports: number
+    layerDistribution: Record<string, number>
+}
+
+export class StatisticsFormatter {
+    displayMetrics(metrics: ProjectMetrics): void {
+        console.log(CLI_MESSAGES.METRICS_HEADER)
+        console.log(`   ${CLI_LABELS.FILES_ANALYZED} ${String(metrics.totalFiles)}`)
+        console.log(`   ${CLI_LABELS.TOTAL_FUNCTIONS} ${String(metrics.totalFunctions)}`)
+        console.log(`   ${CLI_LABELS.TOTAL_IMPORTS} ${String(metrics.totalImports)}`)
+
+        if (Object.keys(metrics.layerDistribution).length > 0) {
+            console.log(CLI_MESSAGES.LAYER_DISTRIBUTION_HEADER)
+            for (const [layer, count] of Object.entries(metrics.layerDistribution)) {
+                console.log(`   ${layer}: ${String(count)} ${CLI_LABELS.FILES}`)
+            }
+        }
+    }
+
+    displaySummary(totalIssues: number, verbose: boolean): void {
+        if (totalIssues === 0) {
+            console.log(CLI_MESSAGES.NO_ISSUES)
+            process.exit(0)
+        } else {
+            console.log(
+                `${CLI_MESSAGES.ISSUES_TOTAL} ${String(totalIssues)} ${CLI_LABELS.ISSUES_TOTAL}`,
+            )
+            console.log(CLI_MESSAGES.TIP)
+
+            if (verbose) {
+                console.log(CLI_MESSAGES.HELP_FOOTER)
+            }
+
+            process.exit(1)
+        }
+    }
+
+    displaySeverityFilterMessage(onlyCritical: boolean, minSeverity?: string): void {
+        if (onlyCritical) {
+            console.log("\n🔴 Filtering: Showing only CRITICAL severity issues\n")
+        } else if (minSeverity) {
+            console.log(
+                `\n⚠️  Filtering: Showing ${minSeverity.toUpperCase()} severity and above\n`,
+            )
+        }
+    }
+
+    displayError(message: string): void {
+        console.error(`\n❌ ${CLI_MESSAGES.ERROR_PREFIX}`)
+        console.error(message)
+        console.error("")
+        process.exit(1)
+    }
+}
--- a/packages/guardian/src/cli/groupers/ViolationGrouper.ts
+++ b/packages/guardian/src/cli/groupers/ViolationGrouper.ts
@@ -0,0 +1,29 @@
+import { SEVERITY_ORDER, type SeverityLevel } from "../../shared/constants"
+
+export class ViolationGrouper {
+    groupBySeverity<T extends { severity: SeverityLevel }>(
+        violations: T[],
+    ): Map<SeverityLevel, T[]> {
+        const grouped = new Map<SeverityLevel, T[]>()
+
+        for (const violation of violations) {
+            const existing = grouped.get(violation.severity) ?? []
+            existing.push(violation)
+            grouped.set(violation.severity, existing)
+        }
+
+        return grouped
+    }
+
+    filterBySeverity<T extends { severity: SeverityLevel }>(
+        violations: T[],
+        minSeverity?: SeverityLevel,
+    ): T[] {
+        if (!minSeverity) {
+            return violations
+        }
+
+        const minSeverityOrder = SEVERITY_ORDER[minSeverity]
+        return violations.filter((v) => SEVERITY_ORDER[v.severity] <= minSeverityOrder)
+    }
+}
--- a/packages/guardian/src/cli/index.ts
+++ b/packages/guardian/src/cli/index.ts
@@ -6,15 +6,56 @@ import {
    CLI_ARGUMENTS,
    CLI_COMMANDS,
    CLI_DESCRIPTIONS,
+    CLI_HELP_TEXT,
    CLI_LABELS,
    CLI_MESSAGES,
    CLI_OPTIONS,
    DEFAULT_EXCLUDES,
 } from "./constants"
+import { SEVERITY_LEVELS, type SeverityLevel } from "../shared/constants"
+import { ViolationGrouper } from "./groupers/ViolationGrouper"
+import { OutputFormatter } from "./formatters/OutputFormatter"
+import { StatisticsFormatter } from "./formatters/StatisticsFormatter"

 const program = new Command()

-program.name(CLI_COMMANDS.NAME).description(CLI_DESCRIPTIONS.MAIN).version(version)
+program
+    .name(CLI_COMMANDS.NAME)
+    .description(CLI_DESCRIPTIONS.MAIN)
+    .version(version)
+    .addHelpText(
+        CLI_HELP_TEXT.POSITION,
+        CLI_HELP_TEXT.EXAMPLES_HEADER +
+            CLI_HELP_TEXT.EXAMPLE_BASIC +
+            CLI_HELP_TEXT.EXAMPLE_CRITICAL +
+            CLI_HELP_TEXT.EXAMPLE_SEVERITY +
+            CLI_HELP_TEXT.EXAMPLE_LIMIT +
+            CLI_HELP_TEXT.EXAMPLE_NO_HARDCODE +
+            CLI_HELP_TEXT.EXAMPLE_NO_ARCHITECTURE +
+            CLI_HELP_TEXT.EXAMPLE_EXCLUDE +
+            CLI_HELP_TEXT.FIX_HEADER +
+            CLI_HELP_TEXT.FIX_HARDCODE +
+            CLI_HELP_TEXT.FIX_CIRCULAR +
+            CLI_HELP_TEXT.FIX_FRAMEWORK +
+            CLI_HELP_TEXT.FIX_NAMING +
+            CLI_HELP_TEXT.FIX_ENTITY +
+            CLI_HELP_TEXT.FIX_DEPENDENCY +
+            CLI_HELP_TEXT.FIX_REPOSITORY +
+            CLI_HELP_TEXT.FOOTER +
+            CLI_HELP_TEXT.AI_AGENT_HEADER +
+            CLI_HELP_TEXT.AI_AGENT_INTRO +
+            CLI_HELP_TEXT.AI_AGENT_STEP1 +
+            CLI_HELP_TEXT.AI_AGENT_STEP1_CMD +
+            CLI_HELP_TEXT.AI_AGENT_STEP2 +
+            CLI_HELP_TEXT.AI_AGENT_STEP2_DETAIL +
+            CLI_HELP_TEXT.AI_AGENT_STEP3 +
+            CLI_HELP_TEXT.AI_AGENT_STEP3_CMD +
+            CLI_HELP_TEXT.AI_AGENT_STEP4 +
+            CLI_HELP_TEXT.AI_AGENT_STEP4_CMDS +
+            CLI_HELP_TEXT.AI_AGENT_OUTPUT +
+            CLI_HELP_TEXT.AI_AGENT_OUTPUT_DETAIL +
+            CLI_HELP_TEXT.AI_AGENT_PRIORITY,
+    )

 program
    .command(CLI_COMMANDS.CHECK)
@@ -24,7 +65,14 @@ program
    .option(CLI_OPTIONS.VERBOSE, CLI_DESCRIPTIONS.VERBOSE_OPTION, false)
    .option(CLI_OPTIONS.NO_HARDCODE, CLI_DESCRIPTIONS.NO_HARDCODE_OPTION)
    .option(CLI_OPTIONS.NO_ARCHITECTURE, CLI_DESCRIPTIONS.NO_ARCHITECTURE_OPTION)
+    .option(CLI_OPTIONS.MIN_SEVERITY, CLI_DESCRIPTIONS.MIN_SEVERITY_OPTION)
+    .option(CLI_OPTIONS.ONLY_CRITICAL, CLI_DESCRIPTIONS.ONLY_CRITICAL_OPTION, false)
+    .option(CLI_OPTIONS.LIMIT, CLI_DESCRIPTIONS.LIMIT_OPTION)
    .action(async (path: string, options) => {
+        const grouper = new ViolationGrouper()
+        const outputFormatter = new OutputFormatter()
+        const statsFormatter = new StatisticsFormatter()
+
        try {
            console.log(CLI_MESSAGES.ANALYZING)

@@ -33,146 +81,229 @@ program
                exclude: options.exclude,
            })

-            const {
+            const { metrics } = result
+            let {
                hardcodeViolations,
                violations,
                circularDependencyViolations,
                namingViolations,
                frameworkLeakViolations,
-                metrics,
+                entityExposureViolations,
+                dependencyDirectionViolations,
+                repositoryPatternViolations,
+                aggregateBoundaryViolations,
+                secretViolations,
+                anemicModelViolations,
            } = result

-            // Display metrics
-            console.log(CLI_MESSAGES.METRICS_HEADER)
-            console.log(`   ${CLI_LABELS.FILES_ANALYZED} ${String(metrics.totalFiles)}`)
-            console.log(`   ${CLI_LABELS.TOTAL_FUNCTIONS} ${String(metrics.totalFunctions)}`)
-            console.log(`   ${CLI_LABELS.TOTAL_IMPORTS} ${String(metrics.totalImports)}`)
+            const minSeverity: SeverityLevel | undefined = options.onlyCritical
+                ? SEVERITY_LEVELS.CRITICAL
+                : options.minSeverity
+                  ? (options.minSeverity.toLowerCase() as SeverityLevel)
+                  : undefined

-            if (Object.keys(metrics.layerDistribution).length > 0) {
-                console.log(CLI_MESSAGES.LAYER_DISTRIBUTION_HEADER)
-                for (const [layer, count] of Object.entries(metrics.layerDistribution)) {
-                    console.log(`   ${layer}: ${String(count)} ${CLI_LABELS.FILES}`)
-                }
+            const limit: number | undefined = options.limit
+                ? parseInt(options.limit, 10)
+                : undefined
+
+            if (minSeverity) {
+                violations = grouper.filterBySeverity(violations, minSeverity)
+                hardcodeViolations = grouper.filterBySeverity(hardcodeViolations, minSeverity)
+                circularDependencyViolations = grouper.filterBySeverity(
+                    circularDependencyViolations,
+                    minSeverity,
+                )
+                namingViolations = grouper.filterBySeverity(namingViolations, minSeverity)
+                frameworkLeakViolations = grouper.filterBySeverity(
+                    frameworkLeakViolations,
+                    minSeverity,
+                )
+                entityExposureViolations = grouper.filterBySeverity(
+                    entityExposureViolations,
+                    minSeverity,
+                )
+                dependencyDirectionViolations = grouper.filterBySeverity(
+                    dependencyDirectionViolations,
+                    minSeverity,
+                )
+                repositoryPatternViolations = grouper.filterBySeverity(
+                    repositoryPatternViolations,
+                    minSeverity,
+                )
+                aggregateBoundaryViolations = grouper.filterBySeverity(
+                    aggregateBoundaryViolations,
+                    minSeverity,
+                )
+                secretViolations = grouper.filterBySeverity(secretViolations, minSeverity)
+                anemicModelViolations = grouper.filterBySeverity(anemicModelViolations, minSeverity)
+
+                statsFormatter.displaySeverityFilterMessage(
+                    options.onlyCritical,
+                    options.minSeverity,
+                )
            }

-            // Architecture violations
+            statsFormatter.displayMetrics(metrics)
+
            if (options.architecture && violations.length > 0) {
                console.log(
-                    `${CLI_MESSAGES.VIOLATIONS_HEADER} ${String(violations.length)} ${CLI_LABELS.ARCHITECTURE_VIOLATIONS}\n`,
+                    `\n${CLI_MESSAGES.VIOLATIONS_HEADER} ${String(violations.length)} ${CLI_LABELS.ARCHITECTURE_VIOLATIONS}`,
+                )
+                outputFormatter.displayGroupedViolations(
+                    violations,
+                    (v, i) => {
+                        outputFormatter.formatArchitectureViolation(v, i)
+                    },
+                    limit,
                )
-
-                violations.forEach((v, index) => {
-                    console.log(`${String(index + 1)}. ${v.file}`)
-                    console.log(`   Rule: ${v.rule}`)
-                    console.log(`   ${v.message}`)
-                    console.log("")
-                })
            }

-            // Circular dependency violations
            if (options.architecture && circularDependencyViolations.length > 0) {
                console.log(
-                    `${CLI_MESSAGES.CIRCULAR_DEPS_HEADER} ${String(circularDependencyViolations.length)} ${CLI_LABELS.CIRCULAR_DEPENDENCIES}\n`,
+                    `\n${CLI_MESSAGES.CIRCULAR_DEPS_HEADER} ${String(circularDependencyViolations.length)} ${CLI_LABELS.CIRCULAR_DEPENDENCIES}`,
+                )
+                outputFormatter.displayGroupedViolations(
+                    circularDependencyViolations,
+                    (cd, i) => {
+                        outputFormatter.formatCircularDependency(cd, i)
+                    },
+                    limit,
                )
-
-                circularDependencyViolations.forEach((cd, index) => {
-                    console.log(`${String(index + 1)}. ${cd.message}`)
-                    console.log(`   Severity: ${cd.severity}`)
-                    console.log("   Cycle path:")
-                    cd.cycle.forEach((file, i) => {
-                        console.log(`     ${String(i + 1)}. ${file}`)
-                    })
-                    console.log(
-                        `     ${String(cd.cycle.length + 1)}. ${cd.cycle[0]} (back to start)`,
-                    )
-                    console.log("")
-                })
            }

-            // Naming convention violations
            if (options.architecture && namingViolations.length > 0) {
                console.log(
-                    `${CLI_MESSAGES.NAMING_VIOLATIONS_HEADER} ${String(namingViolations.length)} ${CLI_LABELS.NAMING_VIOLATIONS}\n`,
+                    `\n${CLI_MESSAGES.NAMING_VIOLATIONS_HEADER} ${String(namingViolations.length)} ${CLI_LABELS.NAMING_VIOLATIONS}`,
+                )
+                outputFormatter.displayGroupedViolations(
+                    namingViolations,
+                    (nc, i) => {
+                        outputFormatter.formatNamingViolation(nc, i)
+                    },
+                    limit,
                )
-
-                namingViolations.forEach((nc, index) => {
-                    console.log(`${String(index + 1)}. ${nc.file}`)
-                    console.log(`   File: ${nc.fileName}`)
-                    console.log(`   Layer: ${nc.layer}`)
-                    console.log(`   Type: ${nc.type}`)
-                    console.log(`   Message: ${nc.message}`)
-                    if (nc.suggestion) {
-                        console.log(`   💡 Suggestion: ${nc.suggestion}`)
-                    }
-                    console.log("")
-                })
            }

-            // Framework leak violations
            if (options.architecture && frameworkLeakViolations.length > 0) {
                console.log(
-                    `\n🏗️ Found ${String(frameworkLeakViolations.length)} framework leak(s):\n`,
+                    `\n🏗️ Found ${String(frameworkLeakViolations.length)} framework leak(s)`,
+                )
+                outputFormatter.displayGroupedViolations(
+                    frameworkLeakViolations,
+                    (fl, i) => {
+                        outputFormatter.formatFrameworkLeak(fl, i)
+                    },
+                    limit,
+                )
+            }
+
+            if (options.architecture && entityExposureViolations.length > 0) {
+                console.log(
+                    `\n🎭 Found ${String(entityExposureViolations.length)} entity exposure(s)`,
+                )
+                outputFormatter.displayGroupedViolations(
+                    entityExposureViolations,
+                    (ee, i) => {
+                        outputFormatter.formatEntityExposure(ee, i)
+                    },
+                    limit,
+                )
+            }
+
+            if (options.architecture && dependencyDirectionViolations.length > 0) {
+                console.log(
+                    `\n⚠️ Found ${String(dependencyDirectionViolations.length)} dependency direction violation(s)`,
+                )
+                outputFormatter.displayGroupedViolations(
+                    dependencyDirectionViolations,
+                    (dd, i) => {
+                        outputFormatter.formatDependencyDirection(dd, i)
+                    },
+                    limit,
+                )
+            }
+
+            if (options.architecture && repositoryPatternViolations.length > 0) {
+                console.log(
+                    `\n📦 Found ${String(repositoryPatternViolations.length)} repository pattern violation(s)`,
+                )
+                outputFormatter.displayGroupedViolations(
+                    repositoryPatternViolations,
+                    (rp, i) => {
+                        outputFormatter.formatRepositoryPattern(rp, i)
+                    },
+                    limit,
+                )
+            }
+
+            if (options.architecture && aggregateBoundaryViolations.length > 0) {
+                console.log(
+                    `\n🔒 Found ${String(aggregateBoundaryViolations.length)} aggregate boundary violation(s)`,
+                )
+                outputFormatter.displayGroupedViolations(
+                    aggregateBoundaryViolations,
+                    (ab, i) => {
+                        outputFormatter.formatAggregateBoundary(ab, i)
+                    },
+                    limit,
+                )
+            }
+
+            if (secretViolations.length > 0) {
+                console.log(
+                    `\n🔐 Found ${String(secretViolations.length)} hardcoded secret(s) - CRITICAL SECURITY RISK`,
+                )
+                outputFormatter.displayGroupedViolations(
+                    secretViolations,
+                    (sv, i) => {
+                        outputFormatter.formatSecretViolation(sv, i)
+                    },
+                    limit,
+                )
+            }
+
+            if (anemicModelViolations.length > 0) {
+                console.log(
+                    `\n🩺 Found ${String(anemicModelViolations.length)} anemic domain model(s)`,
+                )
+                outputFormatter.displayGroupedViolations(
+                    anemicModelViolations,
+                    (am, i) => {
+                        outputFormatter.formatAnemicModelViolation(am, i)
+                    },
+                    limit,
                )
-
-                frameworkLeakViolations.forEach((fl, index) => {
-                    console.log(`${String(index + 1)}. ${fl.file}`)
-                    console.log(`   Package: ${fl.packageName}`)
-                    console.log(`   Category: ${fl.categoryDescription}`)
-                    console.log(`   Layer: ${fl.layer}`)
-                    console.log(`   Rule: ${fl.rule}`)
-                    console.log(`   ${fl.message}`)
-                    console.log(`   💡 Suggestion: ${fl.suggestion}`)
-                    console.log("")
-                })
            }

-            // Hardcode violations
            if (options.hardcode && hardcodeViolations.length > 0) {
                console.log(
-                    `${CLI_MESSAGES.HARDCODE_VIOLATIONS_HEADER} ${String(hardcodeViolations.length)} ${CLI_LABELS.HARDCODE_VIOLATIONS}\n`,
+                    `\n${CLI_MESSAGES.HARDCODE_VIOLATIONS_HEADER} ${String(hardcodeViolations.length)} ${CLI_LABELS.HARDCODE_VIOLATIONS}`,
+                )
+                outputFormatter.displayGroupedViolations(
+                    hardcodeViolations,
+                    (hc, i) => {
+                        outputFormatter.formatHardcodeViolation(hc, i)
+                    },
+                    limit,
                )
-
-                hardcodeViolations.forEach((hc, index) => {
-                    console.log(
-                        `${String(index + 1)}. ${hc.file}:${String(hc.line)}:${String(hc.column)}`,
-                    )
-                    console.log(`   Type: ${hc.type}`)
-                    console.log(`   Value: ${JSON.stringify(hc.value)}`)
-                    console.log(`   Context: ${hc.context.trim()}`)
-                    console.log(`   💡 Suggested: ${hc.suggestion.constantName}`)
-                    console.log(`   📁 Location: ${hc.suggestion.location}`)
-                    console.log("")
-                })
            }

-            // Summary
            const totalIssues =
                violations.length +
                hardcodeViolations.length +
                circularDependencyViolations.length +
                namingViolations.length +
-                frameworkLeakViolations.length
+                frameworkLeakViolations.length +
+                entityExposureViolations.length +
+                dependencyDirectionViolations.length +
+                repositoryPatternViolations.length +
+                aggregateBoundaryViolations.length +
+                secretViolations.length +
+                anemicModelViolations.length

-            if (totalIssues === 0) {
-                console.log(CLI_MESSAGES.NO_ISSUES)
-                process.exit(0)
-            } else {
-                console.log(
-                    `${CLI_MESSAGES.ISSUES_TOTAL} ${String(totalIssues)} ${CLI_LABELS.ISSUES_TOTAL}`,
-                )
-                console.log(CLI_MESSAGES.TIP)
-
-                if (options.verbose) {
-                    console.log(CLI_MESSAGES.HELP_FOOTER)
-                }
-
-                process.exit(1)
-            }
+            statsFormatter.displaySummary(totalIssues, options.verbose)
        } catch (error) {
-            console.error(`\n❌ ${CLI_MESSAGES.ERROR_PREFIX}`)
-            console.error(error instanceof Error ? error.message : String(error))
-            console.error("")
-            process.exit(1)
+            statsFormatter.displayError(error instanceof Error ? error.message : String(error))
        }
    })

--- a/packages/guardian/src/domain/constants/FrameworkCategories.ts
+++ b/packages/guardian/src/domain/constants/FrameworkCategories.ts
@@ -0,0 +1,31 @@
+export const FRAMEWORK_CATEGORY_NAMES = {
+    ORM: "ORM",
+    WEB_FRAMEWORK: "WEB_FRAMEWORK",
+    HTTP_CLIENT: "HTTP_CLIENT",
+    VALIDATION: "VALIDATION",
+    DI_CONTAINER: "DI_CONTAINER",
+    LOGGER: "LOGGER",
+    CACHE: "CACHE",
+    MESSAGE_QUEUE: "MESSAGE_QUEUE",
+    EMAIL: "EMAIL",
+    STORAGE: "STORAGE",
+    TESTING: "TESTING",
+    TEMPLATE_ENGINE: "TEMPLATE_ENGINE",
+} as const
+
+export const FRAMEWORK_CATEGORY_DESCRIPTIONS = {
+    [FRAMEWORK_CATEGORY_NAMES.ORM]: "Database ORM/ODM",
+    [FRAMEWORK_CATEGORY_NAMES.WEB_FRAMEWORK]: "Web Framework",
+    [FRAMEWORK_CATEGORY_NAMES.HTTP_CLIENT]: "HTTP Client",
+    [FRAMEWORK_CATEGORY_NAMES.VALIDATION]: "Validation Library",
+    [FRAMEWORK_CATEGORY_NAMES.DI_CONTAINER]: "DI Container",
+    [FRAMEWORK_CATEGORY_NAMES.LOGGER]: "Logger",
+    [FRAMEWORK_CATEGORY_NAMES.CACHE]: "Cache",
+    [FRAMEWORK_CATEGORY_NAMES.MESSAGE_QUEUE]: "Message Queue",
+    [FRAMEWORK_CATEGORY_NAMES.EMAIL]: "Email Service",
+    [FRAMEWORK_CATEGORY_NAMES.STORAGE]: "Storage Service",
+    [FRAMEWORK_CATEGORY_NAMES.TESTING]: "Testing Framework",
+    [FRAMEWORK_CATEGORY_NAMES.TEMPLATE_ENGINE]: "Template Engine",
+} as const
+
+export const DEFAULT_FRAMEWORK_CATEGORY_DESCRIPTION = "Framework Package"
--- a/packages/guardian/src/domain/constants/Messages.ts
+++ b/packages/guardian/src/domain/constants/Messages.ts
@@ -0,0 +1,91 @@
+export const DEPENDENCY_VIOLATION_MESSAGES = {
+    DOMAIN_INDEPENDENCE: "Domain layer should be independent and not depend on other layers",
+    DOMAIN_MOVE_TO_DOMAIN:
+        "Move the imported code to the domain layer if it contains business logic",
+    DOMAIN_USE_DI:
+        "Use dependency inversion: define an interface in domain and implement it in infrastructure",
+    APPLICATION_NO_INFRA: "Application layer should not depend on infrastructure",
+    APPLICATION_DEFINE_PORT: "Define an interface (Port) in application layer",
+    APPLICATION_IMPLEMENT_ADAPTER: "Implement the interface (Adapter) in infrastructure layer",
+    APPLICATION_USE_DI: "Use dependency injection to provide the implementation",
+}
+
+export const ENTITY_EXPOSURE_MESSAGES = {
+    METHOD_DEFAULT: "Method",
+    METHOD_DEFAULT_NAME: "getEntity",
+}
+
+export const FRAMEWORK_LEAK_MESSAGES = {
+    DEFAULT_MESSAGE: "Domain layer should not depend on external frameworks",
+}
+
+export const REPOSITORY_PATTERN_MESSAGES = {
+    UNKNOWN_TYPE: "Unknown",
+    CONSTRUCTOR: "constructor",
+    DEFAULT_SUGGESTION: "Follow Repository Pattern best practices",
+    NO_EXAMPLE: "// No example available",
+    STEP_REMOVE_ORM_TYPES: "1. Remove ORM-specific types from repository interface",
+    STEP_USE_DOMAIN_TYPES: "2. Use domain types (entities, value objects) instead",
+    STEP_KEEP_CLEAN: "3. Keep repository interface clean and persistence-agnostic",
+    STEP_DEPEND_ON_INTERFACE: "1. Depend on repository interface (IUserRepository) in constructor",
+    STEP_MOVE_TO_INFRASTRUCTURE: "2. Move concrete implementation to infrastructure layer",
+    STEP_USE_DI: "3. Use dependency injection to provide implementation",
+    STEP_REMOVE_NEW: "1. Remove 'new Repository()' from use case",
+    STEP_INJECT_CONSTRUCTOR: "2. Inject repository through constructor",
+    STEP_CONFIGURE_DI: "3. Configure dependency injection container",
+    STEP_RENAME_METHOD: "1. Rename method to use domain language",
+    STEP_REFLECT_BUSINESS: "2. Method names should reflect business operations",
+    STEP_AVOID_TECHNICAL: "3. Avoid technical database terms (query, insert, select)",
+    EXAMPLE_PREFIX: "Example:",
+    BAD_ORM_EXAMPLE: "❌ Bad: findOne(query: Prisma.UserWhereInput)",
+    GOOD_DOMAIN_EXAMPLE: "✅ Good: findById(id: UserId): Promise<User | null>",
+    BAD_NEW_REPO: "❌ Bad: const repo = new UserRepository()",
+    GOOD_INJECT_REPO: "✅ Good: constructor(private readonly userRepo: IUserRepository) {}",
+    SUGGESTION_FINDONE: "findById",
+    SUGGESTION_FINDMANY: "findAll or findByFilter",
+    SUGGESTION_INSERT: "save or create",
+    SUGGESTION_UPDATE: "save",
+    SUGGESTION_DELETE: "remove or delete",
+    SUGGESTION_QUERY: "find or search",
+}
+
+export const REPOSITORY_FALLBACK_SUGGESTIONS = {
+    DEFAULT: "findById() or findByEmail()",
+}
+
+export const AGGREGATE_VIOLATION_MESSAGES = {
+    USE_ID_REFERENCE: "1. Reference other aggregates by ID (UserId, OrderId) instead of entity",
+    USE_VALUE_OBJECT:
+        "2. Use Value Objects to store needed data from other aggregates (CustomerInfo, ProductSummary)",
+    AVOID_DIRECT_REFERENCE: "3. Avoid direct entity references to maintain aggregate independence",
+    MAINTAIN_INDEPENDENCE: "4. Each aggregate should be independently modifiable and deployable",
+}
+
+export const SECRET_VIOLATION_MESSAGES = {
+    USE_ENV_VARIABLES: "1. Use environment variables for sensitive data (process.env.API_KEY)",
+    USE_SECRET_MANAGER:
+        "2. Use secret management services (AWS Secrets Manager, HashiCorp Vault, etc.)",
+    NEVER_COMMIT_SECRETS: "3. Never commit secrets to version control",
+    ROTATE_IF_EXPOSED: "4. If secret was committed, rotate it immediately",
+    USE_GITIGNORE: "5. Add secret files to .gitignore (.env, credentials.json, etc.)",
+}
+
+export const ANEMIC_MODEL_MESSAGES = {
+    REMOVE_PUBLIC_SETTERS: "1. Remove public setters - they allow uncontrolled state changes",
+    USE_METHODS_FOR_CHANGES: "2. Use business methods instead (approve(), cancel(), addItem())",
+    ENCAPSULATE_INVARIANTS: "3. Encapsulate business rules and invariants in methods",
+    ADD_BUSINESS_METHODS: "1. Add business logic methods to the entity",
+    MOVE_LOGIC_FROM_SERVICES:
+        "2. Move business logic from services to domain entities where it belongs",
+    ENCAPSULATE_BUSINESS_RULES: "3. Encapsulate business rules inside entity methods",
+    USE_DOMAIN_EVENTS: "4. Use domain events to communicate state changes",
+}
+
+/**
+ * Example values used in violation messages
+ */
+export const VIOLATION_EXAMPLE_VALUES = {
+    UNKNOWN: "unknown",
+    USER_REPOSITORY: "UserRepository",
+    FIND_ONE: "findOne",
+}
--- a/packages/guardian/src/domain/constants/SecretExamples.ts
+++ b/packages/guardian/src/domain/constants/SecretExamples.ts
@@ -0,0 +1,79 @@
+/**
+ * Secret detection constants
+ * All hardcoded strings related to secret detection and examples
+ */
+
+export const SECRET_KEYWORDS = {
+    AWS: "aws",
+    GITHUB: "github",
+    NPM: "npm",
+    SSH: "ssh",
+    PRIVATE_KEY: "private key",
+    SLACK: "slack",
+    API_KEY: "api key",
+    APIKEY: "apikey",
+    ACCESS_KEY: "access key",
+    SECRET: "secret",
+    TOKEN: "token",
+    PASSWORD: "password",
+    USER: "user",
+    BOT: "bot",
+    RSA: "rsa",
+    DSA: "dsa",
+    ECDSA: "ecdsa",
+    ED25519: "ed25519",
+    BASICAUTH: "basicauth",
+    GCP: "gcp",
+    GOOGLE: "google",
+    PRIVATEKEY: "privatekey",
+    PERSONAL_ACCESS_TOKEN: "personal access token",
+    OAUTH: "oauth",
+} as const
+
+export const SECRET_TYPE_NAMES = {
+    AWS_ACCESS_KEY: "AWS Access Key",
+    AWS_SECRET_KEY: "AWS Secret Key",
+    AWS_CREDENTIAL: "AWS Credential",
+    GITHUB_PERSONAL_ACCESS_TOKEN: "GitHub Personal Access Token",
+    GITHUB_OAUTH_TOKEN: "GitHub OAuth Token",
+    GITHUB_TOKEN: "GitHub Token",
+    NPM_TOKEN: "NPM Token",
+    GCP_SERVICE_ACCOUNT_KEY: "GCP Service Account Key",
+    SSH_RSA_PRIVATE_KEY: "SSH RSA Private Key",
+    SSH_DSA_PRIVATE_KEY: "SSH DSA Private Key",
+    SSH_ECDSA_PRIVATE_KEY: "SSH ECDSA Private Key",
+    SSH_ED25519_PRIVATE_KEY: "SSH Ed25519 Private Key",
+    SSH_PRIVATE_KEY: "SSH Private Key",
+    SLACK_BOT_TOKEN: "Slack Bot Token",
+    SLACK_USER_TOKEN: "Slack User Token",
+    SLACK_TOKEN: "Slack Token",
+    BASIC_AUTH_CREDENTIALS: "Basic Authentication Credentials",
+    API_KEY: "API Key",
+    AUTHENTICATION_TOKEN: "Authentication Token",
+    PASSWORD: "Password",
+    SECRET: "Secret",
+    SENSITIVE_DATA: "Sensitive Data",
+} as const
+
+export const SECRET_EXAMPLE_VALUES = {
+    AWS_ACCESS_KEY_ID: "AKIA1234567890ABCDEF",
+    AWS_SECRET_ACCESS_KEY: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
+    GITHUB_TOKEN: "ghp_1234567890abcdefghijklmnopqrstuv",
+    NPM_TOKEN: "npm_abc123xyz",
+    SLACK_TOKEN: "xoxb-<token-here>",
+    API_KEY: "sk_live_XXXXXXXXXXXXXXXXXXXX_example_key",
+    HARDCODED_SECRET: "hardcoded-secret-value",
+} as const
+
+export const FILE_ENCODING = {
+    UTF8: "utf-8",
+} as const
+
+export const REGEX_ESCAPE_PATTERN = {
+    DOLLAR_AMPERSAND: "\\$&",
+} as const
+
+export const DYNAMIC_IMPORT_PATTERN_PARTS = {
+    QUOTE_START: '"`][^',
+    QUOTE_END: "`]+['\"",
+} as const
--- a/packages/guardian/src/domain/constants/Suggestions.ts
+++ b/packages/guardian/src/domain/constants/Suggestions.ts
@@ -24,6 +24,106 @@ export const SUGGESTION_KEYWORDS = {
    CONSOLE_ERROR: "console.error",
 } as const

+/**
+ * Context keywords for email detection
+ */
+export const EMAIL_CONTEXT_KEYWORDS = {
+    ADMIN: "admin",
+    SUPPORT: "support",
+    NOREPLY: "noreply",
+    NO_REPLY: "no-reply",
+} as const
+
+/**
+ * Context keywords for API key detection
+ */
+export const API_KEY_CONTEXT_KEYWORDS = {
+    SECRET: "secret",
+    PUBLIC: "public",
+} as const
+
+/**
+ * Context keywords for URL detection
+ */
+export const URL_CONTEXT_KEYWORDS = {
+    API: "api",
+    DATABASE: "database",
+    DB: "db",
+    MONGO: "mongo",
+    POSTGRES: "postgres",
+    PG: "pg",
+} as const
+
+/**
+ * Context keywords for IP address detection
+ */
+export const IP_CONTEXT_KEYWORDS = {
+    SERVER: "server",
+    REDIS: "redis",
+} as const
+
+/**
+ * Context keywords for file path detection
+ */
+export const FILE_PATH_CONTEXT_KEYWORDS = {
+    LOG: "log",
+    DATA: "data",
+    TEMP: "temp",
+} as const
+
+/**
+ * Context keywords for date detection
+ */
+export const DATE_CONTEXT_KEYWORDS = {
+    DEADLINE: "deadline",
+    START: "start",
+    END: "end",
+    EXPIR: "expir",
+} as const
+
+/**
+ * Context keywords for UUID detection
+ */
+export const UUID_CONTEXT_KEYWORDS = {
+    ID: "id",
+    IDENTIFIER: "identifier",
+    REQUEST: "request",
+    SESSION: "session",
+} as const
+
+/**
+ * Context keywords for version detection
+ */
+export const VERSION_CONTEXT_KEYWORDS = {
+    APP: "app",
+} as const
+
+/**
+ * Context keywords for color detection
+ */
+export const COLOR_CONTEXT_KEYWORDS = {
+    PRIMARY: "primary",
+    SECONDARY: "secondary",
+    BACKGROUND: "background",
+} as const
+
+/**
+ * Context keywords for base64 detection
+ */
+export const BASE64_CONTEXT_KEYWORDS = {
+    TOKEN: "token",
+    KEY: "key",
+} as const
+
+/**
+ * Context keywords for config detection
+ */
+export const CONFIG_CONTEXT_KEYWORDS = {
+    ENDPOINT: "endpoint",
+    ROUTE: "route",
+    CONNECTION: "connection",
+} as const
+
 /**
 * Constant name templates
 */
@@ -41,6 +141,50 @@ export const CONSTANT_NAMES = {
    MAGIC_STRING: "MAGIC_STRING",
    MAGIC_NUMBER: "MAGIC_NUMBER",
    UNKNOWN_CONSTANT: "UNKNOWN_CONSTANT",
+    ADMIN_EMAIL: "ADMIN_EMAIL",
+    SUPPORT_EMAIL: "SUPPORT_EMAIL",
+    NOREPLY_EMAIL: "NOREPLY_EMAIL",
+    DEFAULT_EMAIL: "DEFAULT_EMAIL",
+    API_SECRET_KEY: "API_SECRET_KEY",
+    API_PUBLIC_KEY: "API_PUBLIC_KEY",
+    API_KEY: "API_KEY",
+    DATABASE_URL: "DATABASE_URL",
+    MONGODB_CONNECTION_STRING: "MONGODB_CONNECTION_STRING",
+    POSTGRES_URL: "POSTGRES_URL",
+    BASE_URL: "BASE_URL",
+    SERVER_IP: "SERVER_IP",
+    DATABASE_HOST: "DATABASE_HOST",
+    REDIS_HOST: "REDIS_HOST",
+    HOST_IP: "HOST_IP",
+    LOG_FILE_PATH: "LOG_FILE_PATH",
+    CONFIG_FILE_PATH: "CONFIG_FILE_PATH",
+    DATA_DIR_PATH: "DATA_DIR_PATH",
+    TEMP_DIR_PATH: "TEMP_DIR_PATH",
+    FILE_PATH: "FILE_PATH",
+    DEADLINE: "DEADLINE",
+    START_DATE: "START_DATE",
+    END_DATE: "END_DATE",
+    EXPIRATION_DATE: "EXPIRATION_DATE",
+    DEFAULT_DATE: "DEFAULT_DATE",
+    DEFAULT_ID: "DEFAULT_ID",
+    REQUEST_ID: "REQUEST_ID",
+    SESSION_ID: "SESSION_ID",
+    UUID_CONSTANT: "UUID_CONSTANT",
+    API_VERSION: "API_VERSION",
+    APP_VERSION: "APP_VERSION",
+    VERSION: "VERSION",
+    PRIMARY_COLOR: "PRIMARY_COLOR",
+    SECONDARY_COLOR: "SECONDARY_COLOR",
+    BACKGROUND_COLOR: "BACKGROUND_COLOR",
+    COLOR_CONSTANT: "COLOR_CONSTANT",
+    MAC_ADDRESS: "MAC_ADDRESS",
+    ENCODED_TOKEN: "ENCODED_TOKEN",
+    ENCODED_KEY: "ENCODED_KEY",
+    BASE64_VALUE: "BASE64_VALUE",
+    API_ENDPOINT: "API_ENDPOINT",
+    ROUTE_PATH: "ROUTE_PATH",
+    CONNECTION_STRING: "CONNECTION_STRING",
+    CONFIG_VALUE: "CONFIG_VALUE",
 } as const

 /**
@@ -50,4 +194,8 @@ export const LOCATIONS = {
    SHARED_CONSTANTS: "shared/constants",
    DOMAIN_CONSTANTS: "domain/constants",
    INFRASTRUCTURE_CONFIG: "infrastructure/config",
+    CONFIG_ENVIRONMENT: "src/config/environment.ts",
+    CONFIG_CONTACTS: "src/config/contacts.ts",
+    CONFIG_PATHS: "src/config/paths.ts",
+    CONFIG_DATES: "src/config/dates.ts",
 } as const
--- a/packages/guardian/src/domain/entities/DependencyGraph.ts
+++ b/packages/guardian/src/domain/entities/DependencyGraph.ts
@@ -94,7 +94,7 @@ export class DependencyGraph extends BaseEntity {
        totalDependencies: number
        avgDependencies: number
        maxDependencies: number
-        } {
+    } {
        const nodes = Array.from(this.nodes.values())
        const totalFiles = nodes.length
        const totalDependencies = nodes.reduce((sum, node) => sum + node.dependencies.length, 0)
--- a/packages/guardian/src/domain/index.ts
+++ b/packages/guardian/src/domain/index.ts
@@ -5,9 +5,10 @@ export * from "./value-objects/ValueObject"
 export * from "./value-objects/ProjectPath"
 export * from "./value-objects/HardcodedValue"
 export * from "./value-objects/NamingViolation"
-export * from "./repositories/IBaseRepository"
+export * from "./value-objects/RepositoryViolation"
 export * from "./services/IFileScanner"
 export * from "./services/ICodeParser"
 export * from "./services/IHardcodeDetector"
 export * from "./services/INamingConventionDetector"
+export * from "./services/RepositoryPatternDetectorService"
 export * from "./events/DomainEvent"
--- a/packages/guardian/src/domain/repositories/IBaseRepository.ts
+++ b/packages/guardian/src/domain/repositories/IBaseRepository.ts
@@ -1,14 +0,0 @@
-import { BaseEntity } from "../entities/BaseEntity"
-
-/**
- * Generic repository interface
- * Defines standard CRUD operations for entities
- */
-export interface IRepository<T extends BaseEntity> {
-    findById(id: string): Promise<T | null>
-    findAll(): Promise<T[]>
-    save(entity: T): Promise<T>
-    update(entity: T): Promise<T>
-    delete(id: string): Promise<boolean>
-    exists(id: string): Promise<boolean>
-}
--- a/packages/guardian/src/domain/services/IAggregateBoundaryDetector.ts
+++ b/packages/guardian/src/domain/services/IAggregateBoundaryDetector.ts
@@ -0,0 +1,45 @@
+import { AggregateBoundaryViolation } from "../value-objects/AggregateBoundaryViolation"
+
+/**
+ * Interface for detecting aggregate boundary violations in DDD
+ *
+ * Aggregate boundary violations occur when an entity from one aggregate
+ * directly references an entity from another aggregate. In DDD, aggregates
+ * should reference each other only by ID or Value Objects to maintain
+ * loose coupling and independence.
+ */
+export interface IAggregateBoundaryDetector {
+    /**
+     * Detects aggregate boundary violations in the given code
+     *
+     * Analyzes import statements to identify direct entity references
+     * across aggregate boundaries.
+     *
+     * @param code - Source code to analyze
+     * @param filePath - Path to the file being analyzed
+     * @param layer - The architectural layer of the file (should be 'domain')
+     * @returns Array of detected aggregate boundary violations
+     */
+    detectViolations(
+        code: string,
+        filePath: string,
+        layer: string | undefined,
+    ): AggregateBoundaryViolation[]
+
+    /**
+     * Checks if a file path belongs to an aggregate
+     *
+     * @param filePath - The file path to check
+     * @returns The aggregate name if found, undefined otherwise
+     */
+    extractAggregateFromPath(filePath: string): string | undefined
+
+    /**
+     * Checks if an import path references an entity from another aggregate
+     *
+     * @param importPath - The import path to analyze
+     * @param currentAggregate - The aggregate of the current file
+     * @returns True if the import crosses aggregate boundaries inappropriately
+     */
+    isAggregateBoundaryViolation(importPath: string, currentAggregate: string): boolean
+}
--- a/packages/guardian/src/domain/services/IAnemicModelDetector.ts
+++ b/packages/guardian/src/domain/services/IAnemicModelDetector.ts
@@ -0,0 +1,29 @@
+import { AnemicModelViolation } from "../value-objects/AnemicModelViolation"
+
+/**
+ * Interface for detecting anemic domain model violations in the codebase
+ *
+ * Anemic domain models are entities that contain only getters/setters
+ * without business logic. This anti-pattern violates Domain-Driven Design
+ * principles and leads to procedural code scattered in services.
+ */
+export interface IAnemicModelDetector {
+    /**
+     * Detects anemic model violations in the given code
+     *
+     * Analyzes classes in domain/entities to identify:
+     * - Classes with only getters and setters (no business logic)
+     * - Classes with public setters (DDD anti-pattern)
+     * - Classes with low method-to-property ratio
+     *
+     * @param code - Source code to analyze
+     * @param filePath - Path to the file being analyzed
+     * @param layer - The architectural layer of the file (domain, application, infrastructure, shared)
+     * @returns Array of detected anemic model violations
+     */
+    detectAnemicModels(
+        code: string,
+        filePath: string,
+        layer: string | undefined,
+    ): AnemicModelViolation[]
+}
--- a/packages/guardian/src/domain/services/IDependencyDirectionDetector.ts
+++ b/packages/guardian/src/domain/services/IDependencyDirectionDetector.ts
@@ -0,0 +1,47 @@
+import { DependencyViolation } from "../value-objects/DependencyViolation"
+
+/**
+ * Interface for detecting dependency direction violations in the codebase
+ *
+ * Dependency direction violations occur when a layer imports from a layer
+ * that it should not depend on according to Clean Architecture principles:
+ * - Domain should not import from Application or Infrastructure
+ * - Application should not import from Infrastructure
+ * - Infrastructure can import from Application and Domain
+ * - Shared can be imported by all layers
+ */
+export interface IDependencyDirectionDetector {
+    /**
+     * Detects dependency direction violations in the given code
+     *
+     * Analyzes import statements to identify violations of dependency rules
+     * between architectural layers.
+     *
+     * @param code - Source code to analyze
+     * @param filePath - Path to the file being analyzed
+     * @param layer - The architectural layer of the file (domain, application, infrastructure, shared)
+     * @returns Array of detected dependency direction violations
+     */
+    detectViolations(
+        code: string,
+        filePath: string,
+        layer: string | undefined,
+    ): DependencyViolation[]
+
+    /**
+     * Checks if an import violates dependency direction rules
+     *
+     * @param fromLayer - The layer that is importing
+     * @param toLayer - The layer being imported
+     * @returns True if the import violates dependency rules
+     */
+    isViolation(fromLayer: string, toLayer: string): boolean
+
+    /**
+     * Extracts the layer from an import path
+     *
+     * @param importPath - The import path to analyze
+     * @returns The layer name if detected, undefined otherwise
+     */
+    extractLayerFromImport(importPath: string): string | undefined
+}
--- a/packages/guardian/src/domain/services/IDuplicateValueTracker.ts
+++ b/packages/guardian/src/domain/services/IDuplicateValueTracker.ts
@@ -0,0 +1,55 @@
+import { HardcodedValue } from "../value-objects/HardcodedValue"
+
+export interface ValueLocation {
+    file: string
+    line: number
+    context: string
+}
+
+export interface DuplicateInfo {
+    value: string | number | boolean
+    locations: ValueLocation[]
+    count: number
+}
+
+/**
+ * Interface for tracking duplicate hardcoded values across files
+ *
+ * Helps identify values that are used in multiple places
+ * and should be extracted to a shared constant.
+ */
+export interface IDuplicateValueTracker {
+    /**
+     * Adds a hardcoded value to tracking
+     */
+    track(violation: HardcodedValue, filePath: string): void
+
+    /**
+     * Gets all duplicate values (values used in 2+ places)
+     */
+    getDuplicates(): DuplicateInfo[]
+
+    /**
+     * Gets duplicate locations for a specific value
+     */
+    getDuplicateLocations(value: string | number | boolean, type: string): ValueLocation[] | null
+
+    /**
+     * Checks if a value is duplicated
+     */
+    isDuplicate(value: string | number | boolean, type: string): boolean
+
+    /**
+     * Gets statistics about duplicates
+     */
+    getStats(): {
+        totalValues: number
+        duplicateValues: number
+        duplicatePercentage: number
+    }
+
+    /**
+     * Clears all tracked values
+     */
+    clear(): void
+}
--- a/packages/guardian/src/domain/services/IEntityExposureDetector.ts
+++ b/packages/guardian/src/domain/services/IEntityExposureDetector.ts
@@ -0,0 +1,34 @@
+import { EntityExposure } from "../value-objects/EntityExposure"
+
+/**
+ * Interface for detecting entity exposure violations in the codebase
+ *
+ * Entity exposure occurs when domain entities are directly returned from
+ * controllers/routes instead of using DTOs (Data Transfer Objects).
+ * This violates separation of concerns and can expose internal domain logic.
+ */
+export interface IEntityExposureDetector {
+    /**
+     * Detects entity exposure violations in the given code
+     *
+     * Analyzes method return types in controllers/routes to identify
+     * domain entities being directly exposed to external clients.
+     *
+     * @param code - Source code to analyze
+     * @param filePath - Path to the file being analyzed
+     * @param layer - The architectural layer of the file (domain, application, infrastructure, shared)
+     * @returns Array of detected entity exposure violations
+     */
+    detectExposures(code: string, filePath: string, layer: string | undefined): EntityExposure[]
+
+    /**
+     * Checks if a return type is a domain entity
+     *
+     * Domain entities are typically PascalCase nouns without Dto/Request/Response suffixes
+     * and are defined in the domain layer.
+     *
+     * @param returnType - The return type to check
+     * @returns True if the return type appears to be a domain entity
+     */
+    isDomainEntity(returnType: string): boolean
+}
--- a/packages/guardian/src/domain/services/INamingConventionDetector.ts
+++ b/packages/guardian/src/domain/services/INamingConventionDetector.ts
@@ -7,12 +7,14 @@ export interface INamingConventionDetector {
    /**
     * Detects naming convention violations for a given file
     *
+     * @param content - Source code content to analyze
     * @param fileName - Name of the file to check (e.g., "UserService.ts")
     * @param layer - Architectural layer of the file (domain, application, infrastructure, shared)
     * @param filePath - Relative file path for context
     * @returns Array of naming convention violations
     */
    detectViolations(
+        content: string,
        fileName: string,
        layer: string | undefined,
        filePath: string,
--- a/packages/guardian/src/domain/services/ISecretDetector.ts
+++ b/packages/guardian/src/domain/services/ISecretDetector.ts
@@ -0,0 +1,34 @@
+import { SecretViolation } from "../value-objects/SecretViolation"
+
+/**
+ * Interface for detecting hardcoded secrets in source code
+ *
+ * Detects sensitive data like API keys, tokens, passwords, and credentials
+ * that should never be hardcoded in source code. Uses industry-standard
+ * Secretlint library for pattern matching.
+ *
+ * All detected secrets are marked as CRITICAL severity violations.
+ *
+ * @example
+ * ```typescript
+ * const detector: ISecretDetector = new SecretDetector()
+ * const violations = await detector.detectAll(
+ *     'const AWS_KEY = "AKIA1234567890ABCDEF"',
+ *     'src/config/aws.ts'
+ * )
+ *
+ * violations.forEach(v => {
+ *     console.log(v.getMessage()) // "Hardcoded AWS Access Key detected"
+ * })
+ * ```
+ */
+export interface ISecretDetector {
+    /**
+     * Detect all types of hardcoded secrets in the provided code
+     *
+     * @param code - Source code to analyze
+     * @param filePath - Path to the file being analyzed
+     * @returns Array of secret violations found
+     */
+    detectAll(code: string, filePath: string): Promise<SecretViolation[]>
+}
--- a/packages/guardian/src/domain/services/RepositoryPatternDetectorService.ts
+++ b/packages/guardian/src/domain/services/RepositoryPatternDetectorService.ts
@@ -0,0 +1,88 @@
+import { RepositoryViolation } from "../value-objects/RepositoryViolation"
+
+/**
+ * Interface for detecting Repository Pattern violations in the codebase
+ *
+ * Repository Pattern violations include:
+ * - ORM-specific types in repository interfaces (domain layer)
+ * - Concrete repository usage in use cases instead of interfaces
+ * - Repository instantiation with 'new' in use cases (should use DI)
+ * - Non-domain method names in repository interfaces
+ *
+ * The Repository Pattern ensures that domain logic remains decoupled from
+ * infrastructure concerns like databases and ORMs.
+ */
+export interface IRepositoryPatternDetector {
+    /**
+     * Detects all Repository Pattern violations in the given code
+     *
+     * Analyzes code for proper implementation of the Repository Pattern,
+     * including interface purity, dependency inversion, and domain language usage.
+     *
+     * @param code - Source code to analyze
+     * @param filePath - Path to the file being analyzed
+     * @param layer - The architectural layer of the file (domain, application, infrastructure, shared)
+     * @returns Array of detected Repository Pattern violations
+     */
+    detectViolations(
+        code: string,
+        filePath: string,
+        layer: string | undefined,
+    ): RepositoryViolation[]
+
+    /**
+     * Checks if a type is an ORM-specific type
+     *
+     * ORM-specific types include Prisma types, TypeORM decorators, Mongoose schemas, etc.
+     * These types should not appear in domain repository interfaces.
+     *
+     * @param typeName - The type name to check
+     * @returns True if the type is ORM-specific
+     */
+    isOrmType(typeName: string): boolean
+
+    /**
+     * Checks if a method name follows domain language conventions
+     *
+     * Domain repository methods should use business-oriented names like:
+     * - findById, findByEmail, findByStatus
+     * - save, create, update
+     * - delete, remove
+     *
+     * Avoid technical database terms like:
+     * - findOne, findMany, query
+     * - insert, select, update (SQL terms)
+     *
+     * @param methodName - The method name to check
+     * @returns True if the method name uses domain language
+     */
+    isDomainMethodName(methodName: string): boolean
+
+    /**
+     * Checks if a file is a repository interface
+     *
+     * Repository interfaces typically:
+     * - Are in the domain layer
+     * - Have names matching I*Repository pattern
+     * - Contain interface definitions
+     *
+     * @param filePath - The file path to check
+     * @param layer - The architectural layer
+     * @returns True if the file is a repository interface
+     */
+    isRepositoryInterface(filePath: string, layer: string | undefined): boolean
+
+    /**
+     * Checks if a file is a use case
+     *
+     * Use cases typically:
+     * - Are in the application layer
+     * - Follow verb-noun naming pattern (CreateUser, UpdateProfile)
+     * - Contain class definitions for business operations
+     *
+     * @param filePath - The file path to check
+     * @param layer - The architectural layer
+     * @returns True if the file is a use case
+     */
+    isUseCase(filePath: string, layer: string | undefined): boolean
+}
--- a/packages/guardian/src/domain/value-objects/AggregateBoundaryViolation.ts
+++ b/packages/guardian/src/domain/value-objects/AggregateBoundaryViolation.ts
@@ -0,0 +1,137 @@
+import { ValueObject } from "./ValueObject"
+import { AGGREGATE_VIOLATION_MESSAGES } from "../constants/Messages"
+
+interface AggregateBoundaryViolationProps {
+    readonly fromAggregate: string
+    readonly toAggregate: string
+    readonly entityName: string
+    readonly importPath: string
+    readonly filePath: string
+    readonly line?: number
+}
+
+/**
+ * Represents an aggregate boundary violation in the codebase
+ *
+ * Aggregate boundary violations occur when an entity from one aggregate
+ * directly references an entity from another aggregate, violating DDD principles:
+ * - Aggregates should reference each other only by ID or Value Objects
+ * - Direct entity references create tight coupling between aggregates
+ * - Changes to one aggregate should not require changes to another
+ *
+ * @example
+ * ```typescript
+ * // Bad: Direct entity reference across aggregates
+ * const violation = AggregateBoundaryViolation.create(
+ *     'order',
+ *     'user',
+ *     'User',
+ *     '../user/User',
+ *     'src/domain/aggregates/order/Order.ts',
+ *     5
+ * )
+ *
+ * console.log(violation.getMessage())
+ * // "Order aggregate should not directly reference User entity from User aggregate"
+ * ```
+ */
+export class AggregateBoundaryViolation extends ValueObject<AggregateBoundaryViolationProps> {
+    private constructor(props: AggregateBoundaryViolationProps) {
+        super(props)
+    }
+
+    public static create(
+        fromAggregate: string,
+        toAggregate: string,
+        entityName: string,
+        importPath: string,
+        filePath: string,
+        line?: number,
+    ): AggregateBoundaryViolation {
+        return new AggregateBoundaryViolation({
+            fromAggregate,
+            toAggregate,
+            entityName,
+            importPath,
+            filePath,
+            line,
+        })
+    }
+
+    public get fromAggregate(): string {
+        return this.props.fromAggregate
+    }
+
+    public get toAggregate(): string {
+        return this.props.toAggregate
+    }
+
+    public get entityName(): string {
+        return this.props.entityName
+    }
+
+    public get importPath(): string {
+        return this.props.importPath
+    }
+
+    public get filePath(): string {
+        return this.props.filePath
+    }
+
+    public get line(): number | undefined {
+        return this.props.line
+    }
+
+    public getMessage(): string {
+        return `${this.capitalizeFirst(this.props.fromAggregate)} aggregate should not directly reference ${this.props.entityName} entity from ${this.capitalizeFirst(this.props.toAggregate)} aggregate`
+    }
+
+    public getSuggestion(): string {
+        const suggestions: string[] = [
+            AGGREGATE_VIOLATION_MESSAGES.USE_ID_REFERENCE,
+            AGGREGATE_VIOLATION_MESSAGES.USE_VALUE_OBJECT,
+            AGGREGATE_VIOLATION_MESSAGES.AVOID_DIRECT_REFERENCE,
+            AGGREGATE_VIOLATION_MESSAGES.MAINTAIN_INDEPENDENCE,
+        ]
+
+        return suggestions.join("\n")
+    }
+
+    public getExampleFix(): string {
+        return `
+// ❌ Bad: Direct entity reference across aggregates
+// domain/aggregates/order/Order.ts
+import { User } from '../user/User'
+
+class Order {
+    constructor(private user: User) {}
+}
+
+// ✅ Good: Reference by ID
+// domain/aggregates/order/Order.ts
+import { UserId } from '../user/value-objects/UserId'
+
+class Order {
+    constructor(private userId: UserId) {}
+}
+
+// ✅ Good: Use Value Object for needed data
+// domain/aggregates/order/value-objects/CustomerInfo.ts
+class CustomerInfo {
+    constructor(
+        readonly customerId: string,
+        readonly customerName: string,
+        readonly customerEmail: string
+    ) {}
+}
+
+// domain/aggregates/order/Order.ts
+class Order {
+    constructor(private customerInfo: CustomerInfo) {}
+}`
+    }
+
+    private capitalizeFirst(str: string): string {
+        return str.charAt(0).toUpperCase() + str.slice(1)
+    }
+}
--- a/packages/guardian/src/domain/value-objects/AnemicModelViolation.ts
+++ b/packages/guardian/src/domain/value-objects/AnemicModelViolation.ts
@@ -0,0 +1,240 @@
+import { ValueObject } from "./ValueObject"
+import { ANEMIC_MODEL_MESSAGES } from "../constants/Messages"
+import { EXAMPLE_CODE_CONSTANTS } from "../../shared/constants"
+
+interface AnemicModelViolationProps {
+    readonly className: string
+    readonly filePath: string
+    readonly layer: string
+    readonly line?: number
+    readonly methodCount: number
+    readonly propertyCount: number
+    readonly hasOnlyGettersSetters: boolean
+    readonly hasPublicSetters: boolean
+}
+
+/**
+ * Represents an anemic domain model violation in the codebase
+ *
+ * Anemic domain model occurs when entities have only getters/setters
+ * without business logic. This violates Domain-Driven Design principles
+ * and leads to procedural code instead of object-oriented design.
+ *
+ * @example
+ * ```typescript
+ * // Bad: Anemic model with only getters/setters
+ * const violation = AnemicModelViolation.create(
+ *     'Order',
+ *     'src/domain/entities/Order.ts',
+ *     'domain',
+ *     10,
+ *     4,
+ *     2,
+ *     true,
+ *     true
+ * )
+ *
+ * console.log(violation.getMessage())
+ * // "Class 'Order' is anemic: 4 methods (all getters/setters) for 2 properties"
+ * ```
+ */
+export class AnemicModelViolation extends ValueObject<AnemicModelViolationProps> {
+    private constructor(props: AnemicModelViolationProps) {
+        super(props)
+    }
+
+    public static create(
+        className: string,
+        filePath: string,
+        layer: string,
+        line: number | undefined,
+        methodCount: number,
+        propertyCount: number,
+        hasOnlyGettersSetters: boolean,
+        hasPublicSetters: boolean,
+    ): AnemicModelViolation {
+        return new AnemicModelViolation({
+            className,
+            filePath,
+            layer,
+            line,
+            methodCount,
+            propertyCount,
+            hasOnlyGettersSetters,
+            hasPublicSetters,
+        })
+    }
+
+    public get className(): string {
+        return this.props.className
+    }
+
+    public get filePath(): string {
+        return this.props.filePath
+    }
+
+    public get layer(): string {
+        return this.props.layer
+    }
+
+    public get line(): number | undefined {
+        return this.props.line
+    }
+
+    public get methodCount(): number {
+        return this.props.methodCount
+    }
+
+    public get propertyCount(): number {
+        return this.props.propertyCount
+    }
+
+    public get hasOnlyGettersSetters(): boolean {
+        return this.props.hasOnlyGettersSetters
+    }
+
+    public get hasPublicSetters(): boolean {
+        return this.props.hasPublicSetters
+    }
+
+    public getMessage(): string {
+        if (this.props.hasPublicSetters) {
+            return `Class '${this.props.className}' has public setters (anti-pattern in DDD)`
+        }
+
+        if (this.props.hasOnlyGettersSetters) {
+            return `Class '${this.props.className}' is anemic: ${String(this.props.methodCount)} methods (all getters/setters) for ${String(this.props.propertyCount)} properties`
+        }
+
+        const ratio = this.props.methodCount / Math.max(this.props.propertyCount, 1)
+        return `Class '${this.props.className}' appears anemic: low method-to-property ratio (${ratio.toFixed(1)}:1)`
+    }
+
+    public getSuggestion(): string {
+        const suggestions: string[] = []
+
+        if (this.props.hasPublicSetters) {
+            suggestions.push(ANEMIC_MODEL_MESSAGES.REMOVE_PUBLIC_SETTERS)
+            suggestions.push(ANEMIC_MODEL_MESSAGES.USE_METHODS_FOR_CHANGES)
+            suggestions.push(ANEMIC_MODEL_MESSAGES.ENCAPSULATE_INVARIANTS)
+        }
+
+        if (this.props.hasOnlyGettersSetters || this.props.methodCount < 2) {
+            suggestions.push(ANEMIC_MODEL_MESSAGES.ADD_BUSINESS_METHODS)
+            suggestions.push(ANEMIC_MODEL_MESSAGES.MOVE_LOGIC_FROM_SERVICES)
+            suggestions.push(ANEMIC_MODEL_MESSAGES.ENCAPSULATE_BUSINESS_RULES)
+            suggestions.push(ANEMIC_MODEL_MESSAGES.USE_DOMAIN_EVENTS)
+        }
+
+        return suggestions.join("\n")
+    }
+
+    public getExampleFix(): string {
+        if (this.props.hasPublicSetters) {
+            return `
+// ❌ Bad: Public setters allow uncontrolled state changes
+class ${this.props.className} {
+    private status: string
+
+    public setStatus(status: string): void {
+        this.status = status  // No validation!
+    }
+
+    public getStatus(): string {
+        return this.status
+    }
+}
+
+// ✅ Good: Business methods with validation
+class ${this.props.className} {
+    private status: OrderStatus
+
+    public approve(): void {
+        if (!this.canBeApproved()) {
+            throw new CannotApproveOrderError()
+        }
+        this.status = OrderStatus.APPROVED
+        this.events.push(new OrderApprovedEvent(this.id))
+    }
+
+    public reject(reason: string): void {
+        if (!this.canBeRejected()) {
+            throw new CannotRejectOrderError()
+        }
+        this.status = OrderStatus.REJECTED
+        this.rejectionReason = reason
+        this.events.push(new OrderRejectedEvent(this.id, reason))
+    }
+
+    public getStatus(): OrderStatus {
+        return this.status
+    }
+
+    private canBeApproved(): boolean {
+        return this.status === OrderStatus.PENDING && this.hasItems()
+    }
+}`
+        }
+
+        return `
+// ❌ Bad: Anemic model (only getters/setters)
+class ${this.props.className} {
+    getStatus() { return this.status }
+    setStatus(status: string) { this.status = status }
+
+    getTotal() { return this.total }
+    setTotal(total: number) { this.total = total }
+}
+
+class OrderService {
+    approve(order: ${this.props.className}): void {
+        if (order.getStatus() !== '${EXAMPLE_CODE_CONSTANTS.ORDER_STATUS_PENDING}') {
+            throw new Error('${EXAMPLE_CODE_CONSTANTS.CANNOT_APPROVE_ERROR}')
+        }
+        order.setStatus('${EXAMPLE_CODE_CONSTANTS.ORDER_STATUS_APPROVED}')
+    }
+}
+
+// ✅ Good: Rich domain model with business logic
+class ${this.props.className} {
+    private readonly id: OrderId
+    private status: OrderStatus
+    private items: OrderItem[]
+    private events: DomainEvent[] = []
+
+    public approve(): void {
+        if (!this.isPending()) {
+            throw new CannotApproveOrderError()
+        }
+        this.status = OrderStatus.APPROVED
+        this.events.push(new OrderApprovedEvent(this.id))
+    }
+
+    public calculateTotal(): Money {
+        return this.items.reduce(
+            (sum, item) => sum.add(item.getPrice()),
+            Money.zero()
+        )
+    }
+
+    public addItem(item: OrderItem): void {
+        if (this.isApproved()) {
+            throw new CannotModifyApprovedOrderError()
+        }
+        this.items.push(item)
+    }
+
+    public getStatus(): OrderStatus {
+        return this.status
+    }
+
+    private isPending(): boolean {
+        return this.status === OrderStatus.PENDING
+    }
+
+    private isApproved(): boolean {
+        return this.status === OrderStatus.APPROVED
+    }
+}`
+    }
+}
--- a/packages/guardian/src/domain/value-objects/DependencyViolation.ts
+++ b/packages/guardian/src/domain/value-objects/DependencyViolation.ts
@@ -0,0 +1,171 @@
+import { ValueObject } from "./ValueObject"
+import {
+    LAYER_APPLICATION,
+    LAYER_DOMAIN,
+    LAYER_INFRASTRUCTURE,
+} from "../../shared/constants/layers"
+import { DEPENDENCY_VIOLATION_MESSAGES } from "../constants/Messages"
+
+interface DependencyViolationProps {
+    readonly fromLayer: string
+    readonly toLayer: string
+    readonly importPath: string
+    readonly filePath: string
+    readonly line?: number
+}
+
+/**
+ * Represents a dependency direction violation in the codebase
+ *
+ * Dependency direction violations occur when a layer imports from a layer
+ * that it should not depend on according to Clean Architecture principles:
+ * - Domain → should not import from Application or Infrastructure
+ * - Application → should not import from Infrastructure
+ * - Infrastructure → can import from Application and Domain (allowed)
+ * - Shared → can be imported by all layers (allowed)
+ *
+ * @example
+ * ```typescript
+ * // Bad: Domain importing from Application
+ * const violation = DependencyViolation.create(
+ *     'domain',
+ *     'application',
+ *     '../../application/dtos/UserDto',
+ *     'src/domain/entities/User.ts',
+ *     5
+ * )
+ *
+ * console.log(violation.getMessage())
+ * // "Domain layer should not import from Application layer"
+ * ```
+ */
+export class DependencyViolation extends ValueObject<DependencyViolationProps> {
+    private constructor(props: DependencyViolationProps) {
+        super(props)
+    }
+
+    public static create(
+        fromLayer: string,
+        toLayer: string,
+        importPath: string,
+        filePath: string,
+        line?: number,
+    ): DependencyViolation {
+        return new DependencyViolation({
+            fromLayer,
+            toLayer,
+            importPath,
+            filePath,
+            line,
+        })
+    }
+
+    public get fromLayer(): string {
+        return this.props.fromLayer
+    }
+
+    public get toLayer(): string {
+        return this.props.toLayer
+    }
+
+    public get importPath(): string {
+        return this.props.importPath
+    }
+
+    public get filePath(): string {
+        return this.props.filePath
+    }
+
+    public get line(): number | undefined {
+        return this.props.line
+    }
+
+    public getMessage(): string {
+        return `${this.capitalizeFirst(this.props.fromLayer)} layer should not import from ${this.capitalizeFirst(this.props.toLayer)} layer`
+    }
+
+    public getSuggestion(): string {
+        const suggestions: string[] = []
+
+        if (this.props.fromLayer === LAYER_DOMAIN) {
+            suggestions.push(
+                DEPENDENCY_VIOLATION_MESSAGES.DOMAIN_INDEPENDENCE,
+                DEPENDENCY_VIOLATION_MESSAGES.DOMAIN_MOVE_TO_DOMAIN,
+                DEPENDENCY_VIOLATION_MESSAGES.DOMAIN_USE_DI,
+            )
+        } else if (this.props.fromLayer === LAYER_APPLICATION) {
+            suggestions.push(
+                DEPENDENCY_VIOLATION_MESSAGES.APPLICATION_NO_INFRA,
+                DEPENDENCY_VIOLATION_MESSAGES.APPLICATION_DEFINE_PORT,
+                DEPENDENCY_VIOLATION_MESSAGES.APPLICATION_IMPLEMENT_ADAPTER,
+                DEPENDENCY_VIOLATION_MESSAGES.APPLICATION_USE_DI,
+            )
+        }
+
+        return suggestions.join("\n")
+    }
+
+    public getExampleFix(): string {
+        if (this.props.fromLayer === LAYER_DOMAIN && this.props.toLayer === LAYER_INFRASTRUCTURE) {
+            return `
+// ❌ Bad: Domain depends on Infrastructure (PrismaClient)
+// domain/services/UserService.ts
+class UserService {
+    constructor(private prisma: PrismaClient) {}
+}
+
+// ✅ Good: Domain defines interface, Infrastructure implements
+// domain/repositories/IUserRepository.ts
+interface IUserRepository {
+    findById(id: UserId): Promise<User | null>
+    save(user: User): Promise<void>
+}
+
+// domain/services/UserService.ts
+class UserService {
+    constructor(private userRepo: IUserRepository) {}
+}
+
+// infrastructure/repositories/PrismaUserRepository.ts
+class PrismaUserRepository implements IUserRepository {
+    constructor(private prisma: PrismaClient) {}
+    async findById(id: UserId): Promise<User | null> { }
+    async save(user: User): Promise<void> { }
+}`
+        }
+
+        if (
+            this.props.fromLayer === LAYER_APPLICATION &&
+            this.props.toLayer === LAYER_INFRASTRUCTURE
+        ) {
+            return `
+// ❌ Bad: Application depends on Infrastructure (SmtpEmailService)
+// application/use-cases/SendEmail.ts
+class SendWelcomeEmail {
+    constructor(private emailService: SmtpEmailService) {}
+}
+
+// ✅ Good: Application defines Port, Infrastructure implements Adapter
+// application/ports/IEmailService.ts
+interface IEmailService {
+    send(to: string, subject: string, body: string): Promise<void>
+}
+
+// application/use-cases/SendEmail.ts
+class SendWelcomeEmail {
+    constructor(private emailService: IEmailService) {}
+}
+
+// infrastructure/adapters/SmtpEmailService.ts
+class SmtpEmailService implements IEmailService {
+    async send(to: string, subject: string, body: string): Promise<void> { }
+}`
+        }
+
+        return ""
+    }
+
+    private capitalizeFirst(str: string): string {
+        return str.charAt(0).toUpperCase() + str.slice(1)
+    }
+}
--- a/packages/guardian/src/domain/value-objects/EntityExposure.ts
+++ b/packages/guardian/src/domain/value-objects/EntityExposure.ts
@@ -0,0 +1,112 @@
+import { ValueObject } from "./ValueObject"
+import { ENTITY_EXPOSURE_MESSAGES } from "../constants/Messages"
+
+interface EntityExposureProps {
+    readonly entityName: string
+    readonly returnType: string
+    readonly filePath: string
+    readonly layer: string
+    readonly line?: number
+    readonly methodName?: string
+}
+
+/**
+ * Represents an entity exposure violation in the codebase
+ *
+ * Entity exposure occurs when a domain entity is directly exposed in API responses
+ * instead of using DTOs (Data Transfer Objects). This violates the separation of concerns
+ * and can lead to exposing internal domain logic to external clients.
+ *
+ * @example
+ * ```typescript
+ * // Bad: Controller returning domain entity
+ * const exposure = EntityExposure.create(
+ *     'User',
+ *     'User',
+ *     'src/infrastructure/controllers/UserController.ts',
+ *     'infrastructure',
+ *     25,
+ *     'getUser'
+ * )
+ *
+ * console.log(exposure.getMessage())
+ * // "Method 'getUser' returns domain entity 'User' instead of DTO"
+ * ```
+ */
+export class EntityExposure extends ValueObject<EntityExposureProps> {
+    private constructor(props: EntityExposureProps) {
+        super(props)
+    }
+
+    public static create(
+        entityName: string,
+        returnType: string,
+        filePath: string,
+        layer: string,
+        line?: number,
+        methodName?: string,
+    ): EntityExposure {
+        return new EntityExposure({
+            entityName,
+            returnType,
+            filePath,
+            layer,
+            line,
+            methodName,
+        })
+    }
+
+    public get entityName(): string {
+        return this.props.entityName
+    }
+
+    public get returnType(): string {
+        return this.props.returnType
+    }
+
+    public get filePath(): string {
+        return this.props.filePath
+    }
+
+    public get layer(): string {
+        return this.props.layer
+    }
+
+    public get line(): number | undefined {
+        return this.props.line
+    }
+
+    public get methodName(): string | undefined {
+        return this.props.methodName
+    }
+
+    public getMessage(): string {
+        const method = this.props.methodName
+            ? `Method '${this.props.methodName}'`
+            : ENTITY_EXPOSURE_MESSAGES.METHOD_DEFAULT
+        return `${method} returns domain entity '${this.props.entityName}' instead of DTO`
+    }
+
+    public getSuggestion(): string {
+        const suggestions = [
+            `Create a DTO class (e.g., ${this.props.entityName}ResponseDto) in the application layer`,
+            `Create a mapper to convert ${this.props.entityName} to ${this.props.entityName}ResponseDto`,
+            `Update the method to return ${this.props.entityName}ResponseDto instead of ${this.props.entityName}`,
+        ]
+        return suggestions.join("\n")
+    }
+
+    public getExampleFix(): string {
+        return `
+// ❌ Bad: Exposing domain entity
+async ${this.props.methodName || ENTITY_EXPOSURE_MESSAGES.METHOD_DEFAULT_NAME}(): Promise<${this.props.entityName}> {
+    return await this.service.find()
+}
+
+// ✅ Good: Using DTO
+async ${this.props.methodName || ENTITY_EXPOSURE_MESSAGES.METHOD_DEFAULT_NAME}(): Promise<${this.props.entityName}ResponseDto> {
+    const entity = await this.service.find()
+    return ${this.props.entityName}Mapper.toDto(entity)
+}`
+    }
+}
--- a/packages/guardian/src/domain/value-objects/FrameworkLeak.ts
+++ b/packages/guardian/src/domain/value-objects/FrameworkLeak.ts
@@ -1,5 +1,9 @@
 import { ValueObject } from "./ValueObject"
 import { FRAMEWORK_LEAK_MESSAGES } from "../../shared/constants/rules"
+import {
+    DEFAULT_FRAMEWORK_CATEGORY_DESCRIPTION,
+    FRAMEWORK_CATEGORY_DESCRIPTIONS,
+} from "../constants/FrameworkCategories"

 interface FrameworkLeakProps {
    readonly packageName: string
@@ -72,7 +76,10 @@ export class FrameworkLeak extends ValueObject<FrameworkLeakProps> {
    }

    public getMessage(): string {
-        return FRAMEWORK_LEAK_MESSAGES.DOMAIN_IMPORT.replace("{package}", this.props.packageName)
+        return FRAMEWORK_LEAK_MESSAGES.DOMAIN_IMPORT.replace(
+            FRAMEWORK_LEAK_MESSAGES.PACKAGE_PLACEHOLDER,
+            this.props.packageName,
+        )
    }

    public getSuggestion(): string {
@@ -80,33 +87,10 @@ export class FrameworkLeak extends ValueObject<FrameworkLeakProps> {
    }

    public getCategoryDescription(): string {
-        switch (this.props.category) {
-            case "ORM":
-                return "Database ORM/ODM"
-            case "WEB_FRAMEWORK":
-                return "Web Framework"
-            case "HTTP_CLIENT":
-                return "HTTP Client"
-            case "VALIDATION":
-                return "Validation Library"
-            case "DI_CONTAINER":
-                return "DI Container"
-            case "LOGGER":
-                return "Logger"
-            case "CACHE":
-                return "Cache"
-            case "MESSAGE_QUEUE":
-                return "Message Queue"
-            case "EMAIL":
-                return "Email Service"
-            case "STORAGE":
-                return "Storage Service"
-            case "TESTING":
-                return "Testing Framework"
-            case "TEMPLATE_ENGINE":
-                return "Template Engine"
-            default:
-                return "Framework Package"
-        }
+        return (
+            FRAMEWORK_CATEGORY_DESCRIPTIONS[
+                this.props.category as keyof typeof FRAMEWORK_CATEGORY_DESCRIPTIONS
+            ] || DEFAULT_FRAMEWORK_CATEGORY_DESCRIPTION
+        )
    }
 }
--- a/packages/guardian/src/domain/value-objects/HardcodedValue.ts
+++ b/packages/guardian/src/domain/value-objects/HardcodedValue.ts
@@ -1,15 +1,55 @@
 import { ValueObject } from "./ValueObject"
-import { HARDCODE_TYPES } from "../../shared/constants/rules"
-import { CONSTANT_NAMES, LOCATIONS, SUGGESTION_KEYWORDS } from "../constants/Suggestions"
+import { DETECTION_PATTERNS, HARDCODE_TYPES } from "../../shared/constants/rules"
+import {
+    API_KEY_CONTEXT_KEYWORDS,
+    BASE64_CONTEXT_KEYWORDS,
+    COLOR_CONTEXT_KEYWORDS,
+    CONFIG_CONTEXT_KEYWORDS,
+    CONSTANT_NAMES,
+    DATE_CONTEXT_KEYWORDS,
+    EMAIL_CONTEXT_KEYWORDS,
+    FILE_PATH_CONTEXT_KEYWORDS,
+    IP_CONTEXT_KEYWORDS,
+    LOCATIONS,
+    SUGGESTION_KEYWORDS,
+    URL_CONTEXT_KEYWORDS,
+    UUID_CONTEXT_KEYWORDS,
+    VERSION_CONTEXT_KEYWORDS,
+} from "../constants/Suggestions"

 export type HardcodeType = (typeof HARDCODE_TYPES)[keyof typeof HARDCODE_TYPES]

+export type ValueType =
+    | "email"
+    | "url"
+    | "ip_address"
+    | "file_path"
+    | "date"
+    | "api_key"
+    | "uuid"
+    | "version"
+    | "color"
+    | "mac_address"
+    | "base64"
+    | "config"
+    | "generic"
+
+export type ValueImportance = "critical" | "high" | "medium" | "low"
+
+export interface DuplicateLocation {
+    file: string
+    line: number
+}
+
 interface HardcodedValueProps {
-    readonly value: string | number
+    readonly value: string | number | boolean
    readonly type: HardcodeType
+    readonly valueType?: ValueType
    readonly line: number
    readonly column: number
    readonly context: string
+    readonly duplicateLocations?: DuplicateLocation[]
+    readonly withinFileUsageCount?: number
 }

 /**
@@ -21,22 +61,28 @@ export class HardcodedValue extends ValueObject<HardcodedValueProps> {
    }

    public static create(
-        value: string | number,
+        value: string | number | boolean,
        type: HardcodeType,
        line: number,
        column: number,
        context: string,
+        valueType?: ValueType,
+        duplicateLocations?: DuplicateLocation[],
+        withinFileUsageCount?: number,
    ): HardcodedValue {
        return new HardcodedValue({
            value,
            type,
+            valueType,
            line,
            column,
            context,
+            duplicateLocations,
+            withinFileUsageCount,
        })
    }

-    public get value(): string | number {
+    public get value(): string | number | boolean {
        return this.props.value
    }

@@ -56,6 +102,28 @@ export class HardcodedValue extends ValueObject<HardcodedValueProps> {
        return this.props.context
    }

+    public get valueType(): ValueType | undefined {
+        return this.props.valueType
+    }
+
+    public get duplicateLocations(): DuplicateLocation[] | undefined {
+        return this.props.duplicateLocations
+    }
+
+    public get withinFileUsageCount(): number | undefined {
+        return this.props.withinFileUsageCount
+    }
+
+    public hasDuplicates(): boolean {
+        return (
+            this.props.duplicateLocations !== undefined && this.props.duplicateLocations.length > 0
+        )
+    }
+
+    public isAlmostConstant(): boolean {
+        return this.props.withinFileUsageCount !== undefined && this.props.withinFileUsageCount >= 2
+    }
+
    public isMagicNumber(): boolean {
        return this.props.type === HARDCODE_TYPES.MAGIC_NUMBER
    }
@@ -103,9 +171,173 @@ export class HardcodedValue extends ValueObject<HardcodedValueProps> {
        return `${CONSTANT_NAMES.MAGIC_NUMBER}_${String(value)}`
    }

+    // eslint-disable-next-line complexity, max-lines-per-function
    private suggestStringConstantName(): string {
        const value = String(this.props.value)
        const context = this.props.context.toLowerCase()
+        const valueType = this.props.valueType
+
+        if (valueType === "email") {
+            if (context.includes(EMAIL_CONTEXT_KEYWORDS.ADMIN)) {
+                return CONSTANT_NAMES.ADMIN_EMAIL
+            }
+            if (context.includes(EMAIL_CONTEXT_KEYWORDS.SUPPORT)) {
+                return CONSTANT_NAMES.SUPPORT_EMAIL
+            }
+            if (
+                context.includes(EMAIL_CONTEXT_KEYWORDS.NOREPLY) ||
+                context.includes(EMAIL_CONTEXT_KEYWORDS.NO_REPLY)
+            ) {
+                return CONSTANT_NAMES.NOREPLY_EMAIL
+            }
+            return CONSTANT_NAMES.DEFAULT_EMAIL
+        }
+
+        if (valueType === "api_key") {
+            if (context.includes(API_KEY_CONTEXT_KEYWORDS.SECRET)) {
+                return CONSTANT_NAMES.API_SECRET_KEY
+            }
+            if (context.includes(API_KEY_CONTEXT_KEYWORDS.PUBLIC)) {
+                return CONSTANT_NAMES.API_PUBLIC_KEY
+            }
+            return CONSTANT_NAMES.API_KEY
+        }
+
+        if (valueType === "url") {
+            if (context.includes(URL_CONTEXT_KEYWORDS.API)) {
+                return CONSTANT_NAMES.API_BASE_URL
+            }
+            if (
+                context.includes(URL_CONTEXT_KEYWORDS.DATABASE) ||
+                context.includes(URL_CONTEXT_KEYWORDS.DB)
+            ) {
+                return CONSTANT_NAMES.DATABASE_URL
+            }
+            if (context.includes(URL_CONTEXT_KEYWORDS.MONGO)) {
+                return CONSTANT_NAMES.MONGODB_CONNECTION_STRING
+            }
+            if (
+                context.includes(URL_CONTEXT_KEYWORDS.POSTGRES) ||
+                context.includes(URL_CONTEXT_KEYWORDS.PG)
+            ) {
+                return CONSTANT_NAMES.POSTGRES_URL
+            }
+            return CONSTANT_NAMES.BASE_URL
+        }
+
+        if (valueType === "ip_address") {
+            if (context.includes(IP_CONTEXT_KEYWORDS.SERVER)) {
+                return CONSTANT_NAMES.SERVER_IP
+            }
+            if (
+                context.includes(URL_CONTEXT_KEYWORDS.DATABASE) ||
+                context.includes(URL_CONTEXT_KEYWORDS.DB)
+            ) {
+                return CONSTANT_NAMES.DATABASE_HOST
+            }
+            if (context.includes(IP_CONTEXT_KEYWORDS.REDIS)) {
+                return CONSTANT_NAMES.REDIS_HOST
+            }
+            return CONSTANT_NAMES.HOST_IP
+        }
+
+        if (valueType === "file_path") {
+            if (context.includes(FILE_PATH_CONTEXT_KEYWORDS.LOG)) {
+                return CONSTANT_NAMES.LOG_FILE_PATH
+            }
+            if (context.includes(SUGGESTION_KEYWORDS.CONFIG)) {
+                return CONSTANT_NAMES.CONFIG_FILE_PATH
+            }
+            if (context.includes(FILE_PATH_CONTEXT_KEYWORDS.DATA)) {
+                return CONSTANT_NAMES.DATA_DIR_PATH
+            }
+            if (context.includes(FILE_PATH_CONTEXT_KEYWORDS.TEMP)) {
+                return CONSTANT_NAMES.TEMP_DIR_PATH
+            }
+            return CONSTANT_NAMES.FILE_PATH
+        }
+
+        if (valueType === "date") {
+            if (context.includes(DATE_CONTEXT_KEYWORDS.DEADLINE)) {
+                return CONSTANT_NAMES.DEADLINE
+            }
+            if (context.includes(DATE_CONTEXT_KEYWORDS.START)) {
+                return CONSTANT_NAMES.START_DATE
+            }
+            if (context.includes(DATE_CONTEXT_KEYWORDS.END)) {
+                return CONSTANT_NAMES.END_DATE
+            }
+            if (context.includes(DATE_CONTEXT_KEYWORDS.EXPIR)) {
+                return CONSTANT_NAMES.EXPIRATION_DATE
+            }
+            return CONSTANT_NAMES.DEFAULT_DATE
+        }
+
+        if (valueType === "uuid") {
+            if (
+                context.includes(UUID_CONTEXT_KEYWORDS.ID) ||
+                context.includes(UUID_CONTEXT_KEYWORDS.IDENTIFIER)
+            ) {
+                return CONSTANT_NAMES.DEFAULT_ID
+            }
+            if (context.includes(UUID_CONTEXT_KEYWORDS.REQUEST)) {
+                return CONSTANT_NAMES.REQUEST_ID
+            }
+            if (context.includes(UUID_CONTEXT_KEYWORDS.SESSION)) {
+                return CONSTANT_NAMES.SESSION_ID
+            }
+            return CONSTANT_NAMES.UUID_CONSTANT
+        }
+
+        if (valueType === "version") {
+            if (context.includes(URL_CONTEXT_KEYWORDS.API)) {
+                return CONSTANT_NAMES.API_VERSION
+            }
+            if (context.includes(VERSION_CONTEXT_KEYWORDS.APP)) {
+                return CONSTANT_NAMES.APP_VERSION
+            }
+            return CONSTANT_NAMES.VERSION
+        }
+
+        if (valueType === "color") {
+            if (context.includes(COLOR_CONTEXT_KEYWORDS.PRIMARY)) {
+                return CONSTANT_NAMES.PRIMARY_COLOR
+            }
+            if (context.includes(COLOR_CONTEXT_KEYWORDS.SECONDARY)) {
+                return CONSTANT_NAMES.SECONDARY_COLOR
+            }
+            if (context.includes(COLOR_CONTEXT_KEYWORDS.BACKGROUND)) {
+                return CONSTANT_NAMES.BACKGROUND_COLOR
+            }
+            return CONSTANT_NAMES.COLOR_CONSTANT
+        }
+
+        if (valueType === "mac_address") {
+            return CONSTANT_NAMES.MAC_ADDRESS
+        }
+
+        if (valueType === "base64") {
+            if (context.includes(BASE64_CONTEXT_KEYWORDS.TOKEN)) {
+                return CONSTANT_NAMES.ENCODED_TOKEN
+            }
+            if (context.includes(BASE64_CONTEXT_KEYWORDS.KEY)) {
+                return CONSTANT_NAMES.ENCODED_KEY
+            }
+            return CONSTANT_NAMES.BASE64_VALUE
+        }
+
+        if (valueType === "config") {
+            if (context.includes(CONFIG_CONTEXT_KEYWORDS.ENDPOINT)) {
+                return CONSTANT_NAMES.API_ENDPOINT
+            }
+            if (context.includes(CONFIG_CONTEXT_KEYWORDS.ROUTE)) {
+                return CONSTANT_NAMES.ROUTE_PATH
+            }
+            if (context.includes(CONFIG_CONTEXT_KEYWORDS.CONNECTION)) {
+                return CONSTANT_NAMES.CONNECTION_STRING
+            }
+            return CONSTANT_NAMES.CONFIG_VALUE
+        }

        if (value.includes(SUGGESTION_KEYWORDS.HTTP)) {
            return CONSTANT_NAMES.API_BASE_URL
@@ -135,6 +367,23 @@ export class HardcodedValue extends ValueObject<HardcodedValueProps> {
        }

        const context = this.props.context.toLowerCase()
+        const valueType = this.props.valueType
+
+        if (valueType === "api_key" || valueType === "url" || valueType === "ip_address") {
+            return LOCATIONS.CONFIG_ENVIRONMENT
+        }
+
+        if (valueType === "email") {
+            return LOCATIONS.CONFIG_CONTACTS
+        }
+
+        if (valueType === "file_path") {
+            return LOCATIONS.CONFIG_PATHS
+        }
+
+        if (valueType === "date") {
+            return LOCATIONS.CONFIG_DATES
+        }

        if (
            context.includes(SUGGESTION_KEYWORDS.ENTITY) ||
@@ -153,4 +402,122 @@ export class HardcodedValue extends ValueObject<HardcodedValueProps> {

        return LOCATIONS.SHARED_CONSTANTS
    }
+
+    public getDetailedSuggestion(currentLayer?: string): string {
+        const constantName = this.suggestConstantName()
+        const location = this.suggestLocation(currentLayer)
+        const valueTypeLabel = this.valueType ? ` (${this.valueType})` : ""
+
+        let suggestion = `Extract${valueTypeLabel} to constant ${constantName} in ${location}`
+
+        if (this.isAlmostConstant() && this.withinFileUsageCount) {
+            suggestion += `. This value appears ${String(this.withinFileUsageCount)} times in this file`
+        }
+
+        if (this.hasDuplicates() && this.duplicateLocations) {
+            const count = this.duplicateLocations.length
+            const fileList = this.duplicateLocations
+                .slice(0, 3)
+                .map((loc) => `${loc.file}:${String(loc.line)}`)
+                .join(", ")
+
+            const more = count > 3 ? ` and ${String(count - 3)} more` : ""
+            suggestion += `. Also duplicated in ${String(count)} other file(s): ${fileList}${more}`
+        }
+
+        return suggestion
+    }
+
+    /**
+     * Analyzes variable name and context to determine importance
+     */
+    public getImportance(): ValueImportance {
+        const context = this.props.context.toLowerCase()
+        const valueType = this.props.valueType
+
+        if (valueType === "api_key") {
+            return "critical"
+        }
+
+        const criticalKeywords = [
+            ...DETECTION_PATTERNS.SENSITIVE_KEYWORDS,
+            ...DETECTION_PATTERNS.BUSINESS_KEYWORDS,
+            "key",
+            "age",
+        ]
+
+        if (criticalKeywords.some((keyword) => context.includes(keyword))) {
+            return "critical"
+        }
+
+        const highKeywords = [...DETECTION_PATTERNS.TECHNICAL_KEYWORDS, "db", "api"]
+
+        if (highKeywords.some((keyword) => context.includes(keyword))) {
+            return "high"
+        }
+
+        if (valueType === "url" || valueType === "ip_address" || valueType === "email") {
+            return "high"
+        }
+
+        const mediumKeywords = DETECTION_PATTERNS.MEDIUM_KEYWORDS
+
+        if (mediumKeywords.some((keyword) => context.includes(keyword))) {
+            return "medium"
+        }
+
+        const lowKeywords = DETECTION_PATTERNS.UI_KEYWORDS
+
+        if (lowKeywords.some((keyword) => context.includes(keyword))) {
+            return "low"
+        }
+
+        return "medium"
+    }
+
+    /**
+     * Checks if this violation should be skipped based on layer strictness
+     *
+     * Different layers have different tolerance levels:
+     * - domain: strictest (no hardcoded values allowed)
+     * - application: strict (only low importance allowed)
+     * - infrastructure: moderate (low and some medium allowed)
+     * - cli: lenient (UI constants allowed)
+     */
+    public shouldSkip(layer?: string): boolean {
+        if (!layer) {
+            return false
+        }
+
+        const importance = this.getImportance()
+
+        if (layer === "domain") {
+            return false
+        }
+
+        if (layer === "application") {
+            return false
+        }
+
+        if (layer === "infrastructure") {
+            return importance === "low" && this.isUIConstant()
+        }
+
+        if (layer === "cli") {
+            return importance === "low" && this.isUIConstant()
+        }
+
+        return false
+    }
+
+    /**
+     * Checks if this value is a UI-related constant
+     */
+    private isUIConstant(): boolean {
+        const context = this.props.context.toLowerCase()
+
+        const uiKeywords = DETECTION_PATTERNS.UI_KEYWORDS
+
+        return uiKeywords.some((keyword) => context.includes(keyword))
+    }
 }
--- a/packages/guardian/src/domain/value-objects/RepositoryViolation.ts
+++ b/packages/guardian/src/domain/value-objects/RepositoryViolation.ts
@@ -0,0 +1,297 @@
+import { ValueObject } from "./ValueObject"
+import { REPOSITORY_VIOLATION_TYPES } from "../../shared/constants/rules"
+import {
+    REPOSITORY_FALLBACK_SUGGESTIONS,
+    REPOSITORY_PATTERN_MESSAGES,
+    VIOLATION_EXAMPLE_VALUES,
+} from "../constants/Messages"
+
+interface RepositoryViolationProps {
+    readonly violationType:
+        | typeof REPOSITORY_VIOLATION_TYPES.ORM_TYPE_IN_INTERFACE
+        | typeof REPOSITORY_VIOLATION_TYPES.CONCRETE_REPOSITORY_IN_USE_CASE
+        | typeof REPOSITORY_VIOLATION_TYPES.NEW_REPOSITORY_IN_USE_CASE
+        | typeof REPOSITORY_VIOLATION_TYPES.NON_DOMAIN_METHOD_NAME
+    readonly filePath: string
+    readonly layer: string
+    readonly line?: number
+    readonly details: string
+    readonly ormType?: string
+    readonly repositoryName?: string
+    readonly methodName?: string
+}
+
+/**
+ * Represents a Repository Pattern violation in the codebase
+ *
+ * Repository Pattern violations occur when:
+ * 1. Repository interfaces contain ORM-specific types
+ * 2. Use cases depend on concrete repository implementations instead of interfaces
+ * 3. Repositories are instantiated with 'new' in use cases
+ * 4. Repository methods use technical names instead of domain language
+ *
+ * @example
+ * ```typescript
+ * // Violation: ORM type in interface
+ * const violation = RepositoryViolation.create(
+ *     'orm-type-in-interface',
+ *     'src/domain/repositories/IUserRepository.ts',
+ *     'domain',
+ *     15,
+ *     'Repository interface uses Prisma-specific type',
+ *     'Prisma.UserWhereInput'
+ * )
+ * ```
+ */
+export class RepositoryViolation extends ValueObject<RepositoryViolationProps> {
+    private constructor(props: RepositoryViolationProps) {
+        super(props)
+    }
+
+    public static create(
+        violationType:
+            | typeof REPOSITORY_VIOLATION_TYPES.ORM_TYPE_IN_INTERFACE
+            | typeof REPOSITORY_VIOLATION_TYPES.CONCRETE_REPOSITORY_IN_USE_CASE
+            | typeof REPOSITORY_VIOLATION_TYPES.NEW_REPOSITORY_IN_USE_CASE
+            | typeof REPOSITORY_VIOLATION_TYPES.NON_DOMAIN_METHOD_NAME,
+        filePath: string,
+        layer: string,
+        line: number | undefined,
+        details: string,
+        ormType?: string,
+        repositoryName?: string,
+        methodName?: string,
+    ): RepositoryViolation {
+        return new RepositoryViolation({
+            violationType,
+            filePath,
+            layer,
+            line,
+            details,
+            ormType,
+            repositoryName,
+            methodName,
+        })
+    }
+
+    public get violationType(): string {
+        return this.props.violationType
+    }
+
+    public get filePath(): string {
+        return this.props.filePath
+    }
+
+    public get layer(): string {
+        return this.props.layer
+    }
+
+    public get line(): number | undefined {
+        return this.props.line
+    }
+
+    public get details(): string {
+        return this.props.details
+    }
+
+    public get ormType(): string | undefined {
+        return this.props.ormType
+    }
+
+    public get repositoryName(): string | undefined {
+        return this.props.repositoryName
+    }
+
+    public get methodName(): string | undefined {
+        return this.props.methodName
+    }
+
+    public getMessage(): string {
+        switch (this.props.violationType) {
+            case REPOSITORY_VIOLATION_TYPES.ORM_TYPE_IN_INTERFACE:
+                return `Repository interface uses ORM-specific type '${this.props.ormType || VIOLATION_EXAMPLE_VALUES.UNKNOWN}'. Domain should not depend on infrastructure concerns.`
+
+            case REPOSITORY_VIOLATION_TYPES.CONCRETE_REPOSITORY_IN_USE_CASE:
+                return `Use case depends on concrete repository '${this.props.repositoryName || VIOLATION_EXAMPLE_VALUES.UNKNOWN}' instead of interface. Use dependency inversion.`
+
+            case REPOSITORY_VIOLATION_TYPES.NEW_REPOSITORY_IN_USE_CASE:
+                return `Use case creates repository with 'new ${this.props.repositoryName || "Repository"}()'. Use dependency injection instead.`
+
+            case REPOSITORY_VIOLATION_TYPES.NON_DOMAIN_METHOD_NAME:
+                return `Repository method '${this.props.methodName || VIOLATION_EXAMPLE_VALUES.UNKNOWN}' uses technical name. Use domain language instead.`
+
+            default:
+                return `Repository pattern violation: ${this.props.details}`
+        }
+    }
+
+    public getSuggestion(): string {
+        switch (this.props.violationType) {
+            case REPOSITORY_VIOLATION_TYPES.ORM_TYPE_IN_INTERFACE:
+                return this.getOrmTypeSuggestion()
+
+            case REPOSITORY_VIOLATION_TYPES.CONCRETE_REPOSITORY_IN_USE_CASE:
+                return this.getConcreteRepositorySuggestion()
+
+            case REPOSITORY_VIOLATION_TYPES.NEW_REPOSITORY_IN_USE_CASE:
+                return this.getNewRepositorySuggestion()
+
+            case REPOSITORY_VIOLATION_TYPES.NON_DOMAIN_METHOD_NAME:
+                return this.getNonDomainMethodSuggestion()
+
+            default:
+                return REPOSITORY_PATTERN_MESSAGES.DEFAULT_SUGGESTION
+        }
+    }
+
+    private getOrmTypeSuggestion(): string {
+        return [
+            REPOSITORY_PATTERN_MESSAGES.STEP_REMOVE_ORM_TYPES,
+            REPOSITORY_PATTERN_MESSAGES.STEP_USE_DOMAIN_TYPES,
+            REPOSITORY_PATTERN_MESSAGES.STEP_KEEP_CLEAN,
+            "",
+            REPOSITORY_PATTERN_MESSAGES.EXAMPLE_PREFIX,
+            REPOSITORY_PATTERN_MESSAGES.BAD_ORM_EXAMPLE,
+            REPOSITORY_PATTERN_MESSAGES.GOOD_DOMAIN_EXAMPLE,
+        ].join("\n")
+    }
+
+    private getConcreteRepositorySuggestion(): string {
+        return [
+            REPOSITORY_PATTERN_MESSAGES.STEP_DEPEND_ON_INTERFACE,
+            REPOSITORY_PATTERN_MESSAGES.STEP_MOVE_TO_INFRASTRUCTURE,
+            REPOSITORY_PATTERN_MESSAGES.STEP_USE_DI,
+            "",
+            REPOSITORY_PATTERN_MESSAGES.EXAMPLE_PREFIX,
+            `❌ Bad: constructor(private repo: ${this.props.repositoryName || VIOLATION_EXAMPLE_VALUES.USER_REPOSITORY})`,
+            `✅ Good: constructor(private repo: I${this.props.repositoryName?.replace(/^.*?([A-Z]\w+)$/, "$1") || VIOLATION_EXAMPLE_VALUES.USER_REPOSITORY})`,
+        ].join("\n")
+    }
+
+    private getNewRepositorySuggestion(): string {
+        return [
+            REPOSITORY_PATTERN_MESSAGES.STEP_REMOVE_NEW,
+            REPOSITORY_PATTERN_MESSAGES.STEP_INJECT_CONSTRUCTOR,
+            REPOSITORY_PATTERN_MESSAGES.STEP_CONFIGURE_DI,
+            "",
+            REPOSITORY_PATTERN_MESSAGES.EXAMPLE_PREFIX,
+            REPOSITORY_PATTERN_MESSAGES.BAD_NEW_REPO,
+            REPOSITORY_PATTERN_MESSAGES.GOOD_INJECT_REPO,
+        ].join("\n")
+    }
+
+    private getNonDomainMethodSuggestion(): string {
+        const detailsMatch = /Consider: (.+)$/.exec(this.props.details)
+        const smartSuggestion = detailsMatch ? detailsMatch[1] : null
+
+        const technicalToDomain = {
+            findOne: REPOSITORY_PATTERN_MESSAGES.SUGGESTION_FINDONE,
+            findMany: REPOSITORY_PATTERN_MESSAGES.SUGGESTION_FINDMANY,
+            insert: REPOSITORY_PATTERN_MESSAGES.SUGGESTION_INSERT,
+            update: REPOSITORY_PATTERN_MESSAGES.SUGGESTION_UPDATE,
+            delete: REPOSITORY_PATTERN_MESSAGES.SUGGESTION_DELETE,
+            query: REPOSITORY_PATTERN_MESSAGES.SUGGESTION_QUERY,
+        }
+
+        const fallbackSuggestion =
+            technicalToDomain[this.props.methodName as keyof typeof technicalToDomain]
+        const finalSuggestion =
+            smartSuggestion || fallbackSuggestion || REPOSITORY_FALLBACK_SUGGESTIONS.DEFAULT
+
+        return [
+            REPOSITORY_PATTERN_MESSAGES.STEP_RENAME_METHOD,
+            REPOSITORY_PATTERN_MESSAGES.STEP_REFLECT_BUSINESS,
+            REPOSITORY_PATTERN_MESSAGES.STEP_AVOID_TECHNICAL,
+            "",
+            REPOSITORY_PATTERN_MESSAGES.EXAMPLE_PREFIX,
+            `❌ Bad: ${this.props.methodName || VIOLATION_EXAMPLE_VALUES.FIND_ONE}()`,
+            `✅ Good: ${finalSuggestion}`,
+        ].join("\n")
+    }
+
+    public getExampleFix(): string {
+        switch (this.props.violationType) {
+            case REPOSITORY_VIOLATION_TYPES.ORM_TYPE_IN_INTERFACE:
+                return this.getOrmTypeExample()
+
+            case REPOSITORY_VIOLATION_TYPES.CONCRETE_REPOSITORY_IN_USE_CASE:
+                return this.getConcreteRepositoryExample()
+
+            case REPOSITORY_VIOLATION_TYPES.NEW_REPOSITORY_IN_USE_CASE:
+                return this.getNewRepositoryExample()
+
+            case REPOSITORY_VIOLATION_TYPES.NON_DOMAIN_METHOD_NAME:
+                return this.getNonDomainMethodExample()
+
+            default:
+                return REPOSITORY_PATTERN_MESSAGES.NO_EXAMPLE
+        }
+    }
+
+    private getOrmTypeExample(): string {
+        return `
+// ❌ BAD: ORM-specific interface
+// domain/repositories/IUserRepository.ts
+interface IUserRepository {
+    findOne(query: { where: { id: string } })  // Prisma-specific
+    create(data: UserCreateInput)  // ORM types in domain
+}
+
+// ✅ GOOD: Clean domain interface
+interface IUserRepository {
+    findById(id: UserId): Promise<User | null>
+    save(user: User): Promise<void>
+    delete(id: UserId): Promise<void>
+}`
+    }
+
+    private getConcreteRepositoryExample(): string {
+        return `
+// ❌ BAD: Use Case with concrete implementation
+class CreateUser {
+    constructor(private prisma: PrismaClient) {}  // VIOLATION!
+}
+
+// ✅ GOOD: Use Case with interface
+class CreateUser {
+    constructor(private userRepo: IUserRepository) {}  // OK
+}`
+    }
+
+    private getNewRepositoryExample(): string {
+        return `
+// ❌ BAD: Creating repository in use case
+class CreateUser {
+    async execute(data: CreateUserRequest) {
+        const repo = new UserRepository()  // VIOLATION!
+        await repo.save(user)
+    }
+}
+
+// ✅ GOOD: Inject repository via constructor
+class CreateUser {
+    constructor(private readonly userRepo: IUserRepository) {}
+
+    async execute(data: CreateUserRequest) {
+        await this.userRepo.save(user)  // OK
+    }
+}`
+    }
+
+    private getNonDomainMethodExample(): string {
+        return `
+// ❌ BAD: Technical method names
+interface IUserRepository {
+    findOne(id: string)  // Database terminology
+    insert(user: User)   // SQL terminology
+    query(filter: any)   // Technical term
+}
+
+// ✅ GOOD: Domain language
+interface IUserRepository {
+    findById(id: UserId): Promise<User | null>
+    save(user: User): Promise<void>
+    findByEmail(email: Email): Promise<User | null>
+}`
+    }
+}
--- a/packages/guardian/src/domain/value-objects/SecretViolation.ts
+++ b/packages/guardian/src/domain/value-objects/SecretViolation.ts
@@ -0,0 +1,204 @@
+import { ValueObject } from "./ValueObject"
+import { SECRET_VIOLATION_MESSAGES } from "../constants/Messages"
+import { SEVERITY_LEVELS } from "../../shared/constants"
+import { FILE_ENCODING, SECRET_EXAMPLE_VALUES, SECRET_KEYWORDS } from "../constants/SecretExamples"
+
+interface SecretViolationProps {
+    readonly file: string
+    readonly line: number
+    readonly column: number
+    readonly secretType: string
+    readonly matchedPattern: string
+}
+
+/**
+ * Represents a secret exposure violation in the codebase
+ *
+ * Secret violations occur when sensitive data like API keys, tokens, passwords,
+ * or credentials are hardcoded in the source code instead of being stored
+ * in secure environment variables or secret management systems.
+ *
+ * All secret violations are marked as CRITICAL severity because they represent
+ * serious security risks that could lead to unauthorized access, data breaches,
+ * or service compromise.
+ *
+ * @example
+ * ```typescript
+ * const violation = SecretViolation.create(
+ *     'src/config/aws.ts',
+ *     10,
+ *     15,
+ *     'AWS Access Key',
+ *     'AKIA1234567890ABCDEF'
+ * )
+ *
+ * console.log(violation.getMessage())
+ * // "Hardcoded AWS Access Key detected"
+ *
+ * console.log(violation.getSeverity())
+ * // "critical"
+ * ```
+ */
+export class SecretViolation extends ValueObject<SecretViolationProps> {
+    private constructor(props: SecretViolationProps) {
+        super(props)
+    }
+
+    public static create(
+        file: string,
+        line: number,
+        column: number,
+        secretType: string,
+        matchedPattern: string,
+    ): SecretViolation {
+        return new SecretViolation({
+            file,
+            line,
+            column,
+            secretType,
+            matchedPattern,
+        })
+    }
+
+    public get file(): string {
+        return this.props.file
+    }
+
+    public get line(): number {
+        return this.props.line
+    }
+
+    public get column(): number {
+        return this.props.column
+    }
+
+    public get secretType(): string {
+        return this.props.secretType
+    }
+
+    public get matchedPattern(): string {
+        return this.props.matchedPattern
+    }
+
+    public getMessage(): string {
+        return `Hardcoded ${this.props.secretType} detected`
+    }
+
+    public getSuggestion(): string {
+        const suggestions: string[] = [
+            SECRET_VIOLATION_MESSAGES.USE_ENV_VARIABLES,
+            SECRET_VIOLATION_MESSAGES.USE_SECRET_MANAGER,
+            SECRET_VIOLATION_MESSAGES.NEVER_COMMIT_SECRETS,
+            SECRET_VIOLATION_MESSAGES.ROTATE_IF_EXPOSED,
+            SECRET_VIOLATION_MESSAGES.USE_GITIGNORE,
+        ]
+
+        return suggestions.join("\n")
+    }
+
+    public getExampleFix(): string {
+        return this.getExampleFixForSecretType(this.props.secretType)
+    }
+
+    public getSeverity(): typeof SEVERITY_LEVELS.CRITICAL {
+        return SEVERITY_LEVELS.CRITICAL
+    }
+
+    private getExampleFixForSecretType(secretType: string): string {
+        const lowerType = secretType.toLowerCase()
+
+        if (lowerType.includes(SECRET_KEYWORDS.AWS)) {
+            return `
+// ❌ Bad: Hardcoded AWS credentials
+const AWS_ACCESS_KEY_ID = "${SECRET_EXAMPLE_VALUES.AWS_ACCESS_KEY_ID}"
+const AWS_SECRET_ACCESS_KEY = "${SECRET_EXAMPLE_VALUES.AWS_SECRET_ACCESS_KEY}"
+
+// ✅ Good: Use environment variables
+const AWS_ACCESS_KEY_ID = process.env.AWS_ACCESS_KEY_ID
+const AWS_SECRET_ACCESS_KEY = process.env.AWS_SECRET_ACCESS_KEY
+
+// ✅ Good: Use credentials provider (in infrastructure layer)
+// Load credentials from environment or credentials file`
+        }
+
+        if (lowerType.includes(SECRET_KEYWORDS.GITHUB)) {
+            return `
+// ❌ Bad: Hardcoded GitHub token
+const GITHUB_TOKEN = "${SECRET_EXAMPLE_VALUES.GITHUB_TOKEN}"
+
+// ✅ Good: Use environment variables
+const GITHUB_TOKEN = process.env.GITHUB_TOKEN
+
+// ✅ Good: GitHub Apps with temporary tokens
+// Use GitHub Apps for automated workflows instead of personal access tokens`
+        }
+
+        if (lowerType.includes(SECRET_KEYWORDS.NPM)) {
+            return `
+// ❌ Bad: Hardcoded NPM token in code
+const NPM_TOKEN = "${SECRET_EXAMPLE_VALUES.NPM_TOKEN}"
+
+// ✅ Good: Use .npmrc file (add to .gitignore)
+// .npmrc
+//registry.npmjs.org/:_authToken=\${NPM_TOKEN}
+
+// ✅ Good: Use environment variable
+const NPM_TOKEN = process.env.NPM_TOKEN`
+        }
+
+        if (
+            lowerType.includes(SECRET_KEYWORDS.SSH) ||
+            lowerType.includes(SECRET_KEYWORDS.PRIVATE_KEY)
+        ) {
+            return `
+// ❌ Bad: Hardcoded SSH private key
+const privateKey = \`-----BEGIN RSA PRIVATE KEY-----
+MIIEpAIBAAKCAQEA...\`
+
+// ✅ Good: Load from secure file (not in repository)
+import fs from "fs"
+const privateKey = fs.readFileSync(process.env.SSH_KEY_PATH, "${FILE_ENCODING.UTF8}")
+
+// ✅ Good: Use SSH agent
+// Configure SSH agent to handle keys securely`
+        }
+
+        if (lowerType.includes(SECRET_KEYWORDS.SLACK)) {
+            return `
+// ❌ Bad: Hardcoded Slack token
+const SLACK_TOKEN = "${SECRET_EXAMPLE_VALUES.SLACK_TOKEN}"
+
+// ✅ Good: Use environment variables
+const SLACK_TOKEN = process.env.SLACK_BOT_TOKEN
+
+// ✅ Good: Use OAuth flow for user tokens
+// Implement OAuth 2.0 flow instead of hardcoding tokens`
+        }
+
+        if (
+            lowerType.includes(SECRET_KEYWORDS.API_KEY) ||
+            lowerType.includes(SECRET_KEYWORDS.APIKEY)
+        ) {
+            return `
+// ❌ Bad: Hardcoded API key
+const API_KEY = "${SECRET_EXAMPLE_VALUES.API_KEY}"
+
+// ✅ Good: Use environment variables
+const API_KEY = process.env.API_KEY
+
+// ✅ Good: Use secret management service (in infrastructure layer)
+// AWS Secrets Manager, HashiCorp Vault, Azure Key Vault
+// Implement secret retrieval in infrastructure and inject via DI`
+        }
+
+        return `
+// ❌ Bad: Hardcoded secret
+const SECRET = "${SECRET_EXAMPLE_VALUES.HARDCODED_SECRET}"
+
+// ✅ Good: Use environment variables
+const SECRET = process.env.SECRET_KEY
+
+// ✅ Good: Use secret management
+// AWS Secrets Manager, HashiCorp Vault, Azure Key Vault, etc.`
+    }
+}
--- a/packages/guardian/src/index.ts
+++ b/packages/guardian/src/index.ts
@@ -1,3 +1,7 @@
+import pkg from "../package.json"
+
+export const VERSION = pkg.version
+
 export * from "./domain"
 export * from "./application"
 export * from "./infrastructure"
--- a/packages/guardian/src/infrastructure/analyzers/AggregateBoundaryDetector.ts
+++ b/packages/guardian/src/infrastructure/analyzers/AggregateBoundaryDetector.ts
@@ -0,0 +1,167 @@
+import { IAggregateBoundaryDetector } from "../../domain/services/IAggregateBoundaryDetector"
+import { AggregateBoundaryViolation } from "../../domain/value-objects/AggregateBoundaryViolation"
+import { LAYERS } from "../../shared/constants/rules"
+import { AggregatePathAnalyzer } from "../strategies/AggregatePathAnalyzer"
+import { FolderRegistry } from "../strategies/FolderRegistry"
+import { ImportValidator } from "../strategies/ImportValidator"
+
+/**
+ * Detects aggregate boundary violations in Domain-Driven Design
+ *
+ * This detector enforces DDD aggregate rules:
+ * - Aggregates should reference each other only by ID or Value Objects
+ * - Direct entity references across aggregates create tight coupling
+ * - Each aggregate should be independently modifiable
+ *
+ * Folder structure patterns detected:
+ * - domain/aggregates/order/Order.ts
+ * - domain/order/Order.ts (aggregate name from parent folder)
+ * - domain/entities/order/Order.ts
+ *
+ * @example
+ * ```typescript
+ * const detector = new AggregateBoundaryDetector()
+ *
+ * // Detect violations in order aggregate
+ * const code = `
+ * import { User } from '../user/User'
+ * import { UserId } from '../user/value-objects/UserId'
+ * `
+ * const violations = detector.detectViolations(
+ *     code,
+ *     'src/domain/aggregates/order/Order.ts',
+ *     'domain'
+ * )
+ *
+ * // violations will contain 1 violation for direct User entity import
+ * // but not for UserId (value object is allowed)
+ * console.log(violations.length) // 1
+ * ```
+ */
+export class AggregateBoundaryDetector implements IAggregateBoundaryDetector {
+    private readonly folderRegistry: FolderRegistry
+    private readonly pathAnalyzer: AggregatePathAnalyzer
+    private readonly importValidator: ImportValidator
+
+    constructor() {
+        this.folderRegistry = new FolderRegistry()
+        this.pathAnalyzer = new AggregatePathAnalyzer(this.folderRegistry)
+        this.importValidator = new ImportValidator(this.folderRegistry, this.pathAnalyzer)
+    }
+
+    /**
+     * Detects aggregate boundary violations in the given code
+     *
+     * Analyzes import statements to identify direct entity references
+     * across aggregate boundaries in the domain layer.
+     *
+     * @param code - Source code to analyze
+     * @param filePath - Path to the file being analyzed
+     * @param layer - The architectural layer of the file (should be 'domain')
+     * @returns Array of detected aggregate boundary violations
+     */
+    public detectViolations(
+        code: string,
+        filePath: string,
+        layer: string | undefined,
+    ): AggregateBoundaryViolation[] {
+        if (layer !== LAYERS.DOMAIN) {
+            return []
+        }
+
+        const currentAggregate = this.pathAnalyzer.extractAggregateFromPath(filePath)
+        if (!currentAggregate) {
+            return []
+        }
+
+        return this.analyzeImports(code, filePath, currentAggregate)
+    }
+
+    /**
+     * Checks if a file path belongs to an aggregate
+     *
+     * Extracts aggregate name from paths like:
+     * - domain/aggregates/order/Order.ts → 'order'
+     * - domain/order/Order.ts → 'order'
+     * - domain/entities/order/Order.ts → 'order'
+     *
+     * @param filePath - The file path to check
+     * @returns The aggregate name if found, undefined otherwise
+     */
+    public extractAggregateFromPath(filePath: string): string | undefined {
+        return this.pathAnalyzer.extractAggregateFromPath(filePath)
+    }
+
+    /**
+     * Checks if an import path references an entity from another aggregate
+     *
+     * @param importPath - The import path to analyze
+     * @param currentAggregate - The aggregate of the current file
+     * @returns True if the import crosses aggregate boundaries inappropriately
+     */
+    public isAggregateBoundaryViolation(importPath: string, currentAggregate: string): boolean {
+        return this.importValidator.isViolation(importPath, currentAggregate)
+    }
+
+    /**
+     * Analyzes all imports in code and detects violations
+     */
+    private analyzeImports(
+        code: string,
+        filePath: string,
+        currentAggregate: string,
+    ): AggregateBoundaryViolation[] {
+        const violations: AggregateBoundaryViolation[] = []
+        const lines = code.split("\n")
+
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i]
+            const lineNumber = i + 1
+
+            const imports = this.importValidator.extractImports(line)
+            for (const importPath of imports) {
+                const violation = this.checkImport(
+                    importPath,
+                    currentAggregate,
+                    filePath,
+                    lineNumber,
+                )
+                if (violation) {
+                    violations.push(violation)
+                }
+            }
+        }
+
+        return violations
+    }
+
+    /**
+     * Checks a single import for boundary violations
+     */
+    private checkImport(
+        importPath: string,
+        currentAggregate: string,
+        filePath: string,
+        lineNumber: number,
+    ): AggregateBoundaryViolation | undefined {
+        if (!this.importValidator.isViolation(importPath, currentAggregate)) {
+            return undefined
+        }
+
+        const targetAggregate = this.pathAnalyzer.extractAggregateFromImport(importPath)
+        const entityName = this.pathAnalyzer.extractEntityName(importPath)
+
+        if (targetAggregate && entityName) {
+            return AggregateBoundaryViolation.create(
+                currentAggregate,
+                targetAggregate,
+                entityName,
+                importPath,
+                filePath,
+                lineNumber,
+            )
+        }
+
+        return undefined
+    }
+}
--- a/packages/guardian/src/infrastructure/analyzers/AnemicModelDetector.ts
+++ b/packages/guardian/src/infrastructure/analyzers/AnemicModelDetector.ts
@@ -0,0 +1,318 @@
+import { IAnemicModelDetector } from "../../domain/services/IAnemicModelDetector"
+import { AnemicModelViolation } from "../../domain/value-objects/AnemicModelViolation"
+import { CLASS_KEYWORDS } from "../../shared/constants"
+import { ANALYZER_DEFAULTS, ANEMIC_MODEL_FLAGS, LAYERS } from "../../shared/constants/rules"
+
+/**
+ * Detects anemic domain model violations
+ *
+ * This detector identifies entities that lack business logic and contain
+ * only getters/setters. Anemic models violate Domain-Driven Design principles.
+ *
+ * @example
+ * ```typescript
+ * const detector = new AnemicModelDetector()
+ *
+ * // Detect anemic models in entity file
+ * const code = `
+ * class Order {
+ *     getStatus() { return this.status }
+ *     setStatus(status: string) { this.status = status }
+ *     getTotal() { return this.total }
+ *     setTotal(total: number) { this.total = total }
+ * }
+ * `
+ * const violations = detector.detectAnemicModels(
+ *     code,
+ *     'src/domain/entities/Order.ts',
+ *     'domain'
+ * )
+ *
+ * // violations will contain anemic model violation
+ * console.log(violations.length) // 1
+ * console.log(violations[0].className) // 'Order'
+ * ```
+ */
+export class AnemicModelDetector implements IAnemicModelDetector {
+    private readonly entityPatterns = [/\/entities\//, /\/aggregates\//]
+    private readonly excludePatterns = [
+        /\.test\.ts$/,
+        /\.spec\.ts$/,
+        /Dto\.ts$/,
+        /Request\.ts$/,
+        /Response\.ts$/,
+        /Mapper\.ts$/,
+    ]
+
+    /**
+     * Detects anemic model violations in the given code
+     */
+    public detectAnemicModels(
+        code: string,
+        filePath: string,
+        layer: string | undefined,
+    ): AnemicModelViolation[] {
+        if (!this.shouldAnalyze(filePath, layer)) {
+            return []
+        }
+
+        const violations: AnemicModelViolation[] = []
+        const classes = this.extractClasses(code)
+
+        for (const classInfo of classes) {
+            const violation = this.analyzeClass(classInfo, filePath, layer || LAYERS.DOMAIN)
+            if (violation) {
+                violations.push(violation)
+            }
+        }
+
+        return violations
+    }
+
+    /**
+     * Checks if file should be analyzed
+     */
+    private shouldAnalyze(filePath: string, layer: string | undefined): boolean {
+        if (layer !== LAYERS.DOMAIN) {
+            return false
+        }
+
+        if (this.excludePatterns.some((pattern) => pattern.test(filePath))) {
+            return false
+        }
+
+        return this.entityPatterns.some((pattern) => pattern.test(filePath))
+    }
+
+    /**
+     * Extracts class information from code
+     */
+    private extractClasses(code: string): ClassInfo[] {
+        const classes: ClassInfo[] = []
+        const lines = code.split("\n")
+        let currentClass: { name: string; startLine: number; startIndex: number } | null = null
+        let braceCount = 0
+        let classBody = ""
+
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i]
+
+            if (!currentClass) {
+                const classRegex = /^\s*(?:export\s+)?(?:abstract\s+)?class\s+(\w+)/
+                const classMatch = classRegex.exec(line)
+                if (classMatch) {
+                    currentClass = {
+                        name: classMatch[1],
+                        startLine: i + 1,
+                        startIndex: lines.slice(0, i).join("\n").length,
+                    }
+                    braceCount = 0
+                    classBody = ""
+                }
+            }
+
+            if (currentClass) {
+                for (const char of line) {
+                    if (char === "{") {
+                        braceCount++
+                    } else if (char === "}") {
+                        braceCount--
+                    }
+                }
+
+                if (braceCount > 0) {
+                    classBody = `${classBody}${line}\n`
+                } else if (braceCount === 0 && classBody.length > 0) {
+                    const properties = this.extractProperties(classBody)
+                    const methods = this.extractMethods(classBody)
+
+                    classes.push({
+                        className: currentClass.name,
+                        lineNumber: currentClass.startLine,
+                        properties,
+                        methods,
+                    })
+
+                    currentClass = null
+                    classBody = ""
+                }
+            }
+        }
+
+        return classes
+    }
+
+    /**
+     * Extracts properties from class body
+     */
+    private extractProperties(classBody: string): PropertyInfo[] {
+        const properties: PropertyInfo[] = []
+        const propertyRegex = /(?:private|protected|public|readonly)*\s*(\w+)(?:\?)?:\s*\w+/g
+
+        let match
+        while ((match = propertyRegex.exec(classBody)) !== null) {
+            const propertyName = match[1]
+
+            if (!this.isMethodSignature(match[0])) {
+                properties.push({ name: propertyName })
+            }
+        }
+
+        return properties
+    }
+
+    /**
+     * Extracts methods from class body
+     */
+    private extractMethods(classBody: string): MethodInfo[] {
+        const methods: MethodInfo[] = []
+        const methodRegex =
+            /(public|private|protected)?\s*(get|set)?\s+(\w+)\s*\([^)]*\)(?:\s*:\s*\w+)?/g
+
+        let match
+        while ((match = methodRegex.exec(classBody)) !== null) {
+            const visibility = match[1] || CLASS_KEYWORDS.PUBLIC
+            const accessor = match[2]
+            const methodName = match[3]
+
+            if (methodName === CLASS_KEYWORDS.CONSTRUCTOR) {
+                continue
+            }
+
+            const isGetter = accessor === "get" || this.isGetterMethod(methodName)
+            const isSetter = accessor === "set" || this.isSetterMethod(methodName, classBody)
+            const isPublic = visibility === CLASS_KEYWORDS.PUBLIC || !visibility
+
+            methods.push({
+                name: methodName,
+                isGetter,
+                isSetter,
+                isPublic,
+                isBusinessLogic: !isGetter && !isSetter,
+            })
+        }
+
+        return methods
+    }
+
+    /**
+     * Analyzes class for anemic model violations
+     */
+    private analyzeClass(
+        classInfo: ClassInfo,
+        filePath: string,
+        layer: string,
+    ): AnemicModelViolation | null {
+        const { className, lineNumber, properties, methods } = classInfo
+
+        if (properties.length === 0 && methods.length === 0) {
+            return null
+        }
+
+        const businessMethods = methods.filter((m) => m.isBusinessLogic)
+        const hasOnlyGettersSetters = businessMethods.length === 0 && methods.length > 0
+        const hasPublicSetters = methods.some((m) => m.isSetter && m.isPublic)
+
+        const methodCount = methods.length
+        const propertyCount = properties.length
+
+        if (hasPublicSetters) {
+            return AnemicModelViolation.create(
+                className,
+                filePath,
+                layer,
+                lineNumber,
+                methodCount,
+                propertyCount,
+                ANEMIC_MODEL_FLAGS.HAS_ONLY_GETTERS_SETTERS_FALSE,
+                ANEMIC_MODEL_FLAGS.HAS_PUBLIC_SETTERS_TRUE,
+            )
+        }
+
+        if (hasOnlyGettersSetters && methodCount >= 2 && propertyCount > 0) {
+            return AnemicModelViolation.create(
+                className,
+                filePath,
+                layer,
+                lineNumber,
+                methodCount,
+                propertyCount,
+                ANEMIC_MODEL_FLAGS.HAS_ONLY_GETTERS_SETTERS_TRUE,
+                ANEMIC_MODEL_FLAGS.HAS_PUBLIC_SETTERS_FALSE,
+            )
+        }
+
+        const methodToPropertyRatio = methodCount / Math.max(propertyCount, 1)
+        if (
+            propertyCount > 0 &&
+            businessMethods.length < 2 &&
+            methodToPropertyRatio < 1.0 &&
+            methodCount > 0
+        ) {
+            return AnemicModelViolation.create(
+                className,
+                filePath,
+                layer,
+                lineNumber,
+                methodCount,
+                propertyCount,
+                ANALYZER_DEFAULTS.HAS_ONLY_GETTERS_SETTERS,
+                ANALYZER_DEFAULTS.HAS_PUBLIC_SETTERS,
+            )
+        }
+
+        return null
+    }
+
+    /**
+     * Checks if method name is a getter pattern
+     */
+    private isGetterMethod(methodName: string): boolean {
+        return (
+            methodName.startsWith("get") ||
+            methodName.startsWith("is") ||
+            methodName.startsWith("has")
+        )
+    }
+
+    /**
+     * Checks if method is a setter pattern
+     */
+    private isSetterMethod(methodName: string, _classBody: string): boolean {
+        return methodName.startsWith("set")
+    }
+
+    /**
+     * Checks if property declaration is actually a method signature
+     */
+    private isMethodSignature(propertyDeclaration: string): boolean {
+        return propertyDeclaration.includes("(") && propertyDeclaration.includes(")")
+    }
+
+    /**
+     * Gets line number for a position in code
+     */
+    private getLineNumber(code: string, position: number): number {
+        const lines = code.substring(0, position).split("\n")
+        return lines.length
+    }
+}
+
+interface ClassInfo {
+    className: string
+    lineNumber: number
+    properties: PropertyInfo[]
+    methods: MethodInfo[]
+}
+
+interface PropertyInfo {
+    name: string
+}
+
+interface MethodInfo {
+    name: string
+    isGetter: boolean
+    isSetter: boolean
+    isPublic: boolean
+    isBusinessLogic: boolean
+}
--- a/packages/guardian/src/infrastructure/analyzers/AstTreeTraverser.ts
+++ b/packages/guardian/src/infrastructure/analyzers/AstTreeTraverser.ts
@@ -0,0 +1,104 @@
+import Parser from "tree-sitter"
+import { HardcodedValue } from "../../domain/value-objects/HardcodedValue"
+import { AstBooleanAnalyzer } from "../strategies/AstBooleanAnalyzer"
+import { AstConfigObjectAnalyzer } from "../strategies/AstConfigObjectAnalyzer"
+import { AstNumberAnalyzer } from "../strategies/AstNumberAnalyzer"
+import { AstStringAnalyzer } from "../strategies/AstStringAnalyzer"
+
+/**
+ * AST tree traverser for detecting hardcoded values
+ *
+ * Walks through the Abstract Syntax Tree and uses analyzers
+ * to detect hardcoded numbers, strings, booleans, and configuration objects.
+ * Also tracks value usage to identify "almost constants" - values used 2+ times.
+ */
+export class AstTreeTraverser {
+    constructor(
+        private readonly numberAnalyzer: AstNumberAnalyzer,
+        private readonly stringAnalyzer: AstStringAnalyzer,
+        private readonly booleanAnalyzer: AstBooleanAnalyzer,
+        private readonly configObjectAnalyzer: AstConfigObjectAnalyzer,
+    ) {}
+
+    /**
+     * Traverses the AST tree and collects hardcoded values
+     */
+    public traverse(tree: Parser.Tree, sourceCode: string): HardcodedValue[] {
+        const results: HardcodedValue[] = []
+        const lines = sourceCode.split("\n")
+        const cursor = tree.walk()
+
+        this.visit(cursor, lines, results)
+
+        this.markAlmostConstants(results)
+
+        return results
+    }
+
+    /**
+     * Marks values that appear multiple times in the same file
+     */
+    private markAlmostConstants(results: HardcodedValue[]): void {
+        const valueUsage = new Map<string, number>()
+
+        for (const result of results) {
+            const key = `${result.type}:${String(result.value)}`
+            valueUsage.set(key, (valueUsage.get(key) || 0) + 1)
+        }
+
+        for (let i = 0; i < results.length; i++) {
+            const result = results[i]
+            const key = `${result.type}:${String(result.value)}`
+            const count = valueUsage.get(key) || 0
+
+            if (count >= 2 && !result.withinFileUsageCount) {
+                results[i] = HardcodedValue.create(
+                    result.value,
+                    result.type,
+                    result.line,
+                    result.column,
+                    result.context,
+                    result.valueType,
+                    result.duplicateLocations,
+                    count,
+                )
+            }
+        }
+    }
+
+    /**
+     * Recursively visits AST nodes
+     */
+    private visit(cursor: Parser.TreeCursor, lines: string[], results: HardcodedValue[]): void {
+        const node = cursor.currentNode
+
+        if (node.type === "object") {
+            const violation = this.configObjectAnalyzer.analyze(node, lines)
+            if (violation) {
+                results.push(violation)
+            }
+        } else if (node.type === "number") {
+            const violation = this.numberAnalyzer.analyze(node, lines)
+            if (violation) {
+                results.push(violation)
+            }
+        } else if (node.type === "string") {
+            const violation = this.stringAnalyzer.analyze(node, lines)
+            if (violation) {
+                results.push(violation)
+            }
+        } else if (node.type === "true" || node.type === "false") {
+            const violation = this.booleanAnalyzer.analyze(node, lines)
+            if (violation) {
+                results.push(violation)
+            }
+        }
+
+        if (cursor.gotoFirstChild()) {
+            do {
+                this.visit(cursor, lines, results)
+            } while (cursor.gotoNextSibling())
+            cursor.gotoParent()
+        }
+    }
+}
--- a/packages/guardian/src/infrastructure/analyzers/DependencyDirectionDetector.ts
+++ b/packages/guardian/src/infrastructure/analyzers/DependencyDirectionDetector.ts
@@ -0,0 +1,181 @@
+import { IDependencyDirectionDetector } from "../../domain/services/IDependencyDirectionDetector"
+import { DependencyViolation } from "../../domain/value-objects/DependencyViolation"
+import { LAYERS } from "../../shared/constants/rules"
+import { IMPORT_PATTERNS, LAYER_PATHS } from "../constants/paths"
+
+/**
+ * Detects dependency direction violations between architectural layers
+ *
+ * This detector enforces Clean Architecture dependency rules:
+ * - Domain → should not import from Application or Infrastructure
+ * - Application → should not import from Infrastructure
+ * - Infrastructure → can import from Application and Domain (allowed)
+ * - Shared → can be imported by all layers (allowed)
+ *
+ * @example
+ * ```typescript
+ * const detector = new DependencyDirectionDetector()
+ *
+ * // Detect violations in domain file
+ * const code = `
+ * import { PrismaClient } from '@prisma/client'
+ * import { UserDto } from '../application/dtos/UserDto'
+ * `
+ * const violations = detector.detectViolations(code, 'src/domain/entities/User.ts', 'domain')
+ *
+ * // violations will contain 1 violation for domain importing from application
+ * console.log(violations.length) // 1
+ * console.log(violations[0].getMessage())
+ * // "Domain layer should not import from Application layer"
+ * ```
+ */
+export class DependencyDirectionDetector implements IDependencyDirectionDetector {
+    private readonly dependencyRules: Map<string, Set<string>>
+
+    constructor() {
+        this.dependencyRules = new Map([
+            [LAYERS.DOMAIN, new Set([LAYERS.DOMAIN, LAYERS.SHARED])],
+            [LAYERS.APPLICATION, new Set([LAYERS.DOMAIN, LAYERS.APPLICATION, LAYERS.SHARED])],
+            [
+                LAYERS.INFRASTRUCTURE,
+                new Set([LAYERS.DOMAIN, LAYERS.APPLICATION, LAYERS.INFRASTRUCTURE, LAYERS.SHARED]),
+            ],
+            [
+                LAYERS.SHARED,
+                new Set([LAYERS.DOMAIN, LAYERS.APPLICATION, LAYERS.INFRASTRUCTURE, LAYERS.SHARED]),
+            ],
+        ])
+    }
+
+    /**
+     * Detects dependency direction violations in the given code
+     *
+     * Analyzes import statements to identify violations of dependency rules
+     * between architectural layers.
+     *
+     * @param code - Source code to analyze
+     * @param filePath - Path to the file being analyzed
+     * @param layer - The architectural layer of the file (domain, application, infrastructure, shared)
+     * @returns Array of detected dependency direction violations
+     */
+    public detectViolations(
+        code: string,
+        filePath: string,
+        layer: string | undefined,
+    ): DependencyViolation[] {
+        if (!layer || layer === LAYERS.SHARED) {
+            return []
+        }
+
+        const violations: DependencyViolation[] = []
+        const lines = code.split("\n")
+
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i]
+            const lineNumber = i + 1
+
+            const imports = this.extractImports(line)
+            for (const importPath of imports) {
+                const targetLayer = this.extractLayerFromImport(importPath)
+
+                if (targetLayer && this.isViolation(layer, targetLayer)) {
+                    violations.push(
+                        DependencyViolation.create(
+                            layer,
+                            targetLayer,
+                            importPath,
+                            filePath,
+                            lineNumber,
+                        ),
+                    )
+                }
+            }
+        }
+
+        return violations
+    }
+
+    /**
+     * Checks if an import violates dependency direction rules
+     *
+     * @param fromLayer - The layer that is importing
+     * @param toLayer - The layer being imported
+     * @returns True if the import violates dependency rules
+     */
+    public isViolation(fromLayer: string, toLayer: string): boolean {
+        const allowedDependencies = this.dependencyRules.get(fromLayer)
+
+        if (!allowedDependencies) {
+            return false
+        }
+
+        return !allowedDependencies.has(toLayer)
+    }
+
+    /**
+     * Extracts the layer from an import path
+     *
+     * @param importPath - The import path to analyze
+     * @returns The layer name if detected, undefined otherwise
+     */
+    public extractLayerFromImport(importPath: string): string | undefined {
+        const normalizedPath = importPath.replace(IMPORT_PATTERNS.QUOTE, "").toLowerCase()
+
+        const layerPatterns: [string, string][] = [
+            [LAYERS.DOMAIN, LAYER_PATHS.DOMAIN],
+            [LAYERS.APPLICATION, LAYER_PATHS.APPLICATION],
+            [LAYERS.INFRASTRUCTURE, LAYER_PATHS.INFRASTRUCTURE],
+            [LAYERS.SHARED, LAYER_PATHS.SHARED],
+        ]
+
+        for (const [layer, pattern] of layerPatterns) {
+            if (this.containsLayerPattern(normalizedPath, pattern)) {
+                return layer
+            }
+        }
+
+        return undefined
+    }
+
+    /**
+     * Checks if the normalized path contains the layer pattern
+     */
+    private containsLayerPattern(normalizedPath: string, pattern: string): boolean {
+        return (
+            normalizedPath.includes(pattern) ||
+            normalizedPath.includes(`.${pattern}`) ||
+            normalizedPath.includes(`..${pattern}`) ||
+            normalizedPath.includes(`...${pattern}`)
+        )
+    }
+
+    /**
+     * Extracts import paths from a line of code
+     *
+     * Handles various import statement formats:
+     * - import { X } from 'path'
+     * - import X from 'path'
+     * - import * as X from 'path'
+     * - const X = require('path')
+     *
+     * @param line - A line of code to analyze
+     * @returns Array of import paths found in the line
+     */
+    private extractImports(line: string): string[] {
+        const imports: string[] = []
+
+        let match = IMPORT_PATTERNS.ES_IMPORT.exec(line)
+        while (match) {
+            imports.push(match[1])
+            match = IMPORT_PATTERNS.ES_IMPORT.exec(line)
+        }
+
+        match = IMPORT_PATTERNS.REQUIRE.exec(line)
+        while (match) {
+            imports.push(match[1])
+            match = IMPORT_PATTERNS.REQUIRE.exec(line)
+        }
+
+        return imports
+    }
+}
--- a/packages/guardian/src/infrastructure/analyzers/DuplicateValueTracker.ts
+++ b/packages/guardian/src/infrastructure/analyzers/DuplicateValueTracker.ts
@@ -0,0 +1,122 @@
+import { HardcodedValue } from "../../domain/value-objects/HardcodedValue"
+import type {
+    DuplicateInfo,
+    IDuplicateValueTracker,
+    ValueLocation,
+} from "../../domain/services/IDuplicateValueTracker"
+
+/**
+ * Tracks duplicate hardcoded values across files
+ *
+ * Helps identify values that are used in multiple places
+ * and should be extracted to a shared constant.
+ */
+export class DuplicateValueTracker implements IDuplicateValueTracker {
+    private readonly valueMap = new Map<string, ValueLocation[]>()
+
+    /**
+     * Adds a hardcoded value to tracking
+     */
+    public track(violation: HardcodedValue, filePath: string): void {
+        const key = this.createKey(violation.value, violation.type)
+        const location: ValueLocation = {
+            file: filePath,
+            line: violation.line,
+            context: violation.context,
+        }
+
+        const locations = this.valueMap.get(key)
+        if (!locations) {
+            this.valueMap.set(key, [location])
+        } else {
+            locations.push(location)
+        }
+    }
+
+    /**
+     * Gets all duplicate values (values used in 2+ places)
+     */
+    public getDuplicates(): DuplicateInfo[] {
+        const duplicates: DuplicateInfo[] = []
+
+        for (const [key, locations] of this.valueMap.entries()) {
+            if (locations.length >= 2) {
+                const { value } = this.parseKey(key)
+                duplicates.push({
+                    value,
+                    locations,
+                    count: locations.length,
+                })
+            }
+        }
+
+        return duplicates.sort((a, b) => b.count - a.count)
+    }
+
+    /**
+     * Gets duplicate locations for a specific value
+     */
+    public getDuplicateLocations(
+        value: string | number | boolean,
+        type: string,
+    ): ValueLocation[] | null {
+        const key = this.createKey(value, type)
+        const locations = this.valueMap.get(key)
+
+        if (!locations || locations.length < 2) {
+            return null
+        }
+
+        return locations
+    }
+
+    /**
+     * Checks if a value is duplicated
+     */
+    public isDuplicate(value: string | number | boolean, type: string): boolean {
+        const key = this.createKey(value, type)
+        const locations = this.valueMap.get(key)
+        return locations ? locations.length >= 2 : false
+    }
+
+    /**
+     * Creates a unique key for a value
+     */
+    private createKey(value: string | number | boolean, type: string): string {
+        return `${type}:${String(value)}`
+    }
+
+    /**
+     * Parses a key back to value and type
+     */
+    private parseKey(key: string): { value: string; type: string } {
+        const [type, ...valueParts] = key.split(":")
+        return { value: valueParts.join(":"), type }
+    }
+
+    /**
+     * Gets statistics about duplicates
+     */
+    public getStats(): {
+        totalValues: number
+        duplicateValues: number
+        duplicatePercentage: number
+    } {
+        const totalValues = this.valueMap.size
+        const duplicateValues = this.getDuplicates().length
+        const duplicatePercentage = totalValues > 0 ? (duplicateValues / totalValues) * 100 : 0
+
+        return {
+            totalValues,
+            duplicateValues,
+            duplicatePercentage,
+        }
+    }
+
+    /**
+     * Clears all tracked values
+     */
+    public clear(): void {
+        this.valueMap.clear()
+    }
+}
--- a/packages/guardian/src/infrastructure/analyzers/EntityExposureDetector.ts
+++ b/packages/guardian/src/infrastructure/analyzers/EntityExposureDetector.ts
@@ -0,0 +1,197 @@
+import { IEntityExposureDetector } from "../../domain/services/IEntityExposureDetector"
+import { EntityExposure } from "../../domain/value-objects/EntityExposure"
+import { LAYERS } from "../../shared/constants/rules"
+import { DTO_SUFFIXES, NULLABLE_TYPES, PRIMITIVE_TYPES } from "../constants/type-patterns"
+
+/**
+ * Detects domain entity exposure in controller/route return types
+ *
+ * This detector identifies violations where controllers or route handlers
+ * directly return domain entities instead of using DTOs (Data Transfer Objects).
+ * This violates separation of concerns and can expose internal domain logic.
+ *
+ * @example
+ * ```typescript
+ * const detector = new EntityExposureDetector()
+ *
+ * // Detect exposures in a controller file
+ * const code = `
+ * class UserController {
+ *     async getUser(id: string): Promise<User> {
+ *         return this.userService.findById(id)
+ *     }
+ * }
+ * `
+ * const exposures = detector.detectExposures(code, 'src/infrastructure/controllers/UserController.ts', 'infrastructure')
+ *
+ * // exposures will contain violation for returning User entity
+ * console.log(exposures.length) // 1
+ * console.log(exposures[0].entityName) // 'User'
+ * ```
+ */
+export class EntityExposureDetector implements IEntityExposureDetector {
+    private readonly dtoSuffixes = DTO_SUFFIXES
+    private readonly controllerPatterns = [
+        /Controller/i,
+        /Route/i,
+        /Handler/i,
+        /Resolver/i,
+        /Gateway/i,
+    ]
+
+    /**
+     * Detects entity exposure violations in the given code
+     *
+     * Analyzes method return types in controllers/routes to identify
+     * domain entities being directly exposed to external clients.
+     *
+     * @param code - Source code to analyze
+     * @param filePath - Path to the file being analyzed
+     * @param layer - The architectural layer of the file (domain, application, infrastructure, shared)
+     * @returns Array of detected entity exposure violations
+     */
+    public detectExposures(
+        code: string,
+        filePath: string,
+        layer: string | undefined,
+    ): EntityExposure[] {
+        if (layer !== LAYERS.INFRASTRUCTURE || !this.isControllerFile(filePath)) {
+            return []
+        }
+
+        const exposures: EntityExposure[] = []
+        const lines = code.split("\n")
+
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i]
+            const lineNumber = i + 1
+
+            const methodMatches = this.findMethodReturnTypes(line)
+            for (const match of methodMatches) {
+                const { methodName, returnType } = match
+
+                if (this.isDomainEntity(returnType)) {
+                    exposures.push(
+                        EntityExposure.create(
+                            returnType,
+                            returnType,
+                            filePath,
+                            layer,
+                            lineNumber,
+                            methodName,
+                        ),
+                    )
+                }
+            }
+        }
+
+        return exposures
+    }
+
+    /**
+     * Checks if a return type is a domain entity
+     *
+     * Domain entities are typically PascalCase nouns without Dto/Request/Response suffixes
+     * and are defined in the domain layer.
+     *
+     * @param returnType - The return type to check
+     * @returns True if the return type appears to be a domain entity
+     */
+    public isDomainEntity(returnType: string): boolean {
+        if (!returnType || returnType.trim() === "") {
+            return false
+        }
+
+        const cleanType = this.extractCoreType(returnType)
+
+        if (this.isPrimitiveType(cleanType)) {
+            return false
+        }
+
+        if (this.hasAllowedSuffix(cleanType)) {
+            return false
+        }
+
+        return this.isPascalCase(cleanType)
+    }
+
+    /**
+     * Checks if the file is a controller/route file
+     */
+    private isControllerFile(filePath: string): boolean {
+        return this.controllerPatterns.some((pattern) => pattern.test(filePath))
+    }
+
+    /**
+     * Finds method return types in a line of code
+     */
+    private findMethodReturnTypes(line: string): { methodName: string; returnType: string }[] {
+        const matches: { methodName: string; returnType: string }[] = []
+
+        const methodRegex =
+            /(?:async\s+)?(\w+)\s*\([^)]*\)\s*:\s*Promise<([^>]+)>|(?:async\s+)?(\w+)\s*\([^)]*\)\s*:\s*([A-Z]\w+)/g
+
+        let match
+        while ((match = methodRegex.exec(line)) !== null) {
+            const methodName = match[1] || match[3]
+            const returnType = match[2] || match[4]
+
+            if (methodName && returnType) {
+                matches.push({ methodName, returnType })
+            }
+        }
+
+        return matches
+    }
+
+    /**
+     * Extracts core type from complex type annotations
+     * Examples:
+     * - "Promise<User>" -> "User"
+     * - "User[]" -> "User"
+     * - "User | null" -> "User"
+     */
+    private extractCoreType(returnType: string): string {
+        let cleanType = returnType.trim()
+
+        cleanType = cleanType.replace(/Promise<([^>]+)>/, "$1")
+
+        cleanType = cleanType.replace(/\[\]$/, "")
+
+        if (cleanType.includes("|")) {
+            const types = cleanType.split("|").map((t) => t.trim())
+            const nonNullTypes = types.filter(
+                (t) => !(NULLABLE_TYPES as readonly string[]).includes(t),
+            )
+            if (nonNullTypes.length > 0) {
+                cleanType = nonNullTypes[0]
+            }
+        }
+
+        return cleanType.trim()
+    }
+
+    /**
+     * Checks if a type is a primitive type
+     */
+    private isPrimitiveType(type: string): boolean {
+        return (PRIMITIVE_TYPES as readonly string[]).includes(type.toLowerCase())
+    }
+
+    /**
+     * Checks if a type has an allowed DTO/Response suffix
+     */
+    private hasAllowedSuffix(type: string): boolean {
+        return this.dtoSuffixes.some((suffix) => type.endsWith(suffix))
+    }
+
+    /**
+     * Checks if a string is in PascalCase
+     */
+    private isPascalCase(str: string): boolean {
+        if (!str || str.length === 0) {
+            return false
+        }
+        return /^[A-Z]([a-z0-9]+[A-Z]?)*[a-z0-9]*$/.test(str) && /[a-z]/.test(str)
+    }
+}
--- a/packages/guardian/src/infrastructure/analyzers/HardcodeDetector.ts
+++ b/packages/guardian/src/infrastructure/analyzers/HardcodeDetector.ts
@@ -1,14 +1,29 @@
+import Parser from "tree-sitter"
 import { IHardcodeDetector } from "../../domain/services/IHardcodeDetector"
 import { HardcodedValue } from "../../domain/value-objects/HardcodedValue"
-import { ALLOWED_NUMBERS, CODE_PATTERNS, DETECTION_KEYWORDS } from "../constants/defaults"
-import { HARDCODE_TYPES } from "../../shared/constants"
+import { FILE_EXTENSIONS } from "../../shared/constants"
+import { CodeParser } from "../parsers/CodeParser"
+import { AstBooleanAnalyzer } from "../strategies/AstBooleanAnalyzer"
+import { AstConfigObjectAnalyzer } from "../strategies/AstConfigObjectAnalyzer"
+import { AstContextChecker } from "../strategies/AstContextChecker"
+import { AstNumberAnalyzer } from "../strategies/AstNumberAnalyzer"
+import { AstStringAnalyzer } from "../strategies/AstStringAnalyzer"
+import { ConstantsFileChecker } from "../strategies/ConstantsFileChecker"
+import { AstTreeTraverser } from "./AstTreeTraverser"

 /**
 * Detects hardcoded values (magic numbers and strings) in TypeScript/JavaScript code
 *
- * This detector identifies configuration values, URLs, timeouts, ports, and other
- * constants that should be extracted to configuration files. It uses pattern matching
- * and context analysis to reduce false positives.
+ * This detector uses Abstract Syntax Tree (AST) analysis via tree-sitter to identify
+ * configuration values, URLs, timeouts, ports, and other constants that should be
+ * extracted to configuration files. AST-based detection provides more accurate context
+ * understanding and reduces false positives compared to regex-based approaches.
+ *
+ * The detector uses a modular architecture with specialized components:
+ * - AstContextChecker: Checks if nodes are in specific contexts (exports, types, etc.)
+ * - AstNumberAnalyzer: Analyzes number literals to detect magic numbers
+ * - AstStringAnalyzer: Analyzes string literals to detect magic strings
+ * - AstTreeTraverser: Traverses the AST and coordinates analyzers
 *
 * @example
 * ```typescript
@@ -22,9 +37,27 @@ import { HARDCODE_TYPES } from "../../shared/constants"
 * ```
 */
 export class HardcodeDetector implements IHardcodeDetector {
-    private readonly ALLOWED_NUMBERS = ALLOWED_NUMBERS
+    private readonly constantsChecker: ConstantsFileChecker
+    private readonly parser: CodeParser
+    private readonly traverser: AstTreeTraverser

-    private readonly ALLOWED_STRING_PATTERNS = [/^[a-z]$/i, /^\/$/, /^\\$/, /^\s+$/, /^,$/, /^\.$/]
+    constructor() {
+        this.constantsChecker = new ConstantsFileChecker()
+        this.parser = new CodeParser()
+
+        const contextChecker = new AstContextChecker()
+        const numberAnalyzer = new AstNumberAnalyzer(contextChecker)
+        const stringAnalyzer = new AstStringAnalyzer(contextChecker)
+        const booleanAnalyzer = new AstBooleanAnalyzer(contextChecker)
+        const configObjectAnalyzer = new AstConfigObjectAnalyzer(contextChecker)
+
+        this.traverser = new AstTreeTraverser(
+            numberAnalyzer,
+            stringAnalyzer,
+            booleanAnalyzer,
+            configObjectAnalyzer,
+        )
+    }

    /**
     * Detects all hardcoded values (both numbers and strings) in the given code
@@ -34,342 +67,57 @@ export class HardcodeDetector implements IHardcodeDetector {
     * @returns Array of detected hardcoded values with suggestions
     */
    public detectAll(code: string, filePath: string): HardcodedValue[] {
-        const magicNumbers = this.detectMagicNumbers(code, filePath)
-        const magicStrings = this.detectMagicStrings(code, filePath)
-        return [...magicNumbers, ...magicStrings]
+        if (this.constantsChecker.isConstantsFile(filePath)) {
+            return []
+        }
+
+        const tree = this.parseCode(code, filePath)
+        return this.traverser.traverse(tree, code)
    }

    /**
-     * Check if a line is inside an exported constant definition
-     */
-    private isInExportedConstant(lines: string[], lineIndex: number): boolean {
-        const currentLineTrimmed = lines[lineIndex].trim()
-
-        if (this.isSingleLineExportConst(currentLineTrimmed)) {
-            return true
-        }
-
-        const exportConstStart = this.findExportConstStart(lines, lineIndex)
-        if (exportConstStart === -1) {
-            return false
-        }
-
-        const { braces, brackets } = this.countUnclosedBraces(lines, exportConstStart, lineIndex)
-        return braces > 0 || brackets > 0
-    }
-
-    /**
-     * Check if a line is a single-line export const declaration
-     */
-    private isSingleLineExportConst(line: string): boolean {
-        if (!line.startsWith(CODE_PATTERNS.EXPORT_CONST)) {
-            return false
-        }
-
-        const hasObjectOrArray =
-            line.includes(CODE_PATTERNS.OBJECT_START) || line.includes(CODE_PATTERNS.ARRAY_START)
-
-        if (hasObjectOrArray) {
-            const hasAsConstEnding =
-                line.includes(CODE_PATTERNS.AS_CONST_OBJECT) ||
-                line.includes(CODE_PATTERNS.AS_CONST_ARRAY) ||
-                line.includes(CODE_PATTERNS.AS_CONST_END_SEMICOLON_OBJECT) ||
-                line.includes(CODE_PATTERNS.AS_CONST_END_SEMICOLON_ARRAY)
-
-            return hasAsConstEnding
-        }
-
-        return line.includes(CODE_PATTERNS.AS_CONST)
-    }
-
-    /**
-     * Find the starting line of an export const declaration
-     */
-    private findExportConstStart(lines: string[], lineIndex: number): number {
-        for (let currentLine = lineIndex; currentLine >= 0; currentLine--) {
-            const trimmed = lines[currentLine].trim()
-
-            const isExportConst =
-                trimmed.startsWith(CODE_PATTERNS.EXPORT_CONST) &&
-                (trimmed.includes(CODE_PATTERNS.OBJECT_START) ||
-                    trimmed.includes(CODE_PATTERNS.ARRAY_START))
-
-            if (isExportConst) {
-                return currentLine
-            }
-
-            const isTopLevelStatement =
-                currentLine < lineIndex &&
-                (trimmed.startsWith(CODE_PATTERNS.EXPORT) ||
-                    trimmed.startsWith(CODE_PATTERNS.IMPORT))
-
-            if (isTopLevelStatement) {
-                break
-            }
-        }
-
-        return -1
-    }
-
-    /**
-     * Count unclosed braces and brackets between two line indices
-     */
-    private countUnclosedBraces(
-        lines: string[],
-        startLine: number,
-        endLine: number,
-    ): { braces: number; brackets: number } {
-        let braces = 0
-        let brackets = 0
-
-        for (let i = startLine; i <= endLine; i++) {
-            const line = lines[i]
-            let inString = false
-            let stringChar = ""
-
-            for (let j = 0; j < line.length; j++) {
-                const char = line[j]
-                const prevChar = j > 0 ? line[j - 1] : ""
-
-                if ((char === "'" || char === '"' || char === "`") && prevChar !== "\\") {
-                    if (!inString) {
-                        inString = true
-                        stringChar = char
-                    } else if (char === stringChar) {
-                        inString = false
-                        stringChar = ""
-                    }
-                }
-
-                if (!inString) {
-                    if (char === "{") {
-                        braces++
-                    } else if (char === "}") {
-                        braces--
-                    } else if (char === "[") {
-                        brackets++
-                    } else if (char === "]") {
-                        brackets--
-                    }
-                }
-            }
-        }
-
-        return { braces, brackets }
-    }
-
-    /**
-     * Detects magic numbers in code (timeouts, ports, limits, retries, etc.)
-     *
-     * Skips allowed numbers (-1, 0, 1, 2, 10, 100, 1000) and values in exported constants
+     * Detects magic numbers in code
     *
     * @param code - Source code to analyze
-     * @param _filePath - File path (currently unused, reserved for future use)
+     * @param filePath - File path (used for constants file check)
     * @returns Array of detected magic numbers
     */
-    public detectMagicNumbers(code: string, _filePath: string): HardcodedValue[] {
-        const results: HardcodedValue[] = []
-        const lines = code.split("\n")
+    public detectMagicNumbers(code: string, filePath: string): HardcodedValue[] {
+        if (this.constantsChecker.isConstantsFile(filePath)) {
+            return []
+        }

-        const numberPatterns = [
-            /(?:setTimeout|setInterval)\s*\(\s*[^,]+,\s*(\d+)/g,
-            /(?:maxRetries|retries|attempts)\s*[=:]\s*(\d+)/gi,
-            /(?:limit|max|min)\s*[=:]\s*(\d+)/gi,
-            /(?:port|PORT)\s*[=:]\s*(\d+)/g,
-            /(?:delay|timeout|TIMEOUT)\s*[=:]\s*(\d+)/gi,
-        ]
-
-        lines.forEach((line, lineIndex) => {
-            if (line.trim().startsWith("//") || line.trim().startsWith("*")) {
-                return
-            }
-
-            // Skip lines inside exported constants
-            if (this.isInExportedConstant(lines, lineIndex)) {
-                return
-            }
-
-            numberPatterns.forEach((pattern) => {
-                let match
-                const regex = new RegExp(pattern)
-
-                while ((match = regex.exec(line)) !== null) {
-                    const value = parseInt(match[1], 10)
-
-                    if (!this.ALLOWED_NUMBERS.has(value)) {
-                        results.push(
-                            HardcodedValue.create(
-                                value,
-                                HARDCODE_TYPES.MAGIC_NUMBER,
-                                lineIndex + 1,
-                                match.index,
-                                line.trim(),
-                            ),
-                        )
-                    }
-                }
-            })
-
-            const genericNumberRegex = /\b(\d{3,})\b/g
-            let match
-
-            while ((match = genericNumberRegex.exec(line)) !== null) {
-                const value = parseInt(match[1], 10)
-
-                if (
-                    !this.ALLOWED_NUMBERS.has(value) &&
-                    !this.isInComment(line, match.index) &&
-                    !this.isInString(line, match.index)
-                ) {
-                    const context = this.extractContext(line, match.index)
-                    if (this.looksLikeMagicNumber(context)) {
-                        results.push(
-                            HardcodedValue.create(
-                                value,
-                                HARDCODE_TYPES.MAGIC_NUMBER,
-                                lineIndex + 1,
-                                match.index,
-                                line.trim(),
-                            ),
-                        )
-                    }
-                }
-            }
-        })
-
-        return results
+        const tree = this.parseCode(code, filePath)
+        const allViolations = this.traverser.traverse(tree, code)
+        return allViolations.filter((v) => v.isMagicNumber())
    }

    /**
-     * Detects magic strings in code (URLs, connection strings, error messages, etc.)
-     *
-     * Skips short strings (≤3 chars), console logs, test descriptions, imports,
-     * and values in exported constants
+     * Detects magic strings in code
     *
     * @param code - Source code to analyze
-     * @param _filePath - File path (currently unused, reserved for future use)
+     * @param filePath - File path (used for constants file check)
     * @returns Array of detected magic strings
     */
-    public detectMagicStrings(code: string, _filePath: string): HardcodedValue[] {
-        const results: HardcodedValue[] = []
-        const lines = code.split("\n")
-
-        const stringRegex = /(['"`])(?:(?!\1).)+\1/g
-
-        lines.forEach((line, lineIndex) => {
-            if (
-                line.trim().startsWith("//") ||
-                line.trim().startsWith("*") ||
-                line.includes("import ") ||
-                line.includes("from ")
-            ) {
-                return
-            }
-
-            // Skip lines inside exported constants
-            if (this.isInExportedConstant(lines, lineIndex)) {
-                return
-            }
-
-            let match
-            const regex = new RegExp(stringRegex)
-
-            while ((match = regex.exec(line)) !== null) {
-                const fullMatch = match[0]
-                const value = fullMatch.slice(1, -1)
-
-                // Skip template literals (backtick strings with ${} interpolation)
-                if (fullMatch.startsWith("`") || value.includes("${")) {
-                    continue
-                }
-
-                if (!this.isAllowedString(value) && this.looksLikeMagicString(line, value)) {
-                    results.push(
-                        HardcodedValue.create(
-                            value,
-                            HARDCODE_TYPES.MAGIC_STRING,
-                            lineIndex + 1,
-                            match.index,
-                            line.trim(),
-                        ),
-                    )
-                }
-            }
-        })
-
-        return results
-    }
-
-    private isAllowedString(str: string): boolean {
-        if (str.length <= 1) {
-            return true
+    public detectMagicStrings(code: string, filePath: string): HardcodedValue[] {
+        if (this.constantsChecker.isConstantsFile(filePath)) {
+            return []
        }

-        return this.ALLOWED_STRING_PATTERNS.some((pattern) => pattern.test(str))
+        const tree = this.parseCode(code, filePath)
+        const allViolations = this.traverser.traverse(tree, code)
+        return allViolations.filter((v) => v.isMagicString())
    }

-    private looksLikeMagicString(line: string, value: string): boolean {
-        const lowerLine = line.toLowerCase()
-
-        if (
-            lowerLine.includes(DETECTION_KEYWORDS.TEST) ||
-            lowerLine.includes(DETECTION_KEYWORDS.DESCRIBE)
-        ) {
-            return false
+    /**
+     * Parses code based on file extension
+     */
+    private parseCode(code: string, filePath: string): Parser.Tree {
+        if (filePath.endsWith(FILE_EXTENSIONS.TYPESCRIPT_JSX)) {
+            return this.parser.parseTsx(code)
+        } else if (filePath.endsWith(FILE_EXTENSIONS.TYPESCRIPT)) {
+            return this.parser.parseTypeScript(code)
        }
-
-        if (
-            lowerLine.includes(DETECTION_KEYWORDS.CONSOLE_LOG) ||
-            lowerLine.includes(DETECTION_KEYWORDS.CONSOLE_ERROR)
-        ) {
-            return false
-        }
-
-        if (value.includes(DETECTION_KEYWORDS.HTTP) || value.includes(DETECTION_KEYWORDS.API)) {
-            return true
-        }
-
-        if (/^\d{2,}$/.test(value)) {
-            return false
-        }
-
-        return value.length > 3
-    }
-
-    private looksLikeMagicNumber(context: string): boolean {
-        const lowerContext = context.toLowerCase()
-
-        const configKeywords = [
-            DETECTION_KEYWORDS.TIMEOUT,
-            DETECTION_KEYWORDS.DELAY,
-            DETECTION_KEYWORDS.RETRY,
-            DETECTION_KEYWORDS.LIMIT,
-            DETECTION_KEYWORDS.MAX,
-            DETECTION_KEYWORDS.MIN,
-            DETECTION_KEYWORDS.PORT,
-            DETECTION_KEYWORDS.INTERVAL,
-        ]
-
-        return configKeywords.some((keyword) => lowerContext.includes(keyword))
-    }
-
-    private isInComment(line: string, index: number): boolean {
-        const beforeIndex = line.substring(0, index)
-        return beforeIndex.includes("//") || beforeIndex.includes("/*")
-    }
-
-    private isInString(line: string, index: number): boolean {
-        const beforeIndex = line.substring(0, index)
-        const singleQuotes = (beforeIndex.match(/'/g) ?? []).length
-        const doubleQuotes = (beforeIndex.match(/"/g) ?? []).length
-        const backticks = (beforeIndex.match(/`/g) ?? []).length
-
-        return singleQuotes % 2 !== 0 || doubleQuotes % 2 !== 0 || backticks % 2 !== 0
-    }
-
-    private extractContext(line: string, index: number): string {
-        const start = Math.max(0, index - 30)
-        const end = Math.min(line.length, index + 30)
-        return line.substring(start, end)
+        return this.parser.parseJavaScript(code)
    }
 }
--- a/packages/guardian/src/infrastructure/analyzers/NamingConventionDetector.ts
+++ b/packages/guardian/src/infrastructure/analyzers/NamingConventionDetector.ts
@@ -1,36 +1,72 @@
+import Parser from "tree-sitter"
 import { INamingConventionDetector } from "../../domain/services/INamingConventionDetector"
 import { NamingViolation } from "../../domain/value-objects/NamingViolation"
-import {
-    LAYERS,
-    NAMING_PATTERNS,
-    NAMING_VIOLATION_TYPES,
-    USE_CASE_VERBS,
-} from "../../shared/constants/rules"
-import {
-    EXCLUDED_FILES,
-    FILE_SUFFIXES,
-    NAMING_ERROR_MESSAGES,
-    PATH_PATTERNS,
-    PATTERN_WORDS,
-} from "../constants/detectorPatterns"
+import { FILE_EXTENSIONS } from "../../shared/constants"
+import { EXCLUDED_FILES } from "../constants/detectorPatterns"
+import { CodeParser } from "../parsers/CodeParser"
+import { AstClassNameAnalyzer } from "../strategies/naming/AstClassNameAnalyzer"
+import { AstFunctionNameAnalyzer } from "../strategies/naming/AstFunctionNameAnalyzer"
+import { AstInterfaceNameAnalyzer } from "../strategies/naming/AstInterfaceNameAnalyzer"
+import { AstNamingTraverser } from "../strategies/naming/AstNamingTraverser"
+import { AstVariableNameAnalyzer } from "../strategies/naming/AstVariableNameAnalyzer"

 /**
- * Detects naming convention violations based on Clean Architecture layers
+ * Detects naming convention violations using AST-based analysis
 *
- * This detector ensures that files follow naming conventions appropriate to their layer:
- * - Domain: Entities (nouns), Services (*Service), Value Objects, Repository interfaces (I*Repository)
- * - Application: Use cases (verbs), DTOs (*Dto/*Request/*Response), Mappers (*Mapper)
- * - Infrastructure: Controllers (*Controller), Repository implementations (*Repository), Services (*Service/*Adapter)
+ * This detector uses Abstract Syntax Tree (AST) analysis via tree-sitter to identify
+ * naming convention violations in classes, interfaces, functions, and variables
+ * according to Clean Architecture layer rules.
+ *
+ * The detector uses a modular architecture with specialized components:
+ * - AstClassNameAnalyzer: Analyzes class names
+ * - AstInterfaceNameAnalyzer: Analyzes interface names
+ * - AstFunctionNameAnalyzer: Analyzes function and method names
+ * - AstVariableNameAnalyzer: Analyzes variable and constant names
+ * - AstNamingTraverser: Traverses the AST and coordinates analyzers
 *
 * @example
 * ```typescript
 * const detector = new NamingConventionDetector()
- * const violations = detector.detectViolations('UserDto.ts', 'domain', 'src/domain/UserDto.ts')
- * // Returns violation: DTOs should not be in domain layer
+ * const code = `
+ *     class userService {  // Wrong: should be UserService
+ *         GetUser() {}     // Wrong: should be getUser
+ *     }
+ * `
+ * const violations = detector.detectViolations(code, 'UserService.ts', 'domain', 'src/domain/UserService.ts')
+ * // Returns array of NamingViolation objects
 * ```
 */
 export class NamingConventionDetector implements INamingConventionDetector {
+    private readonly parser: CodeParser
+    private readonly traverser: AstNamingTraverser
+
+    constructor() {
+        this.parser = new CodeParser()
+
+        const classAnalyzer = new AstClassNameAnalyzer()
+        const interfaceAnalyzer = new AstInterfaceNameAnalyzer()
+        const functionAnalyzer = new AstFunctionNameAnalyzer()
+        const variableAnalyzer = new AstVariableNameAnalyzer()
+
+        this.traverser = new AstNamingTraverser(
+            classAnalyzer,
+            interfaceAnalyzer,
+            functionAnalyzer,
+            variableAnalyzer,
+        )
+    }
+
+    /**
+     * Detects naming convention violations in the given code
+     *
+     * @param content - Source code to analyze
+     * @param fileName - Name of the file being analyzed
+     * @param layer - Architectural layer (domain, application, infrastructure, shared)
+     * @param filePath - File path for context (used in violation reports)
+     * @returns Array of detected naming violations
+     */
    public detectViolations(
+        content: string,
        fileName: string,
        layer: string | undefined,
        filePath: string,
@@ -43,235 +79,23 @@ export class NamingConventionDetector implements INamingConventionDetector {
            return []
        }

-        switch (layer) {
-            case LAYERS.DOMAIN:
-                return this.checkDomainLayer(fileName, filePath)
-            case LAYERS.APPLICATION:
-                return this.checkApplicationLayer(fileName, filePath)
-            case LAYERS.INFRASTRUCTURE:
-                return this.checkInfrastructureLayer(fileName, filePath)
-            case LAYERS.SHARED:
-                return []
-            default:
-                return []
+        if (!content || content.trim().length === 0) {
+            return []
        }
+
+        const tree = this.parseCode(content, filePath)
+        return this.traverser.traverse(tree, content, layer, filePath)
    }

-    private checkDomainLayer(fileName: string, filePath: string): NamingViolation[] {
-        const violations: NamingViolation[] = []
-
-        const forbiddenPatterns = NAMING_PATTERNS.DOMAIN.ENTITY.forbidden ?? []
-
-        for (const forbidden of forbiddenPatterns) {
-            if (fileName.includes(forbidden)) {
-                violations.push(
-                    NamingViolation.create(
-                        fileName,
-                        NAMING_VIOLATION_TYPES.FORBIDDEN_PATTERN,
-                        LAYERS.DOMAIN,
-                        filePath,
-                        NAMING_ERROR_MESSAGES.DOMAIN_FORBIDDEN,
-                        fileName,
-                        "Move to application or infrastructure layer, or rename to follow domain patterns",
-                    ),
-                )
-                return violations
-            }
+    /**
+     * Parses code based on file extension
+     */
+    private parseCode(code: string, filePath: string): Parser.Tree {
+        if (filePath.endsWith(FILE_EXTENSIONS.TYPESCRIPT_JSX)) {
+            return this.parser.parseTsx(code)
+        } else if (filePath.endsWith(FILE_EXTENSIONS.TYPESCRIPT)) {
+            return this.parser.parseTypeScript(code)
        }
-
-        if (fileName.endsWith(FILE_SUFFIXES.SERVICE)) {
-            if (!NAMING_PATTERNS.DOMAIN.SERVICE.pattern.test(fileName)) {
-                violations.push(
-                    NamingViolation.create(
-                        fileName,
-                        NAMING_VIOLATION_TYPES.WRONG_CASE,
-                        LAYERS.DOMAIN,
-                        filePath,
-                        NAMING_PATTERNS.DOMAIN.SERVICE.description,
-                        fileName,
-                    ),
-                )
-            }
-            return violations
-        }
-
-        if (
-            fileName.startsWith(PATTERN_WORDS.I_PREFIX) &&
-            fileName.includes(PATTERN_WORDS.REPOSITORY)
-        ) {
-            if (!NAMING_PATTERNS.DOMAIN.REPOSITORY_INTERFACE.pattern.test(fileName)) {
-                violations.push(
-                    NamingViolation.create(
-                        fileName,
-                        NAMING_VIOLATION_TYPES.WRONG_PREFIX,
-                        LAYERS.DOMAIN,
-                        filePath,
-                        NAMING_PATTERNS.DOMAIN.REPOSITORY_INTERFACE.description,
-                        fileName,
-                    ),
-                )
-            }
-            return violations
-        }
-
-        if (!NAMING_PATTERNS.DOMAIN.ENTITY.pattern.test(fileName)) {
-            violations.push(
-                NamingViolation.create(
-                    fileName,
-                    NAMING_VIOLATION_TYPES.WRONG_CASE,
-                    LAYERS.DOMAIN,
-                    filePath,
-                    NAMING_PATTERNS.DOMAIN.ENTITY.description,
-                    fileName,
-                    NAMING_ERROR_MESSAGES.USE_PASCAL_CASE,
-                ),
-            )
-        }
-
-        return violations
-    }
-
-    private checkApplicationLayer(fileName: string, filePath: string): NamingViolation[] {
-        const violations: NamingViolation[] = []
-
-        if (
-            fileName.endsWith(FILE_SUFFIXES.DTO) ||
-            fileName.endsWith(FILE_SUFFIXES.REQUEST) ||
-            fileName.endsWith(FILE_SUFFIXES.RESPONSE)
-        ) {
-            if (!NAMING_PATTERNS.APPLICATION.DTO.pattern.test(fileName)) {
-                violations.push(
-                    NamingViolation.create(
-                        fileName,
-                        NAMING_VIOLATION_TYPES.WRONG_SUFFIX,
-                        LAYERS.APPLICATION,
-                        filePath,
-                        NAMING_PATTERNS.APPLICATION.DTO.description,
-                        fileName,
-                        NAMING_ERROR_MESSAGES.USE_DTO_SUFFIX,
-                    ),
-                )
-            }
-            return violations
-        }
-
-        if (fileName.endsWith(FILE_SUFFIXES.MAPPER)) {
-            if (!NAMING_PATTERNS.APPLICATION.MAPPER.pattern.test(fileName)) {
-                violations.push(
-                    NamingViolation.create(
-                        fileName,
-                        NAMING_VIOLATION_TYPES.WRONG_SUFFIX,
-                        LAYERS.APPLICATION,
-                        filePath,
-                        NAMING_PATTERNS.APPLICATION.MAPPER.description,
-                        fileName,
-                    ),
-                )
-            }
-            return violations
-        }
-
-        const startsWithVerb = this.startsWithCommonVerb(fileName)
-        if (startsWithVerb) {
-            if (!NAMING_PATTERNS.APPLICATION.USE_CASE.pattern.test(fileName)) {
-                violations.push(
-                    NamingViolation.create(
-                        fileName,
-                        NAMING_VIOLATION_TYPES.WRONG_VERB_NOUN,
-                        LAYERS.APPLICATION,
-                        filePath,
-                        NAMING_PATTERNS.APPLICATION.USE_CASE.description,
-                        fileName,
-                        NAMING_ERROR_MESSAGES.USE_VERB_NOUN,
-                    ),
-                )
-            }
-            return violations
-        }
-
-        if (
-            filePath.includes(PATH_PATTERNS.USE_CASES) ||
-            filePath.includes(PATH_PATTERNS.USE_CASES_ALT)
-        ) {
-            const hasVerb = this.startsWithCommonVerb(fileName)
-            if (!hasVerb) {
-                violations.push(
-                    NamingViolation.create(
-                        fileName,
-                        NAMING_VIOLATION_TYPES.WRONG_VERB_NOUN,
-                        LAYERS.APPLICATION,
-                        filePath,
-                        NAMING_ERROR_MESSAGES.USE_CASE_START_VERB,
-                        fileName,
-                        `Start with a verb like: ${USE_CASE_VERBS.slice(0, 5).join(", ")}`,
-                    ),
-                )
-            }
-        }
-
-        return violations
-    }
-
-    private checkInfrastructureLayer(fileName: string, filePath: string): NamingViolation[] {
-        const violations: NamingViolation[] = []
-
-        if (fileName.endsWith(FILE_SUFFIXES.CONTROLLER)) {
-            if (!NAMING_PATTERNS.INFRASTRUCTURE.CONTROLLER.pattern.test(fileName)) {
-                violations.push(
-                    NamingViolation.create(
-                        fileName,
-                        NAMING_VIOLATION_TYPES.WRONG_SUFFIX,
-                        LAYERS.INFRASTRUCTURE,
-                        filePath,
-                        NAMING_PATTERNS.INFRASTRUCTURE.CONTROLLER.description,
-                        fileName,
-                    ),
-                )
-            }
-            return violations
-        }
-
-        if (
-            fileName.endsWith(FILE_SUFFIXES.REPOSITORY) &&
-            !fileName.startsWith(PATTERN_WORDS.I_PREFIX)
-        ) {
-            if (!NAMING_PATTERNS.INFRASTRUCTURE.REPOSITORY_IMPL.pattern.test(fileName)) {
-                violations.push(
-                    NamingViolation.create(
-                        fileName,
-                        NAMING_VIOLATION_TYPES.WRONG_SUFFIX,
-                        LAYERS.INFRASTRUCTURE,
-                        filePath,
-                        NAMING_PATTERNS.INFRASTRUCTURE.REPOSITORY_IMPL.description,
-                        fileName,
-                    ),
-                )
-            }
-            return violations
-        }
-
-        if (fileName.endsWith(FILE_SUFFIXES.SERVICE) || fileName.endsWith(FILE_SUFFIXES.ADAPTER)) {
-            if (!NAMING_PATTERNS.INFRASTRUCTURE.SERVICE.pattern.test(fileName)) {
-                violations.push(
-                    NamingViolation.create(
-                        fileName,
-                        NAMING_VIOLATION_TYPES.WRONG_SUFFIX,
-                        LAYERS.INFRASTRUCTURE,
-                        filePath,
-                        NAMING_PATTERNS.INFRASTRUCTURE.SERVICE.description,
-                        fileName,
-                    ),
-                )
-            }
-            return violations
-        }
-
-        return violations
-    }
-
-    private startsWithCommonVerb(fileName: string): boolean {
-        const baseFileName = fileName.replace(/\.tsx?$/, "")
-
-        return USE_CASE_VERBS.some((verb) => baseFileName.startsWith(verb))
+        return this.parser.parseJavaScript(code)
    }
 }
--- a/packages/guardian/src/infrastructure/analyzers/RepositoryPatternDetector.ts
+++ b/packages/guardian/src/infrastructure/analyzers/RepositoryPatternDetector.ts
@@ -0,0 +1,106 @@
+import { IRepositoryPatternDetector } from "../../domain/services/RepositoryPatternDetectorService"
+import { RepositoryViolation } from "../../domain/value-objects/RepositoryViolation"
+import { OrmTypeMatcher } from "../strategies/OrmTypeMatcher"
+import { MethodNameValidator } from "../strategies/MethodNameValidator"
+import { RepositoryFileAnalyzer } from "../strategies/RepositoryFileAnalyzer"
+import { RepositoryViolationDetector } from "../strategies/RepositoryViolationDetector"
+
+/**
+ * Detects Repository Pattern violations in the codebase
+ *
+ * This detector identifies violations where the Repository Pattern is not properly implemented:
+ * 1. ORM-specific types in repository interfaces (domain should be ORM-agnostic)
+ * 2. Concrete repository usage in use cases (violates dependency inversion)
+ * 3. Repository instantiation with 'new' in use cases (should use DI)
+ * 4. Non-domain method names in repositories (should use ubiquitous language)
+ *
+ * @example
+ * ```typescript
+ * const detector = new RepositoryPatternDetector()
+ *
+ * // Detect violations in a repository interface
+ * const code = `
+ * interface IUserRepository {
+ *     findOne(query: Prisma.UserWhereInput): Promise<User>
+ * }
+ * `
+ * const violations = detector.detectViolations(
+ *     code,
+ *     'src/domain/repositories/IUserRepository.ts',
+ *     'domain'
+ * )
+ *
+ * // violations will contain ORM type violation
+ * console.log(violations.length) // 1
+ * console.log(violations[0].violationType) // 'orm-type-in-interface'
+ * ```
+ */
+export class RepositoryPatternDetector implements IRepositoryPatternDetector {
+    private readonly ormMatcher: OrmTypeMatcher
+    private readonly methodValidator: MethodNameValidator
+    private readonly fileAnalyzer: RepositoryFileAnalyzer
+    private readonly violationDetector: RepositoryViolationDetector
+
+    constructor() {
+        this.ormMatcher = new OrmTypeMatcher()
+        this.methodValidator = new MethodNameValidator(this.ormMatcher)
+        this.fileAnalyzer = new RepositoryFileAnalyzer()
+        this.violationDetector = new RepositoryViolationDetector(
+            this.ormMatcher,
+            this.methodValidator,
+        )
+    }
+
+    /**
+     * Detects all Repository Pattern violations in the given code
+     */
+    public detectViolations(
+        code: string,
+        filePath: string,
+        layer: string | undefined,
+    ): RepositoryViolation[] {
+        const violations: RepositoryViolation[] = []
+
+        if (this.fileAnalyzer.isRepositoryInterface(filePath, layer)) {
+            violations.push(...this.violationDetector.detectOrmTypes(code, filePath, layer))
+            violations.push(...this.violationDetector.detectNonDomainMethods(code, filePath, layer))
+        }
+
+        if (this.fileAnalyzer.isUseCase(filePath, layer)) {
+            violations.push(
+                ...this.violationDetector.detectConcreteRepositoryUsage(code, filePath, layer),
+            )
+            violations.push(...this.violationDetector.detectNewInstantiation(code, filePath, layer))
+        }
+
+        return violations
+    }
+
+    /**
+     * Checks if a type is an ORM-specific type
+     */
+    public isOrmType(typeName: string): boolean {
+        return this.ormMatcher.isOrmType(typeName)
+    }
+
+    /**
+     * Checks if a method name follows domain language conventions
+     */
+    public isDomainMethodName(methodName: string): boolean {
+        return this.methodValidator.isDomainMethodName(methodName)
+    }
+
+    /**
+     * Checks if a file is a repository interface
+     */
+    public isRepositoryInterface(filePath: string, layer: string | undefined): boolean {
+        return this.fileAnalyzer.isRepositoryInterface(filePath, layer)
+    }
+
+    /**
+     * Checks if a file is a use case
+     */
+    public isUseCase(filePath: string, layer: string | undefined): boolean {
+        return this.fileAnalyzer.isUseCase(filePath, layer)
+    }
+}
--- a/packages/guardian/src/infrastructure/analyzers/SecretDetector.ts
+++ b/packages/guardian/src/infrastructure/analyzers/SecretDetector.ts
@@ -0,0 +1,187 @@
+import { createEngine } from "@secretlint/node"
+import type { SecretLintConfigDescriptor } from "@secretlint/types"
+import { ISecretDetector } from "../../domain/services/ISecretDetector"
+import { SecretViolation } from "../../domain/value-objects/SecretViolation"
+import { SECRET_KEYWORDS, SECRET_TYPE_NAMES } from "../../domain/constants/SecretExamples"
+import { EXTERNAL_PACKAGES } from "../../shared/constants/rules"
+
+/**
+ * Detects hardcoded secrets in TypeScript/JavaScript code
+ *
+ * Uses industry-standard Secretlint library to detect 350+ types of secrets
+ * including AWS keys, GitHub tokens, NPM tokens, SSH keys, API keys, and more.
+ *
+ * All detected secrets are marked as CRITICAL severity because they represent
+ * serious security risks that could lead to unauthorized access or data breaches.
+ *
+ * @example
+ * ```typescript
+ * const detector = new SecretDetector()
+ * const code = `const AWS_KEY = "AKIA1234567890ABCDEF"`
+ * const violations = await detector.detectAll(code, 'config.ts')
+ * // Returns array of SecretViolation objects with CRITICAL severity
+ * ```
+ */
+export class SecretDetector implements ISecretDetector {
+    private readonly secretlintConfig: SecretLintConfigDescriptor = {
+        rules: [
+            {
+                id: EXTERNAL_PACKAGES.SECRETLINT_PRESET,
+            },
+        ],
+    }
+
+    /**
+     * Detects all types of hardcoded secrets in the provided code
+     *
+     * @param code - Source code to analyze
+     * @param filePath - Path to the file being analyzed
+     * @returns Promise resolving to array of secret violations
+     */
+    public async detectAll(code: string, filePath: string): Promise<SecretViolation[]> {
+        try {
+            const engine = await createEngine({
+                cwd: process.cwd(),
+                configFileJSON: this.secretlintConfig,
+                formatter: "stylish",
+                color: false,
+            })
+
+            const result = await engine.executeOnContent({
+                content: code,
+                filePath,
+            })
+
+            return this.parseOutputToViolations(result.output, filePath)
+        } catch (_error) {
+            return []
+        }
+    }
+
+    private parseOutputToViolations(output: string, filePath: string): SecretViolation[] {
+        const violations: SecretViolation[] = []
+
+        if (!output || output.trim() === "") {
+            return violations
+        }
+
+        const lines = output.split("\n")
+
+        for (const line of lines) {
+            const match = /^\s*(\d+):(\d+)\s+(error|warning)\s+(.+?)\s+(.+)$/.exec(line)
+
+            if (match) {
+                const [, lineNum, column, , message, ruleId] = match
+                const secretType = this.extractSecretType(message, ruleId)
+
+                const violation = SecretViolation.create(
+                    filePath,
+                    parseInt(lineNum, 10),
+                    parseInt(column, 10),
+                    secretType,
+                    message,
+                )
+
+                violations.push(violation)
+            }
+        }
+
+        return violations
+    }
+
+    private extractSecretType(message: string, ruleId: string): string {
+        const lowerMessage = message.toLowerCase()
+
+        const ruleBasedType = this.extractByRuleId(ruleId, lowerMessage)
+        if (ruleBasedType) {
+            return ruleBasedType
+        }
+
+        return this.extractByMessage(lowerMessage)
+    }
+
+    private extractByRuleId(ruleId: string, lowerMessage: string): string | null {
+        if (ruleId.includes(SECRET_KEYWORDS.AWS)) {
+            return this.extractAwsType(lowerMessage)
+        }
+        if (ruleId.includes(SECRET_KEYWORDS.GITHUB)) {
+            return this.extractGithubType(lowerMessage)
+        }
+        if (ruleId.includes(SECRET_KEYWORDS.NPM)) {
+            return SECRET_TYPE_NAMES.NPM_TOKEN
+        }
+        if (ruleId.includes(SECRET_KEYWORDS.GCP) || ruleId.includes(SECRET_KEYWORDS.GOOGLE)) {
+            return SECRET_TYPE_NAMES.GCP_SERVICE_ACCOUNT_KEY
+        }
+        if (ruleId.includes(SECRET_KEYWORDS.PRIVATEKEY) || ruleId.includes(SECRET_KEYWORDS.SSH)) {
+            return this.extractSshType(lowerMessage)
+        }
+        if (ruleId.includes(SECRET_KEYWORDS.SLACK)) {
+            return this.extractSlackType(lowerMessage)
+        }
+        if (ruleId.includes(SECRET_KEYWORDS.BASICAUTH)) {
+            return SECRET_TYPE_NAMES.BASIC_AUTH_CREDENTIALS
+        }
+        return null
+    }
+
+    private extractAwsType(lowerMessage: string): string {
+        if (lowerMessage.includes(SECRET_KEYWORDS.ACCESS_KEY)) {
+            return SECRET_TYPE_NAMES.AWS_ACCESS_KEY
+        }
+        if (lowerMessage.includes(SECRET_KEYWORDS.SECRET)) {
+            return SECRET_TYPE_NAMES.AWS_SECRET_KEY
+        }
+        return SECRET_TYPE_NAMES.AWS_CREDENTIAL
+    }
+
+    private extractGithubType(lowerMessage: string): string {
+        if (lowerMessage.includes(SECRET_KEYWORDS.PERSONAL_ACCESS_TOKEN)) {
+            return SECRET_TYPE_NAMES.GITHUB_PERSONAL_ACCESS_TOKEN
+        }
+        if (lowerMessage.includes(SECRET_KEYWORDS.OAUTH)) {
+            return SECRET_TYPE_NAMES.GITHUB_OAUTH_TOKEN
+        }
+        return SECRET_TYPE_NAMES.GITHUB_TOKEN
+    }
+
+    private extractSshType(lowerMessage: string): string {
+        const sshTypeMap: [string, string][] = [
+            [SECRET_KEYWORDS.RSA, SECRET_TYPE_NAMES.SSH_RSA_PRIVATE_KEY],
+            [SECRET_KEYWORDS.DSA, SECRET_TYPE_NAMES.SSH_DSA_PRIVATE_KEY],
+            [SECRET_KEYWORDS.ECDSA, SECRET_TYPE_NAMES.SSH_ECDSA_PRIVATE_KEY],
+            [SECRET_KEYWORDS.ED25519, SECRET_TYPE_NAMES.SSH_ED25519_PRIVATE_KEY],
+        ]
+        for (const [keyword, typeName] of sshTypeMap) {
+            if (lowerMessage.includes(keyword)) {
+                return typeName
+            }
+        }
+        return SECRET_TYPE_NAMES.SSH_PRIVATE_KEY
+    }
+
+    private extractSlackType(lowerMessage: string): string {
+        if (lowerMessage.includes(SECRET_KEYWORDS.BOT)) {
+            return SECRET_TYPE_NAMES.SLACK_BOT_TOKEN
+        }
+        if (lowerMessage.includes(SECRET_KEYWORDS.USER)) {
+            return SECRET_TYPE_NAMES.SLACK_USER_TOKEN
+        }
+        return SECRET_TYPE_NAMES.SLACK_TOKEN
+    }
+
+    private extractByMessage(lowerMessage: string): string {
+        const messageTypeMap: [string, string][] = [
+            [SECRET_KEYWORDS.API_KEY, SECRET_TYPE_NAMES.API_KEY],
+            [SECRET_KEYWORDS.TOKEN, SECRET_TYPE_NAMES.AUTHENTICATION_TOKEN],
+            [SECRET_KEYWORDS.PASSWORD, SECRET_TYPE_NAMES.PASSWORD],
+            [SECRET_KEYWORDS.SECRET, SECRET_TYPE_NAMES.SECRET],
+        ]
+        for (const [keyword, typeName] of messageTypeMap) {
+            if (lowerMessage.includes(keyword)) {
+                return typeName
+            }
+        }
+        return SECRET_TYPE_NAMES.SENSITIVE_DATA
+    }
+}
--- a/packages/guardian/src/infrastructure/constants/defaults.ts
+++ b/packages/guardian/src/infrastructure/constants/defaults.ts
@@ -8,6 +8,10 @@ export const DEFAULT_EXCLUDES = [
    "coverage",
    ".git",
    ".puaros",
+    "tests",
+    "test",
+    "__tests__",
+    "examples",
 ] as const

 export const DEFAULT_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx"] as const
--- a/packages/guardian/src/infrastructure/constants/detectorPatterns.ts
+++ b/packages/guardian/src/infrastructure/constants/detectorPatterns.ts
@@ -63,4 +63,70 @@ export const NAMING_ERROR_MESSAGES = {
    USE_DTO_SUFFIX: "Use *Dto, *Request, or *Response suffix (e.g., UserResponseDto.ts)",
    USE_VERB_NOUN: "Use verb + noun in PascalCase (e.g., CreateUser.ts, UpdateProfile.ts)",
    USE_CASE_START_VERB: "Use cases should start with a verb",
+    DOMAIN_SERVICE_PASCAL_CASE: "Domain services must be PascalCase ending with 'Service'",
+    DOMAIN_ENTITY_PASCAL_CASE: "Domain entities must be PascalCase nouns",
+    DTO_PASCAL_CASE: "DTOs must be PascalCase ending with 'Dto', 'Request', or 'Response'",
+    MAPPER_PASCAL_CASE: "Mappers must be PascalCase ending with 'Mapper'",
+    USE_CASE_VERB_NOUN: "Use cases must be PascalCase Verb+Noun (e.g., CreateUser)",
+    CONTROLLER_PASCAL_CASE: "Controllers must be PascalCase ending with 'Controller'",
+    REPOSITORY_IMPL_PASCAL_CASE:
+        "Repository implementations must be PascalCase ending with 'Repository'",
+    SERVICE_ADAPTER_PASCAL_CASE:
+        "Services/Adapters must be PascalCase ending with 'Service' or 'Adapter'",
+    FUNCTION_CAMEL_CASE: "Functions and methods must be camelCase",
+    USE_CAMEL_CASE_FUNCTION: "Use camelCase for function names (e.g., getUserById, createOrder)",
+    INTERFACE_PASCAL_CASE: "Interfaces must be PascalCase",
+    USE_PASCAL_CASE_INTERFACE: "Use PascalCase for interface names",
+    REPOSITORY_INTERFACE_I_PREFIX:
+        "Domain repository interfaces must start with 'I' (e.g., IUserRepository)",
+    REPOSITORY_INTERFACE_PATTERN: "Repository interfaces must be I + PascalCase + Repository",
+    CONSTANT_UPPER_SNAKE_CASE: "Exported constants must be UPPER_SNAKE_CASE",
+    USE_UPPER_SNAKE_CASE_CONSTANT:
+        "Use UPPER_SNAKE_CASE for constant names (e.g., MAX_RETRIES, API_URL)",
+    VARIABLE_CAMEL_CASE: "Variables must be camelCase",
+    USE_CAMEL_CASE_VARIABLE: "Use camelCase for variable names (e.g., userId, orderList)",
+} as const
+
+/**
+ * DDD folder names for aggregate boundary detection
+ */
+export const DDD_FOLDER_NAMES = {
+    ENTITIES: "entities",
+    AGGREGATES: "aggregates",
+    VALUE_OBJECTS: "value-objects",
+    VO: "vo",
+    EVENTS: "events",
+    DOMAIN_EVENTS: "domain-events",
+    REPOSITORIES: "repositories",
+    SERVICES: "services",
+    SPECIFICATIONS: "specifications",
+    DOMAIN: "domain",
+    CONSTANTS: "constants",
+    SHARED: "shared",
+    FACTORIES: "factories",
+    PORTS: "ports",
+    INTERFACES: "interfaces",
+    ERRORS: "errors",
+    EXCEPTIONS: "exceptions",
+} as const
+
+/**
+ * Repository method suggestions for domain language
+ */
+export const REPOSITORY_METHOD_SUGGESTIONS = {
+    SEARCH: "search",
+    FIND_BY_PROPERTY: "findBy[Property]",
+    GET_ENTITY: "get[Entity]",
+    CREATE: "create",
+    ADD_ENTITY: "add[Entity]",
+    STORE_ENTITY: "store[Entity]",
+    UPDATE: "update",
+    MODIFY_ENTITY: "modify[Entity]",
+    SAVE: "save",
+    DELETE: "delete",
+    REMOVE_BY_PROPERTY: "removeBy[Property]",
+    FIND_ALL: "findAll",
+    LIST_ALL: "listAll",
+    DEFAULT_SUGGESTION:
+        "Use domain-specific names like: findBy[Property], save, create, delete, update, add[Entity]",
 } as const
--- a/packages/guardian/src/infrastructure/constants/naming-patterns.ts
+++ b/packages/guardian/src/infrastructure/constants/naming-patterns.ts
@@ -0,0 +1,2 @@
+export const NAMING_SUGGESTION_DEFAULT =
+    "Move to application or infrastructure layer, or rename to follow domain patterns"
--- a/packages/guardian/src/infrastructure/constants/orm-methods.ts
+++ b/packages/guardian/src/infrastructure/constants/orm-methods.ts
@@ -0,0 +1,21 @@
+export const ORM_QUERY_METHODS = [
+    "findOne",
+    "findMany",
+    "findFirst",
+    "findAndCountAll",
+    "insert",
+    "insertMany",
+    "insertOne",
+    "updateOne",
+    "updateMany",
+    "deleteOne",
+    "deleteMany",
+    "select",
+    "query",
+    "execute",
+    "run",
+    "exec",
+    "aggregate",
+] as const
+
+export type OrmQueryMethod = (typeof ORM_QUERY_METHODS)[number]
--- a/packages/guardian/src/infrastructure/constants/paths.ts
+++ b/packages/guardian/src/infrastructure/constants/paths.ts
@@ -0,0 +1,17 @@
+export const LAYER_PATHS = {
+    DOMAIN: "/domain/",
+    APPLICATION: "/application/",
+    INFRASTRUCTURE: "/infrastructure/",
+    SHARED: "/shared/",
+} as const
+
+export const CLI_PATHS = {
+    DIST_CLI_INDEX: "../dist/cli/index.js",
+} as const
+
+export const IMPORT_PATTERNS = {
+    ES_IMPORT:
+        /import\s+(?:{[^}]*}|[\w*]+(?:\s+as\s+\w+)?|\*\s+as\s+\w+)\s+from\s+['"]([^'"]+)['"]/g,
+    REQUIRE: /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+    QUOTE: /['"]/g,
+} as const
--- a/packages/guardian/src/infrastructure/constants/type-patterns.ts
+++ b/packages/guardian/src/infrastructure/constants/type-patterns.ts
@@ -0,0 +1,28 @@
+export const DTO_SUFFIXES = [
+    "Dto",
+    "DTO",
+    "Request",
+    "Response",
+    "Command",
+    "Query",
+    "Result",
+] as const
+
+export const PRIMITIVE_TYPES = [
+    "string",
+    "number",
+    "boolean",
+    "void",
+    "any",
+    "unknown",
+    "null",
+    "undefined",
+    "object",
+    "never",
+] as const
+
+export const NULLABLE_TYPES = ["null", "undefined"] as const
+
+export const TEST_FILE_EXTENSIONS = [".test.", ".spec."] as const
+
+export const TEST_FILE_SUFFIXES = [".test.ts", ".test.js", ".spec.ts", ".spec.js"] as const
--- a/packages/guardian/src/infrastructure/index.ts
+++ b/packages/guardian/src/infrastructure/index.ts
@@ -1,3 +1,4 @@
 export * from "./parsers/CodeParser"
 export * from "./scanners/FileScanner"
 export * from "./analyzers/HardcodeDetector"
+export * from "./analyzers/RepositoryPatternDetector"
--- a/packages/guardian/src/infrastructure/scanners/FileScanner.ts
+++ b/packages/guardian/src/infrastructure/scanners/FileScanner.ts
@@ -3,6 +3,7 @@ import * as path from "path"
 import { FileScanOptions, IFileScanner } from "../../domain/services/IFileScanner"
 import { DEFAULT_EXCLUDES, DEFAULT_EXTENSIONS, FILE_ENCODING } from "../constants/defaults"
 import { ERROR_MESSAGES } from "../../shared/constants"
+import { TEST_FILE_EXTENSIONS, TEST_FILE_SUFFIXES } from "../constants/type-patterns"

 /**
 * Scans project directory for source files
@@ -56,7 +57,12 @@ export class FileScanner implements IFileScanner {
    }

    private shouldExclude(name: string, excludePatterns: string[]): boolean {
-        return excludePatterns.some((pattern) => name.includes(pattern))
+        const isExcludedDirectory = excludePatterns.some((pattern) => name.includes(pattern))
+        const isTestFile =
+            (TEST_FILE_EXTENSIONS as readonly string[]).some((ext) => name.includes(ext)) ||
+            (TEST_FILE_SUFFIXES as readonly string[]).some((suffix) => name.endsWith(suffix))
+
+        return isExcludedDirectory || isTestFile
    }

    public async readFile(filePath: string): Promise<string> {
--- a/packages/guardian/src/infrastructure/strategies/AggregatePathAnalyzer.ts
+++ b/packages/guardian/src/infrastructure/strategies/AggregatePathAnalyzer.ts
@@ -0,0 +1,177 @@
+import { DDD_FOLDER_NAMES } from "../constants/detectorPatterns"
+import { IMPORT_PATTERNS } from "../constants/paths"
+import { FolderRegistry } from "./FolderRegistry"
+
+/**
+ * Analyzes file paths and imports to extract aggregate information
+ *
+ * Handles path normalization, aggregate extraction, and entity name detection
+ * for aggregate boundary validation.
+ */
+export class AggregatePathAnalyzer {
+    constructor(private readonly folderRegistry: FolderRegistry) {}
+
+    /**
+     * Extracts the aggregate name from a file path
+     *
+     * Handles patterns like:
+     * - domain/aggregates/order/Order.ts → 'order'
+     * - domain/order/Order.ts → 'order'
+     * - domain/entities/order/Order.ts → 'order'
+     */
+    public extractAggregateFromPath(filePath: string): string | undefined {
+        const normalizedPath = this.normalizePath(filePath)
+        const segments = this.getPathSegmentsAfterDomain(normalizedPath)
+
+        if (!segments || segments.length < 2) {
+            return undefined
+        }
+
+        return this.findAggregateInSegments(segments)
+    }
+
+    /**
+     * Extracts the aggregate name from an import path
+     */
+    public extractAggregateFromImport(importPath: string): string | undefined {
+        const normalizedPath = importPath.replace(IMPORT_PATTERNS.QUOTE, "").toLowerCase()
+        const segments = normalizedPath.split("/").filter((seg) => seg !== ".." && seg !== ".")
+
+        if (segments.length === 0) {
+            return undefined
+        }
+
+        return this.findAggregateInImportSegments(segments)
+    }
+
+    /**
+     * Extracts the entity name from an import path
+     */
+    public extractEntityName(importPath: string): string | undefined {
+        const normalizedPath = importPath.replace(IMPORT_PATTERNS.QUOTE, "")
+        const segments = normalizedPath.split("/")
+        const lastSegment = segments[segments.length - 1]
+
+        if (lastSegment) {
+            return lastSegment.replace(/\.(ts|js)$/, "")
+        }
+
+        return undefined
+    }
+
+    /**
+     * Normalizes a file path for consistent processing
+     */
+    private normalizePath(filePath: string): string {
+        return filePath.toLowerCase().replace(/\\/g, "/")
+    }
+
+    /**
+     * Gets path segments after the 'domain' folder
+     */
+    private getPathSegmentsAfterDomain(normalizedPath: string): string[] | undefined {
+        const domainMatch = /(?:^|\/)(domain)\//.exec(normalizedPath)
+        if (!domainMatch) {
+            return undefined
+        }
+
+        const domainEndIndex = domainMatch.index + domainMatch[0].length
+        const pathAfterDomain = normalizedPath.substring(domainEndIndex)
+        return pathAfterDomain.split("/").filter(Boolean)
+    }
+
+    /**
+     * Finds aggregate name in path segments after domain folder
+     */
+    private findAggregateInSegments(segments: string[]): string | undefined {
+        if (this.folderRegistry.isEntityFolder(segments[0])) {
+            return this.extractFromEntityFolder(segments)
+        }
+
+        const aggregate = segments[0]
+        if (this.folderRegistry.isNonAggregateFolder(aggregate)) {
+            return undefined
+        }
+
+        return aggregate
+    }
+
+    /**
+     * Extracts aggregate from entity folder structure
+     */
+    private extractFromEntityFolder(segments: string[]): string | undefined {
+        if (segments.length < 3) {
+            return undefined
+        }
+
+        const aggregate = segments[1]
+        if (this.folderRegistry.isNonAggregateFolder(aggregate)) {
+            return undefined
+        }
+
+        return aggregate
+    }
+
+    /**
+     * Finds aggregate in import path segments
+     */
+    private findAggregateInImportSegments(segments: string[]): string | undefined {
+        const aggregateFromDomainFolder = this.findAggregateAfterDomainFolder(segments)
+        if (aggregateFromDomainFolder) {
+            return aggregateFromDomainFolder
+        }
+
+        return this.findAggregateFromSecondLastSegment(segments)
+    }
+
+    /**
+     * Finds aggregate after 'domain' or 'aggregates' folder in import
+     */
+    private findAggregateAfterDomainFolder(segments: string[]): string | undefined {
+        for (let i = 0; i < segments.length; i++) {
+            const isDomainOrAggregatesFolder =
+                segments[i] === DDD_FOLDER_NAMES.DOMAIN ||
+                segments[i] === DDD_FOLDER_NAMES.AGGREGATES
+
+            if (!isDomainOrAggregatesFolder) {
+                continue
+            }
+
+            if (i + 1 >= segments.length) {
+                continue
+            }
+
+            const nextSegment = segments[i + 1]
+            const isEntityOrAggregateFolder =
+                this.folderRegistry.isEntityFolder(nextSegment) ||
+                nextSegment === DDD_FOLDER_NAMES.AGGREGATES
+
+            if (isEntityOrAggregateFolder) {
+                return i + 2 < segments.length ? segments[i + 2] : undefined
+            }
+
+            return nextSegment
+        }
+        return undefined
+    }
+
+    /**
+     * Extracts aggregate from second-to-last segment if applicable
+     */
+    private findAggregateFromSecondLastSegment(segments: string[]): string | undefined {
+        if (segments.length >= 2) {
+            const secondLastSegment = segments[segments.length - 2]
+
+            if (
+                !this.folderRegistry.isEntityFolder(secondLastSegment) &&
+                !this.folderRegistry.isValueObjectFolder(secondLastSegment) &&
+                !this.folderRegistry.isAllowedFolder(secondLastSegment) &&
+                secondLastSegment !== DDD_FOLDER_NAMES.DOMAIN
+            ) {
+                return secondLastSegment
+            }
+        }
+
+        return undefined
+    }
+}
--- a/packages/guardian/src/infrastructure/strategies/AstBooleanAnalyzer.ts
+++ b/packages/guardian/src/infrastructure/strategies/AstBooleanAnalyzer.ts
@@ -0,0 +1,92 @@
+import Parser from "tree-sitter"
+import { HardcodedValue, HardcodeType } from "../../domain/value-objects/HardcodedValue"
+import { DETECTION_VALUES, HARDCODE_TYPES } from "../../shared/constants/rules"
+import { AstContextChecker } from "./AstContextChecker"
+
+/**
+ * AST-based analyzer for detecting magic booleans
+ *
+ * Detects boolean literals used as arguments without clear meaning.
+ * Example: doSomething(true, false, true) - hard to understand
+ * Better: doSomething({ sync: true, validate: false, cache: true })
+ */
+export class AstBooleanAnalyzer {
+    constructor(private readonly contextChecker: AstContextChecker) {}
+
+    /**
+     * Analyzes a boolean node and returns a violation if it's a magic boolean
+     */
+    public analyze(node: Parser.SyntaxNode, lines: string[]): HardcodedValue | null {
+        if (!this.shouldDetect(node)) {
+            return null
+        }
+
+        const value = node.text === DETECTION_VALUES.BOOLEAN_TRUE
+
+        return this.createViolation(node, value, lines)
+    }
+
+    /**
+     * Checks if boolean should be detected
+     */
+    private shouldDetect(node: Parser.SyntaxNode): boolean {
+        if (this.contextChecker.isInExportedConstant(node)) {
+            return false
+        }
+
+        if (this.contextChecker.isInTypeContext(node)) {
+            return false
+        }
+
+        if (this.contextChecker.isInTestDescription(node)) {
+            return false
+        }
+
+        const parent = node.parent
+        if (!parent) {
+            return false
+        }
+
+        if (parent.type === "arguments") {
+            return this.isInFunctionCallWithMultipleBooleans(parent)
+        }
+
+        return false
+    }
+
+    /**
+     * Checks if function call has multiple boolean arguments
+     */
+    private isInFunctionCallWithMultipleBooleans(argsNode: Parser.SyntaxNode): boolean {
+        let booleanCount = 0
+
+        for (const child of argsNode.children) {
+            if (child.type === "true" || child.type === "false") {
+                booleanCount++
+            }
+        }
+
+        return booleanCount >= 2
+    }
+
+    /**
+     * Creates a HardcodedValue violation from a boolean node
+     */
+    private createViolation(
+        node: Parser.SyntaxNode,
+        value: boolean,
+        lines: string[],
+    ): HardcodedValue {
+        const lineNumber = node.startPosition.row + 1
+        const column = node.startPosition.column
+        const context = lines[node.startPosition.row]?.trim() ?? ""
+
+        return HardcodedValue.create(
+            value,
+            HARDCODE_TYPES.MAGIC_BOOLEAN as HardcodeType,
+            lineNumber,
+            column,
+            context,
+        )
+    }
+}
--- a/Show More
+++ b/Show More