Docs: Synchronize all documentation and environment examples for Unified Enforcer

Author: darestack

.env.example

@@ -12,7 +12,9 @@ GROQ_API_KEY=""
 
 # Infrastructure
 REDIS_URL="redis://localhost:6380"
-DB_PATH="commitguard.db"
+DATABASE_URL="postgresql+asyncpg://postgres:postgres@localhost:5432/commitguard"
+# DB_PATH="commitguard.db" # Legacy SQLite support
+
 
 # Integrations
 # SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."

DOCUMENTATION.md

@@ -1,63 +1,58 @@
 # CommitGuard AI: Comprehensive Documentation 📚
 
-Welcome to the internal mechanics of CommitGuard AI. This document provides a deep dive into how to use the platform, how the agentic reasoning works, and how to scale the system.
+Welcome to the internal mechanics of CommitGuard AI. This document provides a deep dive into the **Unified Enforcer** architecture—the bridge between chat-based behavioral analysis and GitOps technical accountability.
 
 ---
 
-## 🏗️ Architecture Overview
+## 🏗️ Architecture Overview: The Unified Enforcer
 
-CommitGuard AI is built on a **Decoupled Event-Driven Architecture**:
-1.  **FastAPI Entrypoint**: Receives natural language or structured data.
-2.  **Redis Broker**: Handshakes the data to background workers via ARQ.
-3.  **The Brain (Agents)**: A suite of specialized LLM agents that analyze sentiment, risk, and burnout.
-4.  **Persistence Layer**: PostgreSQL (via SQLModel) stores historical reliability and Slack identity mapping.
-5.  **Intervention Layer**: Outbound Slack Webhooks perform directed @mentions.
+CommitGuard AI is built on a **High-Fidelity Event-Driven Architecture**:
+1.  **FastAPI Entrypoint**: Multi-source ingestion (Slack threads + Git Webhooks).
+2.  **Redis Broker**: Handshakes the data to background workers via **ARQ**.
+3.  **The Intelligence (Brain)**:
+    - `ExcuseDetector`: Analyzing the "Human Layer" (Sentiment).
+    - `SlippageAnalyst`: Analyzing the "Code Layer" (Promise-vs-Reality).
+    - `TruthGapDetector`: Correlating the two for 360-degree accountability.
+4.  **Persistence Layer**: PostgreSQL (via SQLModel) stores unified identities and historical scores.
+5.  **Intervention Layer**: Outbound Slack Webhooks with precision @mentions.
 
 ---
 
 ## 🚦 Core Workflows
 
-### 1. The "Commitment Ingestion" Flow
-When a user makes a vague promise in a public channel:
-- **Action**: Call `POST /ingest/raw`.
-- **Mechanics**: The `CommitmentExtractor` agent parses the text. It identifies the **Who** (Owner), **What** (Task), and **When** (Deadline).
-- **Result**: A structured record is ready for tracking.
-
-### 2. The "Accountability Loop"
-This is the heartbeat of the platform.
-- **Action**: Call `POST /evaluate`.
-- **Step 1: Excuse Analysis**: The agent determines if a delay is "Legitimate," "Deflection," or a "Burnout Signal."
-- **Step 2: Risk Scoring**: A score (0-1) is generated based on the check-in sentiment and historical reliability.
-- **Step 3: Burnout Detection**: The agent looks for linguistic markers of fatigue or loss of copability.
-- **Step 4: Adaptation**: The `ToneAdapter` selects a communication style:
-    - `Supportive`: For high-performers showing burnout signs.
-    - `Firm`: For repeat deflectors.
-- **Step 5: Intervention**: A background job is scheduled. If the risk remains high, a **Slack Alert** is sent.
+### 1. Ingestion: Behavioral vs. GitOps
+- **Behavioral**: Call `POST /ingest/raw`. Extracts who/what/when from chat.
+- **GitOps**: Call `POST /ingest/git`. Extracts commitments from commit messages and PR descriptions.
+- **Identity Fusion**: Use `POST /users/config/git` and `/slack` to link emails and Slack IDs to a single human owner.
+
+### 2. The "Unified Accountability Loop"
+1.  **Evaluation**: Triggered via `POST /evaluate`.
+2.  **Slippage Check**: The agent cross-references the check-in sentiment against recent technical evidence.
+3.  **Truth Gap Analysis**: If a user claims 90% progress but Git shows 0 changes, the `TruthGapDetector` flags a discrepancy.
+4.  **Tone Selection**: `ToneAdapter` scales pressure (Supportive for fatigue, Confrontational for deflection).
+5.  **Intervention**: If risk is High/Critical, an autonomous Slack follow-up is triggered.
 
 ---
 
-## 💬 Slack Integration Guide
+## 💬 Integration Guide
 
-### Setting up @Mentions
-To make the agent mention specific people:
-1. Find the user's **Slack Member ID** (Click profile -> More -> Copy member ID).
-2. Call the mapping endpoint:
-   ```bash
-   POST /users/config/slack?user_id=internal_id&slack_id=U12345678
-   ```
-3. From now on, any alert for `internal_id` will ping `@User` in Slack.
+### Setting up @Mentions & Git Mapping
+To unify a developer's identity:
+1.  **Slack**: Find Member ID (e.g., `U12345`). Map with `POST /users/config/slack`.
+2.  **Git**: Map their dev email with `POST /users/config/git`.
+3.  **Result**: CommitGuard now knows that `dev@company.com` on GitHub is the same person as `@John` on Slack.
 
 ---
 
 ## 🧪 Testing and Quality
 CommitGuard AI enforces a **90% coverage threshold**.
 - **Unit Tests**: Test individual agent logic in `src/agents/`.
-- **Integration Tests**: Verify the loop from API to Database.
-- **Mock Mode**: Set `LLM_PROVIDER="mock"` in `.env` to run tests without hitting your API credits.
+- **Performance Tests**: Verify the correlation logic in `tests/test_performance.py`.
+- **Mock Mode**: Set `LLM_PROVIDER="mock"` to run full-suite tests without hitting API credits.
 
 ---
 
 ## 🚀 Scaling for Production
-- **Database**: The system is pre-configured for **PostgreSQL**. Simply update your `DATABASE_URL`.
-- **Concurrency**: Scale your background processing by spinning up multiple `worker` containers in `docker-compose.yml`.
-- **Observability**: Monitor system health at `:8000/metrics` via the integrated Prometheus exporter.
+- **Database**: Pre-configured for **PostgreSQL**. Update your `DATABASE_URL` in `.env`.
+- **Concurrency**: Scale by increasing `worker` replicas in `docker-compose.yml`.
+- **Observability**: Live metrics at `:8000/metrics`.

docs/guides/gitops.md

@@ -0,0 +1,35 @@
+# GitOps Accountability Guide 🛠️
+
+In the engineering world, commitments aren't just made in Slack; they are made in **Source Code**.
+
+## 🔴 The Problem
+Technical debt often accumulates because of "soft promises" made in code comments or commit messages:
+- *"TODO: Refactor this DB connector."*
+- *"I'll fix this auth bug in the next PR."*
+- *"Temporary hack, will clean up tonight."*
+
+These promises "vanish" because no project management tool monitors them.
+
+## 🟢 The Solution: CommitGuard GitOps
+CommitGuard monitors your repository at the source level.
+
+### 1. Extraction from Commits
+If a commit message contains a promise (Who/What/When), the **CommitmentExtractor** identifying it as a formal obligation.
+```bash
+POST /ingest/git
+{
+  "author_email": "dev@company.com",
+  "message": "Fixing CSS. I promise to refactor the login logic by Friday."
+}
+```
+
+### 2. Fulfillment Analysis (Slippage)
+The **SlippageAnalyst** looks at the subsequent PR. 
+*   **The Check**: Did the promised refactor actually happen?
+*   **The Result**: If the code doesn't match the promise, the agent flags **"Shadow Debt"** and alerts the team.
+
+### 3. Truth Gap Detection
+When you provide a check-in via Slack, CommitGuard cross-references it with your recent Git activity.
+*   **User**: *"I'm almost done refactoring."*
+*   **Git**: *0 lines changed in 48 hours.*
+*   **Agent**: *"I noticed no code changes. Is there a blocker I can help with?"* (Tone: Supportive but firm).

mkdocs.yml

@@ -57,6 +57,8 @@ nav:
   - Usage Guides:
       - Quick Start: guides/quickstart.md
       - Slack Integration: guides/slack.md
+      - GitOps Accountability: guides/gitops.md
+
   - API Reference:
       - Endpoint Specs: reference/api.md