feat(security): implement API key authentication and prompt safety

- Added X-API-Key header authentication (configurable via AUTH_ENABLED)
- Refactored monolithic main.py into modular src/api/routes.py
- Mitigated prompt injection via XML tagging in CommitmentExtractor
- Removed hardcoded database credentials from config defaults
- Updated all documentation with /api/v1 prefix and auth headers
- Updated docs/guides with uv commands and auth configuration steps

Author: darestack

DOCUMENTATION.md

@@ -26,7 +26,7 @@ COPY --from=builder /usr/local/bin /usr/local/bin
 COPY . .
 
 # Ensure the database file is writable by the non-root user if using SQLite
-RUN touch commitguard.db && chown commitguard:commitguard commitguard.db && chmod 666 commitguard.db
+RUN touch commitguard.db && chown commitguard:commitguard commitguard.db && chmod 600 commitguard.db
 RUN chown -R commitguard:commitguard /app
 
 USER commitguard

Dockerfile

@@ -34,34 +34,42 @@ CommitGuard AI is a multi-agent system designed for high-stakes enforcement. It
 
 ---
 
-## 🏗️ The Three-Stage Autonomous Pipeline
+## 🏗️ The Four-Stage Autonomous Pipeline
 Every commitment—whether from Slack or a Git Commit—passes through a deterministic reasoning loop:
 
 1.  **Excuse Detection (`ExcuseDetector`)**: Classifies sentiment (Legitimate vs. Deflection vs. Burnout).
 2.  **Predictive Risk Assessment (`RiskScorer`)**: Quantifies failure probability based on historical reliability.
-3.  **Adaptive Pressure (`ToneAdapter`)**: Selects the psychological tone (Supportive → Firm → Confrontational) to ensure delivery.
+3.  **Safety Supervisor (`Overwatch`)**: Audits final communications for HR/Legal ethics and tone drift.
+4.  **Adaptive Pressure (`ToneAdapter`)**: Selects the psychological tone to ensure delivery.
 
 ---
 
 ## 🛠️ Core Tech Stack
 - **Framework**: FastAPI (Python 3.12+)
 - **LLM Orchestration**: Instructor + Pydantic (Deterministic JSON)
+- **Quality**: Strict MyPy typing + Ruff
 - **Infrastructure**: PostgreSQL + Redis + ARQ
 - **Observability**: Prometheus + Structlog
 
 ---
 
 ## 🚀 API Showcase
+
+> **Note:** All API endpoints require authentication via the `X-API-Key` header.
+
 ### Raw Extraction (Slack/Commit/PR)
 ```bash
 curl -X 'POST' \
-  'http://localhost:8000/ingest/raw?user_id=dev_alpha&raw_text=Fixing%20auth%20logic.%20I%20promise%20to%20refactor%20the%20DB%20connector%20by%20Friday'
+  -H 'X-API-Key: YOUR_API_KEY' \
+  'http://localhost:8000/api/v1/ingest/raw?user_id=dev_alpha&raw_text=Fixing%20auth%20logic.%20I%20promise%20to%20refactor%20the%20DB%20connector%20by%20Friday'
 ```
 
 ### Behavioral Evaluation
 ```bash
 curl -X 'POST' \
-  'http://localhost:8000/evaluate' \
+  -H 'X-API-Key: YOUR_API_KEY' \
+  -H 'Content-Type: application/json' \
+  'http://localhost:8000/api/v1/evaluate' \
   -d '{
   "user_id": "dev_alpha",
   "commitment": "refactor the DB connector",
@@ -72,9 +80,12 @@ curl -X 'POST' \
 ### Performance Integrity Audit (The Deliverable)
 Generate a high-value summary of a developer's communication-vs-technical reality.
 ```bash
-curl -X 'GET' 'http://localhost:8000/reports/audit/dev_alpha'
+curl -X 'GET' \
+  -H 'X-API-Key: YOUR_API_KEY' \
+  'http://localhost:8000/api/v1/reports/audit/dev_alpha'
 ```
 
 
+
 ---
 *Built for High-Performance Teams and Elite Portfolios.*

README.md

@@ -14,9 +14,15 @@ These promises "vanish" because no project management tool monitors them.
 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.
+If a commit message contains a promise (Who/What/When), the **CommitmentExtractor** identifies it as a formal obligation. 
+
+> [!NOTE]
+> The extractor uses a `commitment_found` flag to identify messages with NO clear task, preventing the agent from hallucinating promises.
+
 ```bash
-POST /ingest/git
+POST /api/v1/ingest/git
+Headers: X-API-Key: YOUR_API_KEY
+Body:
 {
   "author_email": "dev@company.com",
   "message": "Fixing CSS. I promise to refactor the login logic by Friday."

docs/guides/gitops.md

@@ -9,26 +9,32 @@ The fastest way to spin up the full stack (API + Worker + Redis + Postgres):
 docker-compose up --build
 ```
 
-## 🏗️ Local Poetry Setup
+## 🏗️ Local Setup
 1.  **Install dependencies**:
     ```bash
-    poetry install
+    uv sync
     ```
 2.  **Configure Environment**:
-    Create a `.env` file based on `.env.example`.
+    Create a `.env` file based on `.env.example`. 
+    > **Important**: Set `API_KEY_SECRET` to a secure value for production. Set `AUTH_ENABLED=False` for local testing without auth.
 3.  **Run the API**:
     ```bash
-    poetry run uvicorn src.main:app --reload
+    uv run uvicorn src.main:app --reload
     ```
 4.  **Run the Worker**:
     ```bash
-    poetry run arq src.worker.WorkerSettings
+    uv run arq src.worker.WorkerSettings
     ```
 
 ---
 
-## 🧪 Running the Test Suite
-Standardized tests are enforced with 90%+ coverage.
+## 🧪 Quality and Stability
+CommitGuard AI enforces military-grade engineering standards:
+- **Mock Mode**: Set `LLM_PROVIDER="mock"` in `.env` to run the entire system with zero token cost.
+- **Strict Typing**: The system is fully compliant with `mypy` strict type checking. Run `poetry run mypy src/` to verify correctness.
+- **Coverage**: All critical agents maintain a high test coverage threshold.
+
 ```bash
-poetry run pytest
+# Run tests with clean output
+uv run pytest
 ```

docs/guides/quickstart.md

@@ -22,7 +22,8 @@ CommitGuard can ping users directly using their **Slack Member ID**.
 Call the configuration endpoint with the user's Slack ID (found in their Slack Profile -> More -> Copy Member ID):
 
 ```bash
-POST /users/config/slack?user_id=john_dev&slack_id=U12345678
+POST /api/v1/users/config/slack?user_id=john_dev&slack_id=U12345678
+Headers: X-API-Key: YOUR_API_KEY
 ```
 
 ### The Result

docs/guides/slack.md

@@ -9,17 +9,18 @@
 In modern distributed teams, the **"Slack Stall"** is the #1 drain on project velocity. Project Managers are overwhelmed by vague promises like *"I'll get to it soon,"* which are often forgotten, leading to missed sprints and "bad guy" escalations.
 
 ## ✅ The Solution
-CommitGuard AI is a standalone, agentic service designed to monitor and enforce professional commitments. It doesn't just "track tasks"; it acts as a proactive collaborator that:
+CommitGuard AI is a standalone, agentic service designed to monitor and enforce professional commitments. Every commitment passes through a **4-Stage Reasoning Pipeline**:
 
-1.  **Extracts Vague Promises**: Automatically parses Slack threads to create structured commitment records.
-2.  **Predicts Failure**: Uses behavioral sentiment to flag burnout or deflection *before* the deadline passes.
-3.  **Automates Calibration**: Adjusts its tone—Supportive for burnout, Firm for repeat offenders—saving the PM from having to chase updates.
+1.  **Extraction**: Automatically parses Slack threads or Git commits to identify {who, what, when}.
+2.  **Excuse Analysis**: Categorizes sentiment (Legitimate vs. Deflection vs. Burnout).
+3.  **Risk Scoring**: Quantifies failure probability based on historical reliability.
+4.  **Safety Overwatch**: Audits interventions for ethics, tone drift, and HR compliance.
 
 ---
 
 ## 🏗️ Architecture at a Glance
 CommitGuard AI is built on a **Decoupled Event-Driven Architecture**:
-- **FastAPI Entrypoint**: High-speed ingestion.
-- **Redis & ARQ**: Distributed background processing.
-- **The Brain**: Pluggable LLM reasoning loop.
-- **PostgreSQL**: Industrial-grade persistence.
+- **FastAPI Entrypoint**: High-speed ingestion for Slack and Git webhooks.
+- **Redis & ARQ**: Distributed background processing for high-volume orchestration.
+- **The Brain**: Multi-agent LLM reasoning loop.
+- **PostgreSQL**: Industrial-grade persistence with atomic row-locking for score integrity.

docs/index.md

@@ -19,6 +19,13 @@ The final decision is a personalized intervention:
 - **Tone: Supportive** - If risk is high but burnout is detected.
 - **Tone: Firm** - If risk is high and the user has a history of deflection.
 - **Tone: Neutral** - For standard updates.
+- **Tone: Confrontational** - For repeat deflection.
+
+## 4. Safety Audit (`SafetySupervisor`)
+The "Overwatch" layer acts as a final sanity check before any intervention is sent. It prevents:
+- **HR Violations**: Blocking discussions on salary or firing.
+- **Tone Drift**: Catching if an agent accidentally becomes too aggressive.
+- **Ambiguity**: Flagging if the agent's confidence in its own verdict is low.
 
 ---
 

docs/overviews/agents.md

@@ -29,8 +29,8 @@ The "Secret Sauce" of CommitGuard is in the **System Prompts**. You can find and
 
 ---
 
-## 3. Message Lifecycle & "Overwatch" Architecture 🛰️
-The Safety Supervisor follows a **Post-Generation Overwatch** pattern. This ensures that the system is self-healing without entering infinite regeneration loops.
+## 3. Message Lifecycle & "Safety Overwatch" 🛰️
+The **Safety Supervisor** follows a **Post-Generation Overwatch** pattern. This ensures that the system is self-healing without entering infinite regeneration loops.
 
 ```mermaid
 graph TD