# Warden Core - The AI Code Guardian

> "AI writes the code. Warden guards the production."

![Status](https://img.shields.io/badge/Status-Production%20Ready-success)
![Python](https://img.shields.io/badge/Python-3.9%2B-blue)
![AI Ready](https://img.shields.io/badge/AI-Native-purple)

**Warden** is an AI-native security and quality gate designed to validate code generated by LLMs (Claude, GPT-4, etc.) before it enters your codebase. It acts as a strict, impartial judge that enforcing architectural rules, preventing security vulnerabilities, and maintaining code hygiene.

---

## 🤖 Why Warden?

AI coding assistants are powerful but prone to:
*   **Hallucinations:** Inventing non-existent APIs or libraries.
*   **Subtle Bugs:** Introducing edge cases that human reviewers miss.
*   **Security Flaws:** Hardcoding secrets or using unsafe patterns.
*   **Drift:** Deviating from established project architecture.

Warden provides the **"Verify-Loop"** mechanism to ensure every AI-generated change is validated against a rigorous set of rules.

---

## 🚀 Core Features

### 1. 🧠 AI-Native Integration (MCP & Hooks)
Warden is built to integrate directly with your AI Agent:
*   **Context Loading:** Automatically injects `.warden/AI_RULES.md` into every session via Claude `SessionStart` hooks.
*   **Protocol Enforcement:** Instructs AI agents to follow the **Plan -> Execute -> Verify** loop.
*   **Feedback Loop:** Provides JSON/SARIF reports that AI agents can read to self-correct.

### 2. 🛡️ The 6-Frame Validation Pipeline
Warden runs your code through 6 specialized "Frames":
1.  **SecurityFrame (Critical):** Detects SQLi, XSS, and hardcoded secrets.
2.  **ChaosEngineeringFrame (High):** Validates error handling and resilience patterns.
3.  **FuzzTestingFrame (High):** Checks for type safety and edge case handling.
4.  **PropertyTestingFrame (Medium):** Verifies idempotency and invariants.
5.  **ArchitecturalConsistencyFrame (Medium):** Enforces SOLID principles and file limits.
6.  **StressTestingFrame (Low):** Identifies performance bottlenecks (N+1 queries).

### 3. 🚦 False Positive Management
Warden gives you granular control over what to check:
*   **Inline Suppression:** Use `# warden-ignore: rule-id` to suppress specific issues.
*   **Global Config:** Define suppressions in `.warden/suppressions.yaml`.
*   **File Exclusion:** Respects `.gitignore` and supports `.warden/ignore.yaml`.

---

## 🏁 Quick Start

### Installation

```bash
pip install warden-core
```

### Initialization (The Critical Step)

To setup Warden for your project and **configure your AI Agent**:

```bash
warden init --agent
```

This command:
1.  Analyzes your project structure.
2.  Creates `.warden/AI_RULES.md`.
3.  Configures Claude Code hooks (`.claude/settings.json`) to auto-load rules.
4.  Sets up MCP configuration.
5.  Creates `.env` and `.env.example` for your API keys.

### The "Verify-Loop" Protocol

AI Agents working in a Warden project follow this strict protocol:

1.  **PLAN:** Design the change (Task or Phase).
2.  **EXECUTE:** Implement the code.
3.  **VERIFY:** Run `warden scan` at the end of the task/phase.
    *   **IF PASS:** Display **Quality Score (X/10)** 🚀
    *   **IF FAIL:** Fix issues and Repeat.

---

## 🛠️ Command Reference

| Command | Description |
| :--- | :--- |
| `warden scan` | Runs the full validation pipeline on the project. |
| `warden validate <file>` | Scans a single file for immediate feedback. |
| `warden serve` | Starts the MCP Server for AI integration. |
| `warden doctor` | Checks project health and configuration status. |
| `warden install` | Installs/Updates validation frames. |
| `warden search <query>` | Searches Warden Hub or local codebase. |

---

## 📂 Project Structure

```
.
├── .warden/
│   ├── AI_RULES.md          # Protocol for AI Agents
│   ├── config.yaml          # Pipeline configuration
│   ├── ignore.yaml          # File exclusions
│   ├── suppressions.yaml    # False positive rules
│   └── reports/             # Scan results (JSON, SARIF)
├── .claude/
│   └── settings.json        # Hooks for auto-loading context
└── src/                     # Your source code
```

---

## 🧩 Architecture

Warden is designed with modular "Frames" and extends easily:

*   **Pipes & Filters:** Sequential execution pipeline.
*   **Priority Groups:** Critical security checks run first (Fail-Fast).
*   **LSP Synergy:** Uses Language Server Protocol for deep code understanding.
*   **Vector Search:** Semantic search for context-aware fixes.

---

## 📄 License

[License Info]
