two-brain-audit 0.2.1

Dual-layer audit system combining automated scoring (left brain) with manual qualitative grading (right brain) and reconciliation.

Two-Brain Audit

The product isn't the scoring. It's watching the gap.

Automated checks exist everywhere. Manual reviews exist everywhere. What doesn't exist is a system that runs both continuously, compares them over time, and alerts you the moment they disagree.

That disagreement — the divergence — is where the real information lives.

  LEFT BRAIN (Auto)              RIGHT BRAIN (Manual)
  ─────────────────              ────────────────────
  pytest pass rate    ──┐    ┌── Human grade (A)
  ruff lint score     ──┤    ├── LLM review findings
  semgrep scan        ──┤    ├── User feedback (4.2/5)
  endpoint health     ──┘    └── Team notes
                        │    │
                        ▼    ▼
                   ┌───────────┐
                   │ THE GAP   │  <── this is the product
                   └─────┬─────┘
                         │
              ┌──────────┼──────────┐
              ▼          ▼          ▼
           Aligned    DIVERGED    Failing
           (quiet)    (signal)     (alarm)

When both brains agree, everything's fine — move on. When they disagree, something interesting just happened: either reality changed and the reviewer hasn't caught up, or the reviewer sees something the automation can't. Either way, that gap is worth investigating.

What Divergence Actually Catches

What happened	Auto says	Manual says	Gap means
Tests pass but codebase rotted	A	C+ (stale)	Auto is right. Manual grade expired — reviewer hasn't looked since the refactor.
Reviewer bumped grade after "looks good" review	B+	A	Manual is optimistic. Auto sees real issues the reviewer glossed over.
Security vuln in dependency	D	A	Auto caught it. Manual grade was set before the CVE dropped.
"Feels slow" but metrics are fine	A	B-	Manual is right. Users feel something automation can't measure.
Big refactor, nothing broke	A	B (cautious)	Auto is right. Reviewer is still nervous from the refactor but tests confirm it's solid.
Compliance review happened	B+	A (with notes)	Manual is right. External auditor validated things auto can't check.

None of these are caught by running either brain alone. The signal is in the disagreement.

Quick Start

pip install two-brain-audit

two-brain-audit init                      # create DB + baseline sidecar
two-brain-audit register --preset python  # 8 dimensions for Python projects
two-brain-audit run light                 # first scan (~2s)
two-brain-audit status                    # view scores + divergences

Dimension                  Auto   Grade  Manual  Status
-----------------------------------------------------------------
  test_coverage            0.930      A      —   ok
  lint_score               1.000      S      —   ok
  security                 0.850     A-     A+   DIVERGED
  type_coverage            0.720     B-      —   ok

Overall: A- (0.876)    Divergences: 1

That DIVERGED on security is the system working. Auto scored 0.85 (A-), but someone manually graded it A+. Who's wrong? That's the conversation worth having.

How It Works

Divergence detection fires when |auto_score - manual_score| > 0.15 AND auto-confidence is above 50%. Low-confidence dimensions (like UX at 30%) can't trigger divergence — the system doesn't argue with humans until it has enough data to form a real opinion.

Three resolution paths:

1. Update manual grade — you agree with auto, fix the sidecar
2. Acknowledge — you disagree with auto, dismiss the alert (visible but dimmed)
3. Re-audit — run a deeper tier or request an LLM review for a second opinion

Ratchet rules prevent silent regression: set a floor grade, and if the score drops below it, the system flags it. Ratchets are advisory — they warn, not block.

Six defense layers prevent the system from lying to you:

Layer	What it catches
Functional test scoring	Grade inflation (scores from tests, not file existence)
Grade expiry	Stale optimism (old manual grades display as expired)
Cross-validation	Optimistic reviewers (divergence when manual >> auto)
Git diff detection	Silent drift (code changed since last manual review)
External scanners	Blind spots (semgrep, PyPI drift — independent signals)
Ratchet rules	Backsliding (score can't drop below target without explicit edit)

The Python Preset (8 real checks, 0 stubs)

Dimension	What it runs	Confidence
test_coverage	pytest pass rate	95%
lint_score	ruff check error count	90%
type_coverage	mypy error count	85%
dep_freshness	pip list --outdated	85%
doc_coverage	AST docstring ratio + README existence	80%
security	semgrep SAST or ruff S rules (fallback)	60%
complexity	radon or AST McCabe analysis (fallback)	80%
import_hygiene	ruff check --select I,F401	85%

Every check handles missing tools gracefully (returns 0.5 with a note, not a crash). Confidence determines how much weight divergence detection gives each dimension.

Web Dashboard

pip install two-brain-audit[dashboard]
two-brain-audit dashboard                 # http://localhost:8484/audit/
two-brain-audit dashboard --native        # PyWebView native window

Grade ring, score bars, divergence alerts, tier triggers, feedback widget, review tracking. Self-contained HTML, zero CDN dependencies.

Full walkthrough with examples → docs/QUICKSTART.md

Python API

from two_brain_audit import AuditEngine, Dimension, Tier

engine = AuditEngine(db_path="audit.db", baseline_path="audit_baseline.json")

engine.register(Dimension(
    name="test_coverage",
    check=lambda: (passed / total, {"passed": passed, "total": total}),
    confidence=0.95,
    tier=Tier.LIGHT,
))

results = engine.run_tier("daily")
health = engine.health_check()  # {"ok": True, "grade": "A", "divergences": 0, ...}

# The interesting part: what do the brains disagree on?
for d in engine.get_divergences():
    print(f"{d.name}: auto={d.auto_score:.2f} vs manual={d.manual_grade}")

CI Integration

- name: Audit health check
  run: |
    pip install two-brain-audit
    two-brain-audit health

Exit code 0 = aligned. Exit code 1 = divergences or failing dimensions. The JSON output tells you exactly what disagrees and by how much.

More Presets

Preset	Dimensions	Best for
python	8 real checks	Python repos
api	8 dimensions	REST APIs
database	7 dimensions	Databases
infrastructure	8 dimensions	DevOps
ml_pipeline	7 dimensions	ML workflows

Docs

• Quickstart Guide — step-by-step with examples
• Standards Reference — what we measure and why (OWASP, SRE, DORA, Clean Code, etc.)
• Architecture — design decisions and data flow
• examples/biged/ — 12-dimension reference implementation

Desktop GUI

Two-Brain Studio — native desktop app for configuring, running, and reviewing audits without the CLI. Open any folder, pick a preset, run audits, edit manual grades, export reports.

Origin

Extracted from BigEd CC after production use on a 125-skill AI fleet with 12 audit dimensions, 4 tiers, and automated daily/weekly scheduling. The divergence detection pattern caught real issues that neither automated tests nor manual reviews caught alone.

License

MIT