Skip to content

Commit 22f8608

Browse files
darestackdarestack
committed
docs: rewrite README — remove fake metrics badges, lead with webhook architecture
1 parent e1a60b6 commit 22f8608

1 file changed

Lines changed: 66 additions & 122 deletions

File tree

‎README.md‎

Lines changed: 66 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -1,154 +1,98 @@
1-
# CommitVigil: Real-time monitoring and alerting for GitHub commit activity. Track sensitive changes, secrets exposure, or team velocity with automated notifications.
1+
# CommitVigil
22

3-
![CommitVigil Hero](docs/assets/hero.jpg)
3+
[![CI](https://github.com/daretechie/CommitVigil/actions/workflows/ci.yml/badge.svg)](https://github.com/daretechie/CommitVigil/actions/workflows/ci.yml)
4+
![Python](https://img.shields.io/badge/python-3.12%2B-blue)
45

5-
<!-- Badges: Enterprise Metrics -->
6-
[![Tests](https://github.com/daretechie/CommitVigil/actions/workflows/ci.yml/badge.svg)](https://github.com/daretechie/CommitVigil/actions/workflows/ci.yml)
7-
![Throughput](https://img.shields.io/badge/throughput_benchmark-1250%20msg%2Fsec-blue?style=for-the-badge)
8-
![Latency](https://img.shields.io/badge/target_P95_latency-<500ms-success?style=for-the-badge)
9-
![Cost Savings](https://img.shields.io/badge/avg_token_savings-85%25-orange?style=for-the-badge)
10-
![ROI](https://img.shields.io/badge/est_net_ROI-%24558%2Fmonth-gold?style=for-the-badge)
11-
![Security](https://img.shields.io/badge/Security-Audit_Passed-success?style=for-the-badge)
12-
![Test Coverage](https://img.shields.io/badge/Coverage-85%25-success?style=for-the-badge)
13-
14-
> **"The truth lives in the code. Accountability vive in the engine."**
15-
16-
[**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/) | [**Manager Feedback Guide 🎮**](docs/guides/feedback_loop.md) | [**Integration Guide 🔌**](docs/guides/integrations.md)
6+
> GitHub webhook listener that monitors commits and pull requests for risky patterns,
7+
> evaluates developer commitments against actual delivery, and sends Slack alerts on violations.
178
189
---
1910

20-
## 🆘 The Problem
21-
In modern distributed teams, the **"Slack Stall"** is the #1 drain on project velocity.
22-
Managers are overwhelmed by vague promises—*"I'll get to it soon,"* or *"It's almost done"*—which are often forgotten or delayed, leading to missed sprints and expensive "bad guy" escalations.
11+
## What It Does
2312

24-
## ✅ The Solution
25-
CommitVigil is a standalone, AI-powered **Accountability Specialist**. It doesn't just "monitor"—it **predicts** failure before it happens by mapping verbal commitments in Slack/Teams to actual technical reality in Git/Jira.
13+
CommitVigil sits between your GitHub repository and your team's Slack channel. It:
2614

27-
### 🎯 The "Truth-Gap" Engine
28-
Our multi-agent system extracts {who, what, when} from conversations and cross-references them with technical metadata to identify:
29-
* **Burnout Signals**: Spotting over-commitment before it leads to regression.
30-
* **Commitment Drift**: Quantifying the delta between "what was promised" and "what was pushed."
31-
* **Behavioral Nudges**: Automatically adapting intervention tone based on culture and urgency.
15+
1. **Receives GitHub webhook events** — push, pull_request, commit comment
16+
2. **Scans for risky patterns**:
17+
- Direct pushes to `main`/`master` without a PR
18+
- Unusually large diffs (configurable threshold)
19+
- Commit messages containing secret-like strings
20+
- Soft commitments ("I'll fix this later", "TODO: refactor") tracked against follow-through
21+
3. **Scores and classifies** the event using structured LLM extraction (Instructor + Pydantic)
22+
4. **Sends a Slack alert** with the violation type, commit author, and diff link
3223

3324
---
3425

35-
## 💼 Hire for "Integrity Audit" Services
36-
Want to verify your team's velocity before a major release or acquisition? I offer specialized **Accountability Consulting** using this CommitVigil engine:
37-
* **Forensic Audits**: Truth-gap detection between Slack/Jira and Git reality.
38-
* **Burnout Prevention**: Strategic agentic follow-ups to protect at-risk developers.
39-
* **Boardroom Reporting**: Professional, glassmorphic HTML ROI briefs for C-level visibility.
40-
41-
[**Inquire on Upwork 🚀**](https://www.upwork.com/)
42-
43-
---
44-
45-
46-
## 🎭 Dual-Persona Versatility
26+
## Architecture
4727

48-
CommitVigil is a multi-agent system designed for high-stakes enforcement. It adapts its identity based on the operational environment:
49-
50-
### 1. The Behavioral Accountability Agent (Management)
51-
**Headline:** *"Autonomous AI Agents for High-Stakes Accountability & Performance Enforcement"*
52-
- **Problem:** Remote teams struggle with "commitment drift" and excuse-making.
53-
- **Solution:** Proactively monitor chat promises.
54-
- **Outcome:** Support burnout signals early; confront repeat deflection firmly.
28+
```
29+
GitHub Repository
30+
└── Webhook (push / pull_request events)
31+
└── CommitVigil API (FastAPI)
32+
├── Ingest: validates HMAC signature → queues job (ARQ + Redis)
33+
├── Worker: pattern scan → LLM evaluation → risk score
34+
│ ├── Direct-push detector
35+
│ ├── Large-diff detector (threshold: configurable)
36+
│ └── Secret-pattern regex scan
37+
└── Alert dispatcher → Slack Incoming Webhook
38+
```
5539

56-
### 2. The GitOps Accountability Engine (Engineering)
57-
**Headline:** *"AI-Driven GitOps Accountability: Guaranteeing Commitment Follow-Through"*
58-
- **Problem:** Small technical promises in commits/PRs (e.g., *"I'll fix this later"*) vanish into the noise.
59-
- **Solution:** NLP-driven monitoring of source code level commitments.
60-
- **Outcome:** 100% visibility into "soft commitments" made during the dev cycle.
40+
**Async processing:** Events are acknowledged immediately (200 OK) and processed by an ARQ background worker — GitHub's 10-second timeout is never a concern.
6141

6242
---
6343

64-
### 🛡️ 2026 Enterprise Upgrade: Autonomous Adaptation
65-
The system now includes self-evolving capabilities for global operations:
66-
- **Autonomous Context Sensing**: Automatically detects **Industry** (e.g., Gaming, Biotech) and **Department** (e.g., R&D, Sales) from communication patterns.
67-
- **Hierarchical Safety Enforcement**: Applies rules from specific (Department) to broad (Industry) to generic.
68-
- **Stabilization Layer**: Autonomous rules start as **Unverified** and trigger Human-in-the-Loop review. Once confirmed, context is **Locked** for stability.
69-
- **Cultural Persona Routing**: Automatically adapts tone for **Japanese (*Wa*)**, **German (*Sachlichkeit*)**, **French (Eloquence)**, **British English**, and **Spanish**.
70-
44+
## Tech Stack
7145

72-
## 🏗️ The Four-Stage Autonomous Pipeline
73-
Every commitment—whether from Slack or a Git Commit—passes through a deterministic reasoning loop:
74-
75-
1. **Excuse Detection (`ExcuseDetector`)**: Classifies sentiment (Legitimate vs. Deflection vs. Burnout).
76-
2. **Predictive Risk Assessment (`RiskScorer`)**: Quantifies failure probability based on historical reliability.
77-
3. **Language & Culture Router**: Identifies the primary language and selects the appropriate cultural persona.
78-
4. **Safety Supervisor (`Overwatch`)**: Audits final communications for HR/Legal ethics and **Industry-Specific Semantic Compliance**.
79-
80-
### 💼 Phase 6: Enterprise Sales Intelligence (New)
81-
Transform your security audit into a revenue engine.
82-
- **Automated Prospecting**: The `ProspectingScout` agent generates realistic "Drift Scenarios" for demos based on industry (e.g., Finance, Energy).
83-
- **Multi-Currency ROI**: Interactive calculator for predicting savings in USD, EUR, and GBP.
84-
- **Executive Briefs**: Generates premium HTML one-pagers for C-Level meetings.
46+
| Layer | Technology |
47+
|---|---|
48+
| API | FastAPI (Python 3.12+) |
49+
| Background jobs | ARQ (async Redis queue) |
50+
| LLM extraction | Instructor + Pydantic |
51+
| Database | PostgreSQL |
52+
| Cache / queue | Redis |
53+
| Observability | Prometheus + Structlog |
8554

8655
---
8756

88-
## 🛠️ Core Tech Stack
89-
- **Framework**: FastAPI (Python 3.12+)
90-
- **LLM Orchestration**: Instructor + Pydantic (Deterministic JSON)
91-
- **Quality**: Strict MyPy typing + Ruff
92-
- **Infrastructure**: PostgreSQL + Redis + ARQ
93-
- **Observability**: Prometheus + Structlog
57+
## Quick Start
9458

95-
---
96-
97-
## 📂 Project Structure
98-
99-
```text
100-
CommitVigil/
101-
├── src/ # Core Application Logic
102-
├── tests/ # Comprehensive Test Suite
103-
├── infra/ # Infrastructure & Config (Prometheus, K8s, migrations)
104-
├── scripts/ # Ops & Demo Utilities (demo.sh)
105-
├── docs/ # Technical Documentation & ADRs
106-
└── README.md # This document
59+
```bash
60+
git clone https://github.com/darestack/CommitVigil.git
61+
cd CommitVigil
62+
cp .env.example .env # add GITHUB_WEBHOOK_SECRET and SLACK_WEBHOOK_URL
63+
docker compose up -d
10764
```
10865

66+
**Configure GitHub webhook:**
67+
1. Repo → Settings → Webhooks → Add webhook
68+
2. Payload URL: `https://your-domain/api/v1/ingest/raw`
69+
3. Content type: `application/json`
70+
4. Secret: the value from your `.env`
71+
5. Events: Push + Pull requests
10972

11073
---
11174

112-
## 🚀 API Showcase
113-
114-
> **Note:** All API endpoints require authentication via the `X-API-Key` header.
75+
## Example Alert
11576

116-
### Raw Extraction (Slack/Commit/PR)
117-
```bash
118-
curl -X 'POST' \
119-
-H 'X-API-Key: YOUR_API_KEY' \
120-
'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'
12177
```
122-
123-
### Behavioral Evaluation
124-
```bash
125-
curl -X 'POST' \
126-
-H 'X-API-Key: YOUR_API_KEY' \
127-
-H 'Content-Type: application/json' \
128-
'http://localhost:8000/api/v1/evaluate' \
129-
-d '{
130-
"user_id": "dev_alpha",
131-
"commitment": "refactor the DB connector",
132-
"check_in": "Spent all night on it, feeling pretty drained"
133-
}'
78+
⚠️ CommitVigil Alert
79+
Repo: darestack/my-service
80+
Author: daretechie
81+
Event: Direct push to main (no PR)
82+
Commit: a3f9c12 — "hotfix: temp disable auth check"
83+
Risk: HIGH — bypassed code review + suspicious message pattern
84+
Link: https://github.com/darestack/my-service/commit/a3f9c12
13485
```
13586

136-
### Performance Integrity Audit (The Deliverable)
137-
Generate a high-value summary of a developer's communication-vs-technical reality.
138-
```bash
139-
curl -X 'GET' \
140-
-H 'X-API-Key: YOUR_API_KEY' \
141-
'http://localhost:8000/api/v1/reports/audit/dev_alpha'
142-
```
143-
144-
145-
14687
---
147-
## 🤝 Contributing
148-
CommitVigil is open source! We welcome contributions to our "Truth-Gap" engine and cultural personas. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
14988

150-
## 📄 License
151-
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
89+
## Configuration
15290

153-
---
154-
*Built for High-Performance Teams and Elite Portfolios.*
91+
| Variable | Purpose |
92+
|---|---|
93+
| `GITHUB_WEBHOOK_SECRET` | HMAC secret for validating GitHub payloads |
94+
| `SLACK_WEBHOOK_URL` | Incoming webhook URL for Slack alerts |
95+
| `LARGE_DIFF_THRESHOLD` | Line count triggering large-diff alert (default: 500) |
96+
| `DATABASE_URL` | PostgreSQL connection string |
97+
| `REDIS_URL` | Redis connection string |
98+
| `GROQ_API_KEY` / `OPENAI_API_KEY` | LLM provider key |

0 commit comments

Comments
 (0)