docs: finalized documentation audit, branding alignment, and feature documentation

Author: darestack

README.md

@@ -11,7 +11,7 @@
 
 > **"One Engine. Two Worlds. Total Accountability."**
 
-[**Full Documentation 📚**](https://daretechie.github.io/CommitVigil/) | [**Safety Validation Report 🛡️**](https://daretechie.github.io/CommitVigil/validation/safety_validation_report/)
+[**Full Documentation 📚**](https://daretechie.github.io/CommitVigil/) | [**Live Site 🌐**](https://daretechie.github.io/CommitVigil/) | [**Safety Validation Report 🛡️**](https://daretechie.github.io/CommitVigil/validation/safety_validation_report/)
 
 ---
 

docs/guides/quickstart.md

@@ -12,18 +12,21 @@ docker-compose up --build
 ## 🏗️ Local Setup
 1.  **Install dependencies**:
     ```bash
+    # Recommendation: Use uv for high-performance dependency resolution
     uv sync
+    # OR standard poetry
+    poetry install
     ```
 2.  **Configure Environment**:
     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
-    uv run uvicorn src.main:app --reload
+    poetry run uvicorn src.main:app --reload
     ```
 4.  **Run the Worker**:
     ```bash
-    uv run arq src.worker.WorkerSettings
+    poetry run arq src.worker.WorkerSettings
     ```
 
 ---

docs/overviews/agents.md

@@ -22,10 +22,17 @@ The final decision is a personalized intervention:
 - **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.
+The "Overwatch" layer acts as a final sanity check before any intervention is sent. It enforces the **Industry-Specific Semantic Firewall**:
+- **Healthcare (HIPAA)**: Hard-blocks unauthorized PII or clinical mandates.
+- **Finance (SEC)**: Prevents market manipulation or non-compliant financial advice.
+- **HR Violations**: Guards against illegal firing or salary negotiations.
+
+## 5. Cultural Persona Architecture
+CommitVigil adapts the **ToneAdapter** to the cultural context of the user:
+- **Japanese (`ja`)**: High-context, polite, and face-saving interventions.
+- **German (`de`)**: Direct, technical, and objective accountability.
+- **African Ubuntu (`en-AF`)**: Communal, relationship-centric, and narrative-driven check-ins.
+- **British (`en-UK`)**: Nuanced, polite persistence.
 
 ---
 

docs/overviews/ethics.md

@@ -11,28 +11,31 @@ One of our most discussed features is the **"Confrontational"** tone. Here is ho
 *   **The Burnout Safety Valve**: If the `ExcuseDetector` identifies signs of fatigue, the system **blocks** confrontational escalation and triggers a "Burnout Alert" for the manager instead. 
 *   **Tone Drift & Cooling-off**: To prevent morale fatigue, the system implements **mathematical tone-damping**. If a user receives **3 consecutive "Firm" or "Confrontational" follow-ups**, the logic automatically locks the agent into a `NEUTRAL` or `SUPPORTIVE` state for 48 hours (configurable via `COOLING_OFF_PERIOD_HOURS`).
 
-## 2. Nuanced Hard-Blocking (The "Ethics Firewall")
-We explicitly distinguish between "Business Aggression" and "HR Violations." The **Safety Supervisor** enforces a **Semantic Firewall**:
-*   **BLOCKED (HR Territory)**: Discussions involving `Salary`, `PIP` (Performance Improvement Plans), `Firing`, or `Legal Threats` are immediately blocked. This is a hard-coded safety guarantee.
-*   **ALLOWED (Business Territory)**: Aggressive discussions about `Pricing Models`, `Budgeting`, or `Resource Allocation` are permitted as valid professional discourse.
+## 2. Industry-Specific Semantic Firewall 🧱
+CommitVigil provides hard-coded safety guarantees for regulated industries:
+*   **Healthcare (HIPAA)**: The system hard-blocks unauthorized medical mandates or PII disclosure. 
+*   **Finance (SEC)**: Prevents the agent from accidentally facilitating market manipulation or providing unregulated financial advice.
+*   **HR Territory**: Discussions involving `Salary`, `PIP` (Performance Improvement Plans), or `Firing` are immediately escalated to human review.
 
 
 
-## 2. Cultural & Contextual Sensitivity
-"Deflection" is relative. What is seen as blunt in one culture is polite in another:
+## 3. Continuous Learning & ROI Metrics 📈
+CommitVigil doesn't just act; it learns:
+*   **Manager Feedback Loop**: Every intervention can be reviewed by a supervisor. Their "Accept/Modify/Reject" decisions are persisted.
+*   **ROI Dashboard**: The system calculates the **Intervention Acceptance Rate** to quantify the AI's alignment with management intent.
 
 *   **Sensitivity Calibration**: CommitVigil supports **Cultural Tone Profiles**. Managers can calibrate the "Pressure Sensitivity" of the agents to match their specific team norms (e.g., High-Directness vs. High-Context locales).
 *   **Domain-Specific Jargon**: The NLP models are refined to recognize that certain industry vernacular (e.g., *"I'm swamped"*) may be a routine status update rather than an excuse in specific high-velocity teams.
 
-## 3. Privacy & Data Integrity
+## 4. Privacy & Data Integrity
 
 Monitoring at the granularity of Slack threads and Git commits requires a strict privacy stance:
 
 *   **Scoped Monitoring**: CommitVigil is designed to monitor designated `#project` channels, not private DMs or unrelated chatter.
 *   **Source-Level Only**: Commit monitoring is restricted to commit messages and PR metadata—not the proprietary logic within the source code files themselves.
 *   **Identity Anonymization**: Internal IDs are used for analysis; real names can be masked in the database if necessary.
 
-## 3. Handling Ambiguity (The "100% Visibility" Claim) 🧠
+## 5. Handling Ambiguity (The "100% Visibility" Claim) 🧠
 Ambiguity is the greatest challenge in Engineering NLP. Here is how we move toward high accuracy:
 
 *   **Confidence Scores**: Every extraction (Commitment, Risk, Excuse) is accompanied by a `confidence_score`.

docs/reference/api.md

@@ -30,6 +30,13 @@ CommitVigil provides a clean RESTful interface for all operations.
       show_root_heading: true
       show_source: false
 
+## 🏢 Enterprise Departmental Audits
+
+::: src.api.routes.get_departmental_audit
+    options:
+      show_root_heading: true
+      show_source: false
+
 ### Exporting Reports
 The audit endpoint supports three formats via the `report_format` query parameter:
 - **`json`** (Default): Standard API response for integration.

src/api/routes.py

@@ -145,7 +145,11 @@ async def get_performance_audit(user_id: str, report_format: str = "json"):
     analyst = SlippageAnalyst()
     detector = TruthGapDetector()
 
-    from src.schemas.performance import SlippageAnalysis, TruthGapAnalysis, SlippageStatus
+    from src.schemas.performance import (
+        SlippageAnalysis,
+        TruthGapAnalysis,
+        SlippageStatus,
+    )
 
     try:
         slippage = await analyst.analyze_performance_gap(promised, reality)
@@ -158,13 +162,13 @@ async def get_performance_audit(user_id: str, report_format: str = "json"):
             fulfillment_ratio=0.0,
             detected_gap="The developer promised to refactor the API, fix CSS, and update docs, but only updated some typos in README. No major code changes detected.",
             risk_to_system_stability=0.8,
-            intervention_required=True
+            intervention_required=True,
         )
         gap = TruthGapAnalysis(
             gap_detected=True,
             truth_score=0.1,
             explanation="The user claims to be 90% done with the refactor, but the technical evidence only shows updates to typos in the README with no major code changes detected.",
-            recommended_tone="skeptical"
+            recommended_tone="skeptical",
         )
 
     # 3. Compile Report
@@ -201,6 +205,7 @@ async def log_safety_feedback(feedback: CorrectionFeedback):
     )
     return {"status": "logged", "message": "Safety feedback recorded for model tuning."}
 
+
 @router.get("/reports/department/{department}", dependencies=[Depends(get_api_key)])
 async def get_departmental_audit(department: str):
     """
@@ -218,13 +223,36 @@ async def get_departmental_audit(department: str):
             members = list(result.scalars().all())
 
         if not members:
-            logger.info("no_department_members_found_falling_back_to_demo_mock", department=department)
+            logger.info(
+                "no_department_members_found_falling_back_to_demo_mock",
+                department=department,
+            )
             members = [
-                UserHistory(user_id="lead_rockstar", reliability_score=98.5, department=department),
-                UserHistory(user_id="senior_reliable", reliability_score=92.0, department=department),
-                UserHistory(user_id="mid_slipping", reliability_score=45.0, department=department),
-                UserHistory(user_id="junior_burnout", reliability_score=62.0, department=department),
-                UserHistory(user_id="new_hire_risk", reliability_score=38.0, department=department)
+                UserHistory(
+                    user_id="lead_rockstar",
+                    reliability_score=98.5,
+                    department=department,
+                ),
+                UserHistory(
+                    user_id="senior_reliable",
+                    reliability_score=92.0,
+                    department=department,
+                ),
+                UserHistory(
+                    user_id="mid_slipping",
+                    reliability_score=45.0,
+                    department=department,
+                ),
+                UserHistory(
+                    user_id="junior_burnout",
+                    reliability_score=62.0,
+                    department=department,
+                ),
+                UserHistory(
+                    user_id="new_hire_risk",
+                    reliability_score=38.0,
+                    department=department,
+                ),
             ]
 
         # ROI Calculation: Intervention Acceptance
@@ -238,11 +266,31 @@ async def get_departmental_audit(department: str):
         return AuditReportGenerator.generate_departmental_audit(
             department=department,
             members=[
-                UserHistory(user_id="lead_rockstar", reliability_score=98.5, department=department),
-                UserHistory(user_id="senior_reliable", reliability_score=92.0, department=department),
-                UserHistory(user_id="mid_slipping", reliability_score=45.0, department=department),
-                UserHistory(user_id="junior_burnout", reliability_score=62.0, department=department),
-                UserHistory(user_id="new_hire_risk", reliability_score=38.0, department=department)
+                UserHistory(
+                    user_id="lead_rockstar",
+                    reliability_score=98.5,
+                    department=department,
+                ),
+                UserHistory(
+                    user_id="senior_reliable",
+                    reliability_score=92.0,
+                    department=department,
+                ),
+                UserHistory(
+                    user_id="mid_slipping",
+                    reliability_score=45.0,
+                    department=department,
+                ),
+                UserHistory(
+                    user_id="junior_burnout",
+                    reliability_score=62.0,
+                    department=department,
+                ),
+                UserHistory(
+                    user_id="new_hire_risk",
+                    reliability_score=38.0,
+                    department=department,
+                ),
             ],
-            intervention_rate=0.88
+            intervention_rate=0.88,
         )

src/core/database.py

@@ -79,14 +79,14 @@ async def update_user_reliability(
             user.total_commitments += 1
             if was_failure:
                 user.failed_commitments += 1
-        
+
         # 1.5 Cooling-off Logic: Reset strict intervention counter if enough time has passed
         if user.last_intervention_at:
             last_int = user.last_intervention_at
             # SQLite returns naive datetimes; ensure comparison is aware
             if last_int.tzinfo is None:
                 last_int = last_int.replace(tzinfo=timezone.utc)
-            
+
             time_since_last = datetime.now(timezone.utc) - last_int
             if time_since_last > timedelta(hours=settings.COOLING_OFF_PERIOD_HOURS):
                 user.consecutive_firm_interventions = 0

src/core/reporting.py

@@ -240,12 +240,12 @@ def generate_departmental_audit(
         total_rel = sum(m.reliability_score for m in members)
         avg_rel = round(total_rel / len(members), 2)
 
-        top_perf = [
-            m.user_id for m in members if m.reliability_score >= 90.0
-        ][:5]  # Top 5
-        critical = [
-            m.user_id for m in members if m.reliability_score < 50.0
-        ][:5]  # Bottom 5
+        top_perf = [m.user_id for m in members if m.reliability_score >= 90.0][
+            :5
+        ]  # Top 5
+        critical = [m.user_id for m in members if m.reliability_score < 50.0][
+            :5
+        ]  # Bottom 5
 
         # Heuristic: If reliability is dropping rapidly across the team, flag it.
         # For this demo, we'll assume a static check.

src/schemas/agents.py

@@ -125,7 +125,9 @@ class UserHistory(SQLModel, table=True):
     reliability_score: float = Field(default=100.0)
 
     # Enterprise Attributes
-    department: str = Field(default="engineering", index=True)  # engineering, hr, research, finance
+    department: str = Field(
+        default="engineering", index=True
+    )  # engineering, hr, research, finance
     industry_type: str = Field(default="generic")  # healthcare, finance, generic
     language_preference: str = Field(default="en")  # en, en-UK, ja, de
 

tests/test_database.py

@@ -86,14 +86,15 @@ async def test_git_email_flow():
 @pytest.mark.asyncio
 async def test_cooling_off_reset():
     from src.core.database import AsyncSessionLocal
+
     user_id = "cooling_off_user"
-    
+
     # 1. Setup user with strict interventions and a recent timestamp
     async with AsyncSessionLocal() as session:
         user = UserHistory(
             user_id=user_id,
             consecutive_firm_interventions=5,
-            last_intervention_at=datetime.now(timezone.utc)
+            last_intervention_at=datetime.now(timezone.utc),
         )
         session.add(user)
         await session.commit()
@@ -103,11 +104,13 @@ async def test_cooling_off_reset():
         statement = select(UserHistory).where(UserHistory.user_id == user_id)
         results = await session.execute(statement)
         db_user = results.scalar_one()
-        db_user.last_intervention_at = datetime.now(timezone.utc) - timedelta(hours=settings.COOLING_OFF_PERIOD_HOURS + 1)
+        db_user.last_intervention_at = datetime.now(timezone.utc) - timedelta(
+            hours=settings.COOLING_OFF_PERIOD_HOURS + 1
+        )
         await session.commit()
 
     # 3. Update with firm tone. It should detect cooling off, reset to 0, then increment to 1.
     await update_user_reliability(user_id, was_failure=True, tone_used="firm")
-    
+
     _, _, consecutive_firm = await get_user_reliability(user_id)
     assert consecutive_firm == 1  # Reset to 0 then +1