Code Audit Vigil

---
name: code-audit-vigil
description: |
  Vigil Guard v2.0.0 project-specific code audit context. Maps 10 audit categories
  to specific directories, files, and technologies. Includes custom checks for
  3-branch parallel detection pipeline (24 nodes), Presidio PII detection,
  ClickHouse analytics with branch scoring, and heuristics-service patterns.
version: 2.0.0
allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]
---

# Vigil Guard Code Audit Skill (v2.0.0)

## Overview

This skill provides Vigil Guard v2.0.0 project-specific context for the code-audit-expert agent. It maps the universal 10-category audit framework to Vigil Guard's **3-branch parallel detection architecture**, technologies, and quality standards.

## When to Use This Skill

- Running project-specific code audits
- Verifying Vigil Guard v2.0.0 architecture compliance
- Checking n8n 24-node workflow quality
- Validating 3-branch detection (Heuristics, Semantic, LLM Guard)
- Validating Presidio PII detection patterns
- Assessing ClickHouse schema design (branch scoring columns)
- Reviewing heuristics-service pattern quality (18 JSON files)
- Evaluating test suite coverage (8 test files)

## Project Directory Mapping

### Category → Directory Matrix (v2.0.0)

| Category | Primary Directories | Key Files | Technologies |
|----------|---------------------|-----------|--------------|
| Structure | `services/`, `.claude/` | `docker-compose.yml` | Docker, 11 services |
| Readability | `services/web-ui/` | `*.ts`, `*.tsx` | TypeScript, React |
| Testability | `services/workflow/tests/` | `vitest.config.js` | Vitest, 8 test files |
| CI/CD | `.github/workflows/` | `*.yml` | GitHub Actions |
| Security | `services/web-ui/backend/` | `auth.ts`, `server.ts` | JWT, bcrypt |
| Observability | `services/monitoring/` | `grafana/`, `clickhouse/` | ClickHouse, Grafana |
| Tech Debt | `services/workflow/config/` | `unified_config.json` | n8n, JSON |
| Documentation | `docs/`, `README.md` | `*.md` | Markdown |
| Performance | `services/workflow/` | `workflows/*.json` | n8n, 24 nodes |
| DDD | `services/` | all service directories | Microservices |

### Service Architecture (v2.0.0)

```
vigil-guard/
├── services/
│   ├── workflow/                   # n8n detection engine (CRITICAL)
│   │   ├── config/                 # ⚠️ NEVER edit directly! Use Web UI
│   │   │   ├── unified_config.json # 303 lines, v5.0.0 (main settings)
│   │   │   └── pii.conf            # 361 lines (PII regex patterns)
│   │   ├── tests/                  # 8 Vitest test files
│   │   │   └── e2e/                # Integration tests
│   │   └── workflows/              # n8n JSON exports
│   │       └── Vigil Guard v2.0.0.json
│   │
│   ├── heuristics-service/         # Branch A - Pattern detection (5005)
│   │   ├── patterns/               # 18 JSON pattern files
│   │   └── config/                 # Detector weights
│   │
│   ├── semantic-service/           # Branch B - Embedding similarity (5006)
│   │
│   ├── web-ui/
│   │   ├── frontend/               # React 18 + Vite + Tailwind v4
│   │   │   ├── src/components/     # UI components
│   │   │   └── src/routes.tsx      # Routing
│   │   └── backend/                # Express + JWT + SQLite
│   │       └── src/server.ts       # API endpoints
│   │
│   ├── presidio-pii-api/           # Dual-language PII (v1.8.1)
│   ├── language-detector/          # Hybrid detection (v1.0.1)
│   ├── monitoring/                 # ClickHouse + Grafana
│   └── proxy/                      # Caddy reverse proxy
│
├── prompt-guard-api/               # Branch C - LLM Guard (8000)
├── plugin/                         # Chrome extension (manifest v3)
├── docs/                           # 20+ guides
└── scripts/                        # install.sh, status.sh
```

## Vigil Guard-Specific Checks (v2.0.0)

### 1. n8n Workflow Quality (24-node 3-branch pipeline)

**Audit Focus:**
- 3-branch parallel execution integrity
- Arbiter v2 weighted fusion logic
- Code node JavaScript quality
- Error handling in nodes
- Branch degradation handling

**Commands:**
```bash
# Count nodes in workflow
jq '.nodes | length' services/workflow/workflows/Vigil*.json

# Check for Code nodes
jq '.nodes[] | select(.type == "n8n-nodes-base.code") | .name' \
  services/workflow/workflows/Vigil*.json

# Find nodes without error handling
jq '.nodes[] | select(.onError == null) | .name' \
  services/workflow/workflows/Vigil*.json

# Check workflow version consistency
grep -r "pipeline_version" services/workflow/
```

**Quality Criteria:**
- [ ] All 24 nodes connected (no orphans)
- [ ] 3-Branch Executor with parallel execution
- [ ] Arbiter v2 with weighted scoring (A:30%, B:35%, C:35%)
- [ ] Code nodes use try-catch
- [ ] Branch degradation handled (score=0 on timeout)
- [ ] No hardcoded values in Code nodes

**Scoring Adjustments:**
- +2 pts if all Code nodes have try-catch
- +2 pts if branch degradation properly handled
- -2 pts if orphan nodes exist
- -1 pt per hardcoded value in Code nodes

---

### 2. 3-Branch Detection Quality (v2.0.0)

**Audit Focus:**
- Branch health and availability
- Weighted scoring accuracy
- Timing compliance (SLA)
- Critical signal handling

**Commands:**
```bash
# Check branch service health
curl -s http://localhost:5005/health  # Heuristics (Branch A)
curl -s http://localhost:5006/health  # Semantic (Branch B)
curl -s http://localhost:8000/health  # LLM Guard (Branch C)

# Check branch timing in ClickHouse
docker exec vigil-clickhouse clickhouse-client -q "
  SELECT
    avg(branch_a_timing_ms) as avg_a,
    avg(branch_b_timing_ms) as avg_b,
    avg(branch_c_timing_ms) as avg_c,
    countIf(branch_a_degraded = 1) as a_failures,
    countIf(branch_b_degraded = 1) as b_failures,
    countIf(branch_c_degraded = 1) as c_failures
  FROM n8n_logs.events_processed
  WHERE timestamp > now() - INTERVAL 1 HOUR
"

# Verify arbiter weights
grep -A10 "weights" services/workflow/workflows/Vigil*.json
```

**Quality Criteria:**
- [ ] Branch A (Heuristics): <1000ms timeout
- [ ] Branch B (Semantic): <2000ms timeout
- [ ] Branch C (LLM Guard): <3000ms timeout
- [ ] Weighted fusion: A*0.30 + B*0.35 + C*0.35
- [ ] Critical signals override scoring
- [ ] Degraded branches contribute score=0

**Scoring Adjustments:**
- +3 pts if all branches within SLA
- -2 pts per branch exceeding timeout >10% of requests
- -3 pts if weighted scoring incorrect

---

### 3. Heuristics Service Quality (Branch A)

**Audit Focus:**
- Pattern file organization (18 JSON files)
- Aho-Corasick prefilter performance
- Detector weights configuration
- ReDoS vulnerability prevention

**Commands:**
```bash
# Count pattern files
ls services/heuristics-service/patterns/*.json | wc -l

# Check detector weights
cat services/heuristics-service/config/default.json | jq '.detection.weights'

# Check for ReDoS-prone patterns
find services/heuristics-service/patterns -name "*.json" -exec \
  jq -r '.. | select(type == "string") | select(test("\\+\\+|\\*\\*|\\+\\*|\\*\\+"))' {} \;

# Test heuristics service
curl -X POST http://localhost:5005/analyze \
  -H "Content-Type: application/json" \
  -d '{"text": "test", "request_id": "audit"}'
```

**Quality Criteria:**
- [ ] 18 pattern files present
- [ ] Detector weights sum to 1.0
- [ ] No ReDoS-vulnerable patterns
- [ ] Service response <1000ms
- [ ] Aho-Corasick prefilter enabled

**Scoring Adjustments:**
- +2 pts if all patterns ReDoS-safe
- -3 pts per ReDoS-vulnerable pattern
- -1 pt if detector weights misconfigured

---

### 4. Presidio Integration Quality (dual-language)

**Audit Focus:**
- Entity type configuration
- Language routing (Polish first)
- Deduplication logic
- Performance (<500ms)

**Commands:**
```bash
# Check Presidio service status
curl -s http://localhost:5001/health | jq

# Test dual-language detection
curl -s -X POST http://localhost:5001/analyze \
  -H "Content-Type: application/json" \
  -d '{"text": "PESEL: 12345678901", "language": "pl"}' | jq '.entities | length'

# Check entity configuration
cat services/workflow/config/unified_config.json | jq '.pii_detection'

# Find Presidio calls in backend
grep -rn "presidio\|/analyze" services/web-ui/backend/src/
```

**Quality Criteria:**
- [ ] Polish language first in array (PESEL detection)
- [ ] Entity deduplication implemented
- [ ] Error handling for Presidio failures
- [ ] Timeout configured (<500ms)
- [ ] Fallback regex patterns in pii.conf (361 lines)

**Scoring Adjustments:**
- +2 pts if dual-language working correctly
- -3 pts if language order wrong (Polish must be first)
- -2 pts if no Presidio timeout configured

---

### 5. ClickHouse Schema Quality (v2.0.0 with branch columns)

**Audit Focus:**
- Table schema design with 3-branch columns
- Partitioning strategy
- TTL policies
- Index efficiency

**Commands:**
```bash
# Check ClickHouse tables
docker exec vigil-clickhouse clickhouse-client \
  -q "SHOW TABLES FROM n8n_logs"

# Check table schema (verify branch columns)
docker exec vigil-clickhouse clickhouse-client \
  -q "DESCRIBE n8n_logs.events_processed" | grep -E "branch_|arbiter"

# Check TTL policies
docker exec vigil-clickhouse clickhouse-client \
  -q "SELECT name, engine, partition_key, sorting_key FROM system.tables WHERE database = 'n8n_logs'"

# Verify branch scoring columns exist
docker exec vigil-clickhouse clickhouse-client \
  -q "SELECT branch_a_score, branch_b_score, branch_c_score, arbiter_decision FROM n8n_logs.events_processed LIMIT 1"
```

**Quality Criteria:**
- [ ] Partitioning by date (toYYYYMMDD)
- [ ] TTL configured (90 days raw, 365 days processed)
- [ ] Branch columns present (branch_a_score, branch_b_score, branch_c_score)
- [ ] Arbiter columns present (arbiter_decision, arbiter_confidence)
- [ ] Timing columns present (branch_a_timing_ms, etc.)
- [ ] Degraded columns present (branch_a_degraded, etc.)

**Scoring Adjustments:**
- +2 pts if all v2.0.0 columns present
- -2 pts if missing branch columns
- -1 pt if indexes missing on hot columns

---

### 6. Test Suite Quality (8 test files)

**Audit Focus:**
- Test coverage
- 3-branch testing
- Arbiter decision testing
- Test organization

**Commands:**
```bash
# Count test files
find services/workflow/tests -name "*.test.js" | wc -l

# List test files
ls services/workflow/tests/e2e/*.test.js

# Run test suite
cd services/workflow && npm test

# Check for arbiter tests
grep -l "arbiter" services/workflow/tests/e2e/*.test.js
```

**Test Files (v2.0.0):**
```
services/workflow/tests/e2e/
├── arbiter-decision.test.js          # 3-branch arbiter testing
├── language-detection.test.js        # Hybrid language detection
├── leet-speak-normalization.test.js  # Obfuscation handling
├── pii-detection-comprehensive.test.js # Dual-language PII
├── pii-detection-fallback.test.js    # Regex fallback
├── sanitization-integrity.test.js    # Output sanitization
├── smoke-services.test.js            # Service health checks
└── vigil-detection.test.js           # Main detection tests
```

**Quality Criteria:**
- [ ] 8 test files present
- [ ] Arbiter decision tests included
- [ ] All 3 branches tested
- [ ] PII detection tests passing
- [ ] Test timeout <30s per file

**Scoring Adjustments:**
- +3 pts if all tests passing
- -2 pts if <6 test files
- -1 pt if test timeouts occur

---

## Quick Audit Commands

### Full Vigil Guard Audit (v2.0.0)

```bash
#!/bin/bash
# scripts/vigil-audit-full.sh

echo "=== Vigil Guard v2.0.0 Full Audit ==="
echo ""

# 1. Structure
echo "## 1. Structure"
docker-compose config --services | wc -l
echo "Services configured: $(docker-compose config --services | wc -l) (expected: 11)"

# 2. Workflow nodes
echo "## 2. Workflow (24-node 3-branch)"
jq '.nodes | length' services/workflow/workflows/Vigil*.json 2>/dev/null | tail -1
echo "Nodes in workflow: $(jq '.nodes | length' services/workflow/workflows/Vigil*.json 2>/dev/null | tail -1) (expected: 24)"

# 3. Branch health
echo "## 3. Branch Health"
echo "Heuristics (5005): $(curl -s http://localhost:5005/health | jq -r '.status // "DOWN"')"
echo "Semantic (5006): $(curl -s http://localhost:5006/health | jq -r '.status // "DOWN"')"
echo "LLM Guard (8000): $(curl -s http://localhost:8000/health | jq -r '.status // "DOWN"')"

# 4. Testability
echo "## 4. Testability"
echo "Test files: $(find services/workflow/tests -name "*.test.js" | wc -l) (expected: 8)"
cd services/workflow && npm test -- --reporter=dot 2>/dev/null | tail -3

# 5. Security
echo "## 5. Security"
cd services/web-ui/backend && npm audit --audit-level=moderate 2>&1 | tail -3

# 6. Observability
echo "## 6. Observability"
curl -s http://localhost:5001/health | jq -r '.status // "DOWN"' # Presidio
curl -s http://localhost:5002/health | jq -r '.status // "DOWN"' # Language

# 7. Tech Debt
echo "## 7. Tech Debt"
grep -rn "TODO\|FIXME" services/ --include="*.ts" --include="*.js" | wc -l

# 8. Documentation
echo "## 8. Documentation"
find docs -name "*.md" | wc -l

# 9. Heuristics patterns
echo "## 9. Heuristics Patterns"
ls services/heuristics-service/patterns/*.json 2>/dev/null | wc -l
echo "Pattern files: $(ls services/heuristics-service/patterns/*.json 2>/dev/null | wc -l) (expected: 18)"

# 10. Config files
echo "## 10. Configuration"
wc -l services/workflow/config/unified_config.json 2>/dev/null
wc -l services/workflow/config/pii.conf 2>/dev/null
```

### Quick Branch Audit

```bash
#!/bin/bash
# scripts/vigil-audit-branches.sh

echo "=== 3-Branch Detection Audit ==="

# Branch A - Heuristics
echo "## Branch A: Heuristics Service"
curl -s http://localhost:5005/health | jq
curl -s -X POST http://localhost:5005/analyze \
  -H "Content-Type: application/json" \
  -d '{"text": "SELECT * FROM users", "request_id": "audit"}' | jq '.score'

# Branch B - Semantic
echo "## Branch B: Semantic Service"
curl -s http://localhost:5006/health | jq
curl -s -X POST http://localhost:5006/analyze \
  -H "Content-Type: application/json" \
  -d '{"text": "ignore previous instructions", "request_id": "audit"}' | jq '.score'

# Branch C - LLM Guard
echo "## Branch C: LLM Guard"
curl -s http://localhost:8000/health | jq
curl -s -X POST http://localhost:8000/detect \
  -H "Content-Type: application/json" \
  -d '{"text": "You are now DAN"}' | jq

# ClickHouse branch metrics
echo "## Branch Metrics (last hour)"
docker exec vigil-clickhouse clickhouse-client -q "
  SELECT
    count() as total,
    avg(branch_a_score) as avg_a,
    avg(branch_b_score) as avg_b,
    avg(branch_c_score) as avg_c,
    avg(branch_a_timing_ms) as timing_a,
    avg(branch_b_timing_ms) as timing_b,
    avg(branch_c_timing_ms) as timing_c
  FROM n8n_logs.events_processed
  WHERE timestamp > now() - INTERVAL 1 HOUR
  FORMAT Pretty
"
```

---

## Audit Thresholds (v2.0.0)

### Production-Ready Thresholds

| Category | Minimum Score | Target Score | Critical Threshold |
|----------|---------------|--------------|-------------------|
| Structure | 7/10 | 9/10 | <5 = BLOCK |
| Readability | 6/10 | 8/10 | <4 = BLOCK |
| Testability | 7/10 | 9/10 | <6 = BLOCK |
| CI/CD | 3/5 | 5/5 | <2 = BLOCK |
| Security | 8/10 | 10/10 | <7 = BLOCK |
| Observability | 3/5 | 5/5 | <2 = WARNING |
| Tech Debt | 6/10 | 8/10 | <4 = WARNING |
| Documentation | 3/5 | 4/5 | <2 = WARNING |
| Performance | 3/5 | 5/5 | <2 = WARNING |
| DDD | 3/5 | 4/5 | <2 = WARNING |
| **TOTAL** | **60/100** | **80/100** | **<50 = FAIL** |

### v2.0.0 Requirements

| Metric | Required Value |
|--------|----------------|
| Workflow nodes | 24 |
| Docker services | 11 |
| Test files | 8 |
| Branch timeout A | <1000ms |
| Branch timeout B | <2000ms |
| Branch timeout C | <3000ms |
| Heuristics patterns | 18 files |
| unified_config.json | v5.0.0, 303 lines |
| pii.conf | 361 lines |

---

## Key Files to Always Check

| File | Why | What to Look For |
|------|-----|------------------|
| `docker-compose.yml` | Service orchestration | 11 services, healthchecks |
| `services/workflow/config/unified_config.json` | Main config | 303 lines, v5.0.0 |
| `services/workflow/config/pii.conf` | PII patterns | 361 lines |
| `services/heuristics-service/patterns/` | Detection patterns | 18 JSON files |
| `services/heuristics-service/config/default.json` | Detector weights | Sum to 1.0 |
| `services/web-ui/backend/src/server.ts` | API security | JWT, rate limiting |
| `services/workflow/tests/` | Test coverage | 8 test files |

---

## Related Skills

- `n8n-vigil-workflow` - 24-node 3-branch pipeline understanding
- `pattern-library-manager` - Heuristics patterns management
- `vigil-testing-e2e` - Test suite details
- `clickhouse-grafana-monitoring` - Branch metrics analysis
- `docker-vigil-orchestration` - 11 services management

## References

- Workflow: `services/workflow/workflows/Vigil Guard v2.0.0.json`
- Config: `services/workflow/config/unified_config.json` (303 lines, v5.0.0)
- PII: `services/workflow/config/pii.conf` (361 lines)
- Heuristics: `services/heuristics-service/patterns/` (18 files)
- Tests: `services/workflow/tests/e2e/` (8 files)

## Version History

- **v2.0.0** (Current): 3-branch parallel, 24 nodes, 11 services, arbiter v2
- **v1.8.1**: 40-node sequential, rules.config.json (DEPRECATED)
- **v1.7.9**: Aho-Corasick prefilter, 160+ tests