feat: architectural remediation, security hardening, and documentation updates

Author: darestack

README.md

@@ -53,7 +53,19 @@ Every commitment—whether from Slack or a Git Commit—passes through a determi
 
 ---
 
-## 🚀 API Showcase
+## � Professional Integrity Audits
+
+Need a deep-dive into your team's commitment reliability? I offer **one-time AI-powered audits** for remote engineering teams. 
+
+- **Extract "Shadow Debt"**: Identify technical promises made in commits that never made it to a PR.
+- **Predict Burnout**: Recognize linguistic patterns of fatigue before they impact velocity.
+- **Reliability Scoring**: Get a multi-dimensional scorecard for your squads.
+
+📧 **[Contact me for an Audit](mailto:adelekedare2012@gmail.com)** to see a sample report and book a 1-hour squad analysis.
+
+---
+
+## �🚀 API Showcase
 
 > **Note:** All API endpoints require authentication via the `X-API-Key` header.
 

docs/guides/gitops.md

@@ -39,3 +39,18 @@ When you provide a check-in via Slack, CommitGuard cross-references it with your
 *   **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).
+### 4. Identity Mapping (Crucial Step)
+To link your Git commits to your Slack profile, you must map your email to your user ID:
+
+```bash
+curl -X POST \
+  -H 'X-API-Key: YOUR_API_KEY' \
+  'http://localhost:8000/api/v1/users/config/git?user_id=Daretechie&email=your-email@example.com'
+```
+
+Once mapped, `identity_matched` will return `true` in ingest responses, and the agent will know exactly who to ping in Slack.
+
+---
+
+> [!TIP]
+> Use the same `user_id` across both Slack and Git mapping to ensure a unified accountability profile.

docs/guides/production.md

@@ -0,0 +1,79 @@
+# Production & Enterprise Deployment Guide 🚀
+
+Scaling CommitGuard AI to 1000+ users requires moving from a local monolithic setup to a distributed, high-availability architecture.
+
+## 🏗️ Enterprise Architecture
+
+For large-scale teams, we separate the **Ingestion Layer** (API) from the **Processing Layer** (Workers).
+
+1.  **API Layer**: Stateless FastAPI pods behind a Load Balancer (AWS ALB / Nginx).
+2.  **Processing Layer**: Distributed `arq` workers scaling horizontally based on queue depth.
+3.  **State Layer**: Managed Redis (AWS ElastiCache) and PostgreSQL (AWS RDS).
+
+---
+
+## ☸️ Kubernetes Orchestration
+
+We provide production-ready K8s manifests in [`infra/k8s/`](file:///home/daretechie/DevProject/GitHub/CommitGuard-AI/infra/k8s/).
+
+### Key Scaling Features:
+- **Replica Sets**: Run multiple API instances to handle high traffic.
+- **Auto-Scaling (HPA)**: Workers automatically scale from **2 to 20+ pods** based on CPU usage or queue backlog.
+- **Resource Constraints**: Strict CPU/Memory limits to prevent noisy-neighbor issues on shared clusters.
+
+### Deployment Command:
+```bash
+kubectl apply -f infra/k8s/
+```
+
+---
+
+## 🔄 Automated Org-Wide Ingestion
+
+Managers don't need to manually ingest commits. Use **GitHub Webhooks** at the Organization level:
+
+1.  Go to **GitHub Organization Settings** -> **Webhooks**.
+2.  Add a new webhook:
+    - **Payload URL**: `https://api.commitguard.yourcloud.com/api/v1/ingest/git`
+    - **Content Type**: `application/json`
+    - **Secret**: Your fixed `API_KEY_SECRET`
+    - **Events**: Select `Pushes`.
+
+**Result**: Every commit from every repo in your organization is automatically processed for accountability.
+
+---
+
+## 🆔 Bulk Identity Sync (SSO)
+
+Mapping 1000+ users via `curl` is inefficient. Implement a **Mapping Sync Service**:
+
+- **Active Directory / Google Workspace**: Write a small cronjob that polls your employee list and calls:
+  - `POST /api/v1/users/config/slack` (Email -> Slack ID)
+  - `POST /api/v1/users/config/git` (Email -> Git Email)
+- **Automatic Discovery**: CommitGuard can be configured to use the Slack `users.lookupByEmail` API to auto-map users on their first commitment.
+
+---
+
+## 📊 Monitoring & Observability
+
+Enterprise deployment includes **Prometheus + Grafana** integration:
+
+- **SLIs (Service Level Indicators)**:
+  - `background_jobs_pending`: How many commitments are waiting for AI processing?
+  - `ai_token_usage_total`: Cost tracking per team/department.
+  - `intervention_acceptance_rate`: How often are managers acting on AI pings?
+
+---
+
+## 💰 FinOps: Optimizing LLM Costs
+
+At 1000+ users, token costs can add up. CommitGuard helps you optimize:
+
+1.  **Provider Switching**: Use **Groq (Llama 3.3 70b)** for high-speed, low-cost extraction, and **OpenAI (GPT-4o)** only for complex tone adaptation.
+2.  **Mock Mode for Non-Critical Repos**: Use `LLM_PROVIDER="mock"` for internal experimental repositories to save budget.
+3.  **Caching**: CommitGuard can be extended with a vector cache (like RedisVL) to reuse extracted tasks from similar commit messages.
+
+---
+
+> [!IMPORTANT]
+> Always deploy in a **Zero-Trust** environment using encrypted secrets and private network VPCs for the Database and Redis.

docs/guides/slack.md

@@ -2,30 +2,83 @@
 
 Transform the agent into a visible collaborator by bridging it to your Slack workspace.
 
-## 1. Webhook Setup
-To receive notifications, you need an **Incoming Webhook URL**:
-1.  Go to [Slack API Apps](https://api.slack.com/apps).
-2.  Create a new app (from scratch).
-3.  Enable **Incoming Webhooks**.
-4.  Add a new webhook to your channel and copy the URL.
+## 1. Webhook Setup (Step-by-Step)
+
+### Step 1: Access Slack API
+1. Open your browser and navigate to **[api.slack.com/apps](https://api.slack.com/apps)**
+2. Sign in with your Slack workspace credentials if prompted
+
+### Step 2: Create a New App
+1. Click the green **"Create New App"** button
+2. Select **"From scratch"** (not from a manifest)
+3. Fill in the form:
+   - **App Name:** `CommitGuard AI` (or any name you prefer)
+   - **Pick a workspace:** Select your Slack workspace from the dropdown
+4. Click **"Create App"**
+
+### Step 3: Enable Incoming Webhooks
+1. After creating the app, you'll land on the **Basic Information** page
+2. In the left sidebar under **"Features"**, click **"Incoming Webhooks"**
+3. Toggle the switch **ON** at the top of the page
+4. You'll see a confirmation: *"Incoming Webhooks are On"*
+
+### Step 4: Add Webhook to Channel
+1. Scroll down to **"Webhook URLs for Your Workspace"**
+2. Click **"Add New Webhook to Workspace"**
+3. A popup will ask: *"Where should CommitGuard AI post?"*
+4. Select your target channel (e.g., `#engineering`, `#accountability`)
+5. Click **"Allow"**
+6. Copy the generated webhook URL:
+   ```
+   https://hooks.slack.com/services/YOUR_WORKSPACE_ID/YOUR_APP_ID/YOUR_WEBHOOK_TOKEN
+   ```
 
 ## 2. Configuration
-Add the URL to your `.env`:
+
+Add the webhook URL to your `.env` file:
+```bash
+SLACK_WEBHOOK_URL="https://hooks.slack.com/services/WORKSPACE_ID/APP_ID/TOKEN"
+```
+
+Restart the service to apply changes:
 ```bash
-SLACK_WEBHOOK_URL="https://hooks.slack.com/services/T000.../B000.../XXXX..."
+docker-compose down && docker-compose up --build
 ```
 
-## 3. User @Mentions (Identity Mapping)
+## 3. Test the Webhook
+
+Verify connectivity with a simple curl command:
+```bash
+curl -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{"text": "🛡️ CommitGuard AI is connected!"}' \
+  'YOUR_WEBHOOK_URL'
+```
+
+You should see `ok` in the terminal and the message in your Slack channel.
+
+## 4. User @Mentions (Identity Mapping)
+
 CommitGuard can ping users directly using their **Slack Member ID**.
 
-### How to map a user:
-Call the configuration endpoint with the user's Slack ID (found in their Slack Profile -> More -> Copy Member ID):
+### How to Find a Slack Member ID
+1. Open Slack and go to the user's profile
+2. Click **"More"** (three dots)
+3. Select **"Copy Member ID"**
 
+### How to Map a User
+Call the configuration endpoint:
 ```bash
-POST /api/v1/users/config/slack?user_id=john_dev&slack_id=U12345678
-Headers: X-API-Key: YOUR_API_KEY
+curl -X POST \
+  -H 'X-API-Key: YOUR_API_KEY' \
+  'http://localhost:8000/api/v1/users/config/slack?user_id=john_dev&slack_id=U12345678'
 ```
 
 ### The Result
 When an alert is triggered, Slack turns the ID into a real mention:
 > 🔔 **CommitGuard Alert for @John:** Checking in on commitment: fix the CSS bugs
+
+---
+
+> [!TIP]
+> You can create multiple webhooks for different channels (e.g., `#urgent-alerts` for critical issues, `#commitment-log` for routine tracking).

infra/k8s/deployment.yaml

@@ -0,0 +1,90 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: commitguard-api
+  labels:
+    app: commitguard-api
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: commitguard-api
+  template:
+    metadata:
+      labels:
+        app: commitguard-api
+    spec:
+      containers:
+      - name: api
+        image: commitguard-ai:latest
+        command: ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]
+        ports:
+        - containerPort: 8000
+        envFrom:
+        - secretRef:
+            name: commitguard-secrets
+        - configMapRef:
+            name: commitguard-config
+        resources:
+          requests:
+            cpu: "250m"
+            memory: "512Mi"
+          limits:
+            cpu: "1000m"
+            memory: "1Gi"
+
+---
+
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: commitguard-worker
+  labels:
+    app: commitguard-worker
+spec:
+  replicas: 5
+  selector:
+    matchLabels:
+      app: commitguard-worker
+  template:
+    metadata:
+      labels:
+        app: commitguard-worker
+    spec:
+      containers:
+      - name: worker
+        image: commitguard-ai:latest
+        command: ["arq", "src.worker.WorkerSettings"]
+        envFrom:
+        - secretRef:
+            name: commitguard-secrets
+        - configMapRef:
+            name: commitguard-config
+        resources:
+          requests:
+            cpu: "500m"
+            memory: "1Gi"
+          limits:
+            cpu: "2000m"
+            memory: "2Gi"
+
+---
+
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: commitguard-worker-hpa
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: commitguard-worker
+  minReplicas: 2
+  maxReplicas: 20
+  metrics:
+  - type: Resource
+    resource:
+      name: cpu
+      target:
+        type: Utilization
+        averageUtilization: 70

src/agents/brain.py

@@ -12,7 +12,6 @@
     BurnoutDetection,
     ExcuseAnalysis,
     ExcuseCategory,
-    ExtractedCommitment,
     PipelineEvaluation,
     RiskAssessment,
     RiskLevel,
@@ -37,9 +36,12 @@ async def analyze_excuse(self, user_input: str) -> ExcuseAnalysis:
             messages=[
                 {
                     "role": "system",
-                    "content": "Analyze the user excuse for commitment failure.",
+                    "content": "Analyze the user excuse for commitment failure provided within <user_excuse> tags.",
+                },
+                {
+                    "role": "user",
+                    "content": f"<user_excuse>\n{user_input}\n</user_excuse>",
                 },
-                {"role": "user", "content": user_input},
             ],
         )
 
@@ -53,13 +55,15 @@ async def assess_risk(
                 {
                     "role": "system",
                     "content": (
-                        "Assess the risk of commitment failure based on history."
+                        "Assess the risk of commitment failure based on the provided "
+                        "history and current status within their respective XML tags."
                     ),
                 },
                 {
                     "role": "user",
                     "content": (
-                        f"History: {historical_context}\nStatus: {current_status}"
+                        f"<historical_context>\n{historical_context}\n</historical_context>\n"
+                        f"<current_status>\n{current_status}\n</current_status>"
                     ),
                 },
             ],
@@ -73,29 +77,17 @@ async def detect_burnout(self, user_input: str) -> BurnoutDetection:
                 {
                     "role": "system",
                     "content": (
-                        "Detect signs of professional burnout in the user input."
+                        "Detect signs of professional burnout in the user input provided within <user_input> tags."
                     ),
                 },
-                {"role": "user", "content": user_input},
-            ],
-        )
-
-    async def extract_commitment(self, raw_input: str) -> ExtractedCommitment:
-        return await self.provider.chat_completion(
-            response_model=ExtractedCommitment,
-            model=self.model,
-            messages=[
                 {
-                    "role": "system",
-                    "content": (
-                        "Extract a task and deadline from the user's "
-                        "natural language promise."
-                    ),
+                    "role": "user",
+                    "content": f"<user_input>\n{user_input}\n</user_input>",
                 },
-                {"role": "user", "content": raw_input},
             ],
         )
 
+
     async def evaluate_participation(
         self,
         user_id: str,