Metadata-Version: 2.4
Name: two-brain-audit
Version: 0.2.1
Summary: Dual-layer audit system combining automated scoring (left brain) with manual qualitative grading (right brain) and reconciliation.
Project-URL: Homepage, https://github.com/maxtheman/two-brain-audit
Project-URL: Repository, https://github.com/maxtheman/two-brain-audit
Project-URL: Issues, https://github.com/maxtheman/two-brain-audit/issues
Author: Max
License-Expression: MIT
License-File: LICENSE
Keywords: audit,grading,quality,reconciliation,scoring
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: flask>=3.0; extra == 'all'
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: pywebview>=5.0; extra == 'all'
Requires-Dist: semgrep>=1.60; extra == 'all'
Provides-Extra: dashboard
Requires-Dist: flask>=3.0; extra == 'dashboard'
Provides-Extra: dev
Requires-Dist: flask>=3.0; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: pywebview>=5.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: semgrep>=1.60; extra == 'dev'
Provides-Extra: github
Requires-Dist: httpx>=0.27; extra == 'github'
Provides-Extra: llm
Requires-Dist: httpx>=0.27; extra == 'llm'
Provides-Extra: native
Requires-Dist: flask>=3.0; extra == 'native'
Requires-Dist: pywebview>=5.0; extra == 'native'
Provides-Extra: semgrep
Requires-Dist: semgrep>=1.60; extra == 'semgrep'
Description-Content-Type: text/markdown

# 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

```bash
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

```bash
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 &#8594; docs/QUICKSTART.md](docs/QUICKSTART.md)**

## Python API

```python
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

```yaml
- 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](docs/QUICKSTART.md)** — step-by-step with examples
- **[Standards Reference](docs/STANDARDS.md)** — what we measure and why (OWASP, SRE, DORA, Clean Code, etc.)
- **[Architecture](docs/ARCHITECTURE.md)** — design decisions and data flow
- **[examples/biged/](examples/biged/)** — 12-dimension reference implementation

## Desktop GUI

[Two-Brain Studio](https://github.com/SwiftWing21/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](https://github.com/maxtheman/Education) 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
