engrm 0.1.0

package/SENTINEL.md

@@ -0,0 +1,293 @@
+# Engrm Sentinel — Real-Time AI Audit for Coding Agents
+
+**Status**: Planned (Phase 5)
+**Target Launch**: April 22, 2026 (6 weeks from 2026-03-11)
+**Tier**: Pro + Team (paid upsell feature)
+
+## Executive Summary
+
+Sentinel is a real-time code validation layer that intercepts AI agent tool calls (file writes, edits) **before execution**, retrieves team-specific coding standards from Engrm's vector memory, and routes the diff through a configurable audit LLM for judgment. If the code violates team standards, Sentinel blocks the write and tells the agent exactly what to fix — the agent self-corrects automatically.
+
+No competitor offers this. Every existing AI code review tool (CodeRabbit, Qodo, Greptile, Ellipsis) operates at PR level — **after** code is written. Sentinel operates at the pre-execution level, preventing mistakes before they happen.
+
+## Market Gap
+
+```
+                    Static Standards          Dynamic RAG Standards
+                    ─────────────────         ──────────────────────
+PR-Level Review  │  CodeRabbit ($24)     │   Qodo ($30)
+                 │  Ellipsis ($20)       │   Greptile ($30)
+                 │  Sourcery ($12)       │
+                 │  Copilot ($19-39)     │
+─────────────────┼───────────────────────┼─────────────────────────
+Real-Time        │  decider/claude-hooks │
+Pre-Execution    │  trailofbits config   │   ← ENGRM SENTINEL
+Interception     │  (local-only, no RAG) │     (UNOCCUPIED)
+```
+
+### Competitive Research (March 2026)
+
+| Tool | Pricing | Timing | Custom Standards | RAG/Vector | Agent Hooks |
+|------|---------|--------|-----------------|------------|-------------|
+| CodeRabbit | $0-24/dev/mo | PR-level + IDE inline | Yes (.coderabbit.yml) | No | No |
+| Qodo | $0-30/dev/mo | PR-level + IDE | Yes (auto-generated) | Yes (proprietary) | No |
+| Greptile | $30/dev/mo | PR-level | Learns from PRs | Yes (AST + vector) | No |
+| Ellipsis | ~$20/dev/mo | PR-level | Yes (natural language) | No | No |
+| Cursor Bugbot | Included ($20-40/mo) | PR-level (background) | .cursor/rules | Proprietary | Cursor-only |
+| Copilot Review | $19-39/user/mo | PR-level | Repository rules | Proprietary | Copilot-only |
+| **Engrm Sentinel** | **$15-25/dev/mo** | **Pre-execution** | **Dynamic RAG** | **Hybrid FTS5+vec** | **Any MCP agent** |
+
+### GitHub Reference Implementations
+
+| Repo | Stars | Pattern | What We Learn |
+|------|-------|---------|--------------|
+| disler/claude-code-hooks-mastery | 3.3k | Builder/Validator agents, PostToolUse linting | Builder/Validator separation pattern |
+| trailofbits/claude-code-config | 1.6k | Security blocking hooks, anti-rationalization gate | Stop hook prompt checking for incomplete work |
+| qodo-ai/pr-agent | 10.5k | PR review tools, AGPL | PR compression for large diffs |
+| ChrisWiles/claude-code-showcase | 5.5k | Skills, agents, GitHub Actions | Skill evaluation hook as pattern |
+| decider/claude-hooks | 67 | Static rule enforcement | Hierarchical config (root + dir overrides) |
+| praneybehl/code-review-mcp | 29 | MCP server for multi-provider review | Stateless — no memory, no team sharing |
+
+**Key insight**: Every existing implementation is stateless. None retrieves project-specific standards from vector memory. None syncs findings across a team.
+
+## Architecture
+
+### Flow
+
+```
+Developer working with Claude Code...
+
+Claude tries to write a file
+    │
+    ▼
+PreToolUse(Write|Edit) fires → hooks/sentinel.ts
+    │
+    ├─ 1. SKIP CHECK
+    │     Is sentinel enabled? Is this file in skip_patterns?
+    │
+    ├─ 2. RETRIEVE STANDARDS
+    │     engrm search("auth middleware security")
+    │     → "Decision: all auth must use bcrypt, not MD5"
+    │     → "Bugfix: session tokens were stored unencrypted"
+    │     → "Standard: never log auth credentials"
+    │
+    ├─ 3. AUDIT LLM CALL
+    │     POST base_url/chat/completions
+    │     { model, messages: [system + standards + diff] }
+    │     temperature: 0, max_tokens: 150
+    │
+    ├─ 4a. PASS → exit 0 (Claude proceeds)
+    ├─ 4b. WARN → exit 0 + log observation
+    └─ 4c. BLOCK → exit 2 + stderr reason
+           (Claude receives error, self-corrects, retries)
+    │
+    ▼
+Finding saved as observation → syncs to team → future audits are smarter
+```
+
+### Dashboard → Server → Client Config Push
+
+```
+Dashboard (engrm.dev/sentinel)
+    │ POST /v1/mem/sentinel/config
+    ▼
+Candengo Vector (sync_events, record_type="sentinel_config")
+    │ GET /v1/sync/changes (existing pull loop, every 60s)
+    ▼
+Client (~/.engrm/settings.json → sentinel config merged)
+    │
+    ▼
+PreToolUse hook reads config on each invocation
+```
+
+### Provider Agnostic (OpenAI-Compatible API)
+
+All major LLM providers speak the same `POST /v1/chat/completions` format:
+
+| Provider | Base URL | Models | Cost/1K audits |
+|----------|----------|--------|---------------|
+| OpenAI | api.openai.com/v1 | gpt-4o-mini | ~$0.40 |
+| xAI/Grok | api.x.ai/v1 | grok-3-mini | ~$0.30 |
+| Mistral | api.mistral.ai/v1 | mistral-small | ~$0.20 |
+| Anthropic | via proxy | haiku-4.5 | ~$0.50 |
+| Local vLLM | 192.168.5.5:8000/v1 | devstral-24b | $0 |
+| Ollama | localhost:11434/v1 | llama3-8b | $0 |
+
+One client function, ~40 lines. No provider-specific code.
+
+## Config Schema
+
+```typescript
+interface SentinelConfig {
+  enabled: boolean;
+  mode: "advisory" | "blocking";           // WARN-only vs BLOCK+WARN
+  provider: "openai" | "xai" | "mistral" | "anthropic" | "custom";
+  base_url: string;                        // OpenAI-compatible endpoint
+  model: string;                           // e.g. "gpt-4o-mini"
+  api_key_env?: string;                    // Client-side env var name
+  encrypted_api_key?: string;              // Server-pushed, decrypted client-side
+  match_tools: string[];                   // ["Write", "Edit"] default
+  timeout_ms: number;                      // Max wait (default 8000)
+  skip_patterns: string[];                 // e.g. ["*.test.ts", "*.md"]
+  max_diff_lines: number;                  // Truncate large diffs (default 200)
+}
+```
+
+Stored in `~/.engrm/settings.json` under `sentinel` key. Pushed from dashboard via sync_events.
+
+## Standards
+
+Standards are **observations tagged as audit-relevant**. No separate schema needed.
+
+- Add `"standard"` to the observation type enum
+- Tag with `sentinel-standard` in concepts
+- Standards sync through the existing push/pull pipeline
+- Dashboard provides UI for creating/managing them
+- Every past decision, bugfix, and pattern is a potential standard — just tag it
+
+## Graceful Degradation
+
+Following the sqlite-vec precedent:
+
+| Failure | Behavior |
+|---------|----------|
+| LLM API down/timeout | exit 0 (allow), log warning |
+| No standards found | Skip audit, exit 0 |
+| Config not synced yet | Sentinel disabled by default |
+| API key missing | Skip audit, log once |
+| Free tier user | Sentinel hooks not registered |
+
+## Feedback Loop (The Moat)
+
+```
+Sentinel blocks a write
+  → Claude self-corrects
+  → Corrected code passes
+  → Block + correction saved as observation
+  → Observation syncs to all team members
+  → Future audits retrieve it as context
+  → Sentinel gets smarter over time
+```
+
+Static rules don't learn. Sentinel does. This is the competitive moat.
+
+## Pricing
+
+| Tier | Sentinel | Observations | Price |
+|------|----------|-------------|-------|
+| Free | Not available | 10K, 2 devices | $0 |
+| Pro | Advisory mode, 100 audits/day, own API keys | 50K, unlimited devices | $15/dev/mo |
+| Team | Full blocking + advisory, unlimited, dashboard config push, shared standards, audit heatmap | 100K, unlimited devices | $25/dev/mo |
+
+Users bring their own LLM API keys. Engrm's marginal cost per audit is near-zero (one vector search + config lookup).
+
+## Implementation Plan
+
+### Phase 1: Core Hook + Local Audit (Week 1)
+
+| Task | File | Effort |
+|------|------|--------|
+| Add `SentinelConfig` to config interface | `src/config.ts` | 1h |
+| Add `"standard"` to observation type enum | `src/types.ts` | 30m |
+| Create `src/sentinel/types.ts` | New | 30m |
+| Create `src/sentinel/llm-client.ts` (OpenAI-compatible) | New (~40 lines) | 1h |
+| Create `src/sentinel/prompts.ts` | New | 2h |
+| Create `src/sentinel/audit.ts` (orchestrator) | New | 3h |
+| Create `hooks/sentinel.ts` (PreToolUse hook) | New | 2h |
+| Register sentinel hook in `registerHooks()` | `src/register.ts` | 30m |
+| Tests | `src/sentinel/*.test.ts` | 3h |
+| Integration test (hook → local LLM) | Manual | 2h |
+
+### Phase 2: Dashboard Config Push (Week 2)
+
+| Task | Location | Effort |
+|------|----------|--------|
+| `POST /v1/mem/sentinel/config` endpoint | candengo-vector | 3h |
+| `GET /v1/mem/sentinel/config` endpoint | candengo-vector | 1h |
+| Store config in sync_events (record_type="sentinel_config") | candengo-vector | 2h |
+| Handle sentinel_config in pull loop | `src/sync/pull.ts` | 2h |
+| Dashboard: LLM provider config page | website/mem/sentinel.html | 4h |
+| Dashboard: standards manager (CRUD) | website/mem/sentinel.html | 4h |
+| API key encryption (server→client) | Both | 3h |
+
+### Phase 3: Standards Library + Feedback Loop (Week 3)
+
+| Task | Location | Effort |
+|------|----------|--------|
+| `POST /v1/mem/sentinel/standards` CRUD | candengo-vector | 3h |
+| Standards sync via pull loop | `src/sync/pull.ts` | 2h |
+| Save audit findings as observations | `src/sentinel/audit.ts` | 2h |
+| Dashboard: audit results + heatmap | candengo-vector website | 4h |
+| `engrm sentinel status` CLI | `src/cli.ts` | 1h |
+| `engrm sentinel test` CLI | `src/cli.ts` | 2h |
+
+### Phase 4: Polish + Tier Enforcement (Week 4)
+
+| Task | Effort |
+|------|--------|
+| Rate limiting (100/day pro, unlimited team) | 2h |
+| Tier check on hook registration | 1h |
+| Anti-rationalization gate (Stop hook, from TrailOfBits) | 3h |
+| Skip patterns, file-type filtering | 2h |
+| Docs + onboarding in dashboard | 3h |
+| Performance profiling (target: <3s/audit) | 2h |
+
+### Phase 5: Beta + Launch (Weeks 5-6)
+
+| Task | Effort |
+|------|--------|
+| Internal dogfood (Unimpossible team) | 1 week |
+| Bug fixes from dogfood | Variable |
+| Launch blog post + HN announcement | 1 day |
+| Waitlist conversion emails | 1 day |
+
+## Files to Create
+
+```
+src/sentinel/
+├── types.ts          # SentinelConfig, AuditResult, etc.
+├── llm-client.ts     # OpenAI-compatible API client (~40 lines)
+├── prompts.ts        # System prompt, audit request formatter, response parser
+├── audit.ts          # Orchestrator: search → LLM → decision → save finding
+└── *.test.ts         # Tests
+
+hooks/
+└── sentinel.ts       # PreToolUse hook (follows post-tool-use.ts pattern)
+```
+
+## Files to Modify
+
+```
+src/config.ts         # Add SentinelConfig to Config interface + defaults
+src/register.ts       # Register PreToolUse sentinel hook
+src/sync/pull.ts      # Handle record_type="sentinel_config" | "sentinel_standard"
+src/cli.ts            # Add `engrm sentinel status|test` commands
+```
+
+## Key Design Patterns to Follow
+
+| Pattern | Source | Application |
+|---------|--------|-------------|
+| Silent error handling | hooks/post-tool-use.ts | Never crash; exit 0 on any error |
+| Config merging | src/config.ts | Defaults → disk → sync override |
+| Reentrancy guards | src/sync/engine.ts | Prevent concurrent audits |
+| Graceful degradation | sqlite-vec integration | If unavailable, skip silently |
+| Observation pipeline | src/capture/ | Findings go through same scrub→quality→dedup→save flow |
+
+## References
+
+### Competitors
+- [CodeRabbit](https://www.coderabbit.ai/) — PR-level, $0-24/dev/mo
+- [Qodo](https://www.qodo.ai/) — Best RAG, PR-level, $0-30/dev/mo
+- [Greptile](https://www.greptile.com/) — Learns from PRs, $30/dev/mo
+- [Ellipsis](https://www.ellipsis.dev/) — PR-level, ~$20/dev/mo
+
+### GitHub Repos
+- [disler/claude-code-hooks-mastery](https://github.com/disler/claude-code-hooks-mastery) (3.3k★)
+- [trailofbits/claude-code-config](https://github.com/trailofbits/claude-code-config) (1.6k★)
+- [qodo-ai/pr-agent](https://github.com/qodo-ai/pr-agent) (10.5k★)
+- [praneybehl/code-review-mcp](https://github.com/praneybehl/code-review-mcp)
+
+### Claude Code Docs
+- [Hooks Reference](https://code.claude.com/docs/en/hooks)
+- [Hooks Guide](https://code.claude.com/docs/en/hooks-guide)