1 added, 1 removed. Audit A to A.
# bernstein - CLAUDE.md
<!-- AUTO-GENERATED by `bernstein agents-md sync` - DO NOT edit by hand. Source: AGENTS.md. -->
## Overview
- Bernstein is the open-source governance layer for AI agents. A deterministic scheduler - no model in the coordination loop - runs agents in parallel, gates what they produce, and records every step, so a run can be verified after the fact, offline, from the artifacts alone. CLI coding agents work out of the box (Claude Code, Codex, Gemini CLI, and 40+ more), and the same layer governs any agent workload: the deliverable can be a diff, a research report, a dataset, or an audit evidence pack. Air-gap install profile included. Apache-2.0.
+ Bernstein is the open-source governance layer for AI agents. It runs on policy as code: you write the policy - who may do what, what needs approval, what must be recorded - and Bernstein enforces it and produces the verifiable record. A deterministic scheduler - no model in the coordination loop - runs agents in parallel, gates what they produce, and records every step, so a run can be verified after the fact, offline, from the artifacts alone. CLI coding agents work out of the box (Claude Code, Codex, Gemini CLI, and 40+ more), and the same layer governs any agent workload: the deliverable can be a diff, a research report, a dataset, or an audit evidence pack. Air-gap install profile included. Apache-2.0.
## Module map
Full per-file map: `docs/sdd/module-map.md` (generated).
| Package | Purpose / detail |
|---------------|------------------|
| `core/` | orchestration engine - `src/bernstein/core/` |
| `adapters/` | CLI agent adapters - `src/bernstein/adapters/AGENTS.md` |
| `agents/` | agent catalog & discovery - `src/bernstein/agents/` |
| `cli/` | Click CLI - `src/bernstein/cli/AGENTS.md` |
| `evolution/` | self-evolution engine - `src/bernstein/evolution/` |
| `eval/` | evaluation harness - `src/bernstein/eval/` |
| `plugins/` | plugin system (pluggy) - `src/bernstein/plugins/` |
| `tui/` | Textual TUI - `src/bernstein/tui/` |
| `github_app/` | GitHub App integration - `src/bernstein/github_app/` |
| `mcp/` | MCP server - `src/bernstein/mcp/` |
| `benchmark/` | SWE-bench - `src/bernstein/benchmark/` |
## Directory context files
Per-directory context files for agents working inside a subtree. Each covers: what the directory is for, key files, invariants, and how to test that subtree.
| Path | Covers |
|----------------------------------------------|--------|
| `src/bernstein/adapters/AGENTS.md` | CLI agent adapters |
| `src/bernstein/cli/AGENTS.md` | Click CLI |
| `src/bernstein/core/lineage/AGENTS.md` | Lineage: artifact provenance |
| `src/bernstein/core/orchestration/AGENTS.md` | Orchestration engine |
| `src/bernstein/core/quality/AGENTS.md` | Quality gates and verification |
| `src/bernstein/core/security/AGENTS.md` | Security: audit chain, identity, policy |
| `tests/AGENTS.md` | Test suite |
## Build & test
```
uv sync # install + lock
uv run python scripts/run_tests.py # tests (isolated per-file runner)
uv run ruff check . # lint
uv run ruff format . # format
uv run mypy src # type-check
```
## Setup
1. `uv sync` to install + lock the project.
2. `uv run python -m bernstein --help` (or your equivalent entry point).
3. See [Build & test](#build--test) for the recurring commands.
## Architecture (entry points)
Top-level entry points exposed by the package:
| Command | Purpose |
|------------------------|---------|
| `bernstein` | bernstein.cli.main:cli |
| `bernstein-worker` | bernstein.core.worker:main |
| `bernstein-bench` | bernstein.eval.bench.bench_cli:bench_group |
| `verify-audit-receipt` | bernstein.core.verifier.audit_receipt_verifier:main |
**Back-compat aliases.** Legacy import paths (e.g. `bernstein.core.orchestrator`) are served by a `sys.meta_path` finder, not by physical shim files. The mechanism lives in `src/bernstein/core/__init__.py` as `_CoreRedirectFinder` driven by the `_REDIRECT_MAP` dict - add new aliases there rather than creating shim modules at the old path.
## Git workflow
Default branch: `main`.
## Agent roles
Bernstein ships agent role prompts under `templates/roles/`. The orchestrator loads them at task-spawn time; you don't write to them manually.
- `adversary`
- `analyst`
- `architect`
- `backend`
- `ci-fixer`
- `devops`
- `docs`
- `frontend`
- `manager`
- `ml-engineer`
- `prompt-engineer`
- `qa`
- `resolver`
- `retrieval`
- `reviewer`
- `security`
- `visionary`
- `vp`
## Documentation duty
Every PR that adds or changes a feature MUST update docs in the same PR:
- User-visible behaviour: update the relevant `README.md` section.
- Operator workflows: update `docs/operations/<area>.md`.
- Public API surface: regenerate `docs/api/` schemas.
- Architecture or new module: update `docs/sdd/` and run `bernstein agents-md sync` so AGENTS.md, CLAUDE.md, `.goosehints`, `CONVENTIONS.md`, and `.cursor/rules/*.mdc` stay aligned.
- New test layer: also update `docs/contributing/testing.md`.
PRs without the matching docs change will be sent back. Docs and code ship together.