14 added, 398 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 a deterministic orchestrator for CLI coding agents (Claude Code, Codex, Gemini CLI, and 40+ more). It runs them in parallel, gates what they produce, and records enough of the run that you can check it afterwards. Air-gap install profile included. Apache-2.0.
## Module map
- ### `src/bernstein/core/` - orchestration engine
-
- | File | Purpose |
- |-----------------------------|---------|
- | `compat_redirect_ledger.py` | Compatibility ledger for legacy ``bernstein.core`` redirects |
- | `credential_scoping.py` | Agent credential scope minimization for least-privilege API keys |
- | `dataclass_helpers.py` | Helpers for preserving dataclass instance types through updates |
- | `defaults.py` | Centralized default values for the Bernstein orchestrator |
- | `diff_paths.py` | Which repository-relative paths a unified diff touches |
- | `instrumentation.py` | Wave-3 per-agent instrumentation: LLM calls, tool calls, and conversation history |
- | `parallel_admission.py` | Parallel-execution admission from a code graph (#3237, scope step 3) |
- | `path_scope.py` | Which repository-relative paths fall outside a set of globs |
- | `run_auth_token.py` | Persist and read the auto-generated run Bearer token (issue #2794) |
- | `streaming_merge.py` | Streaming task results for long-running agents (incremental merge) |
- | `admission/` | Named resource pools with lease-backed admission (#2544) |
- | `agents/` | agents sub-package |
- | `approval/` | Interactive tool-call approval (op-002) |
- | `autofix/` | Bernstein autofix daemon - auto-repair CI failures on Bernstein PRs |
- | `autoheal/` | Auto-heal v2 subpackage |
- | `chat/` | Chat-control bridges for driving Bernstein agents from messaging apps |
- | `communication/` | communication sub-package |
- | `compliance/` | Compliance subpackage |
- | `config/` | Config: seed parsing, config management, settings, feature gates |
- | `cost/` | cost sub-package |
- | `daemon/` | Daemon installation helpers for Bernstein |
- | `datasources/` | Content-addressed query receipts (issue #2887) and the schema-bound query driver (issue #3125) |
- | `devops/` | devops sub-package |
- | `distribution/` | Distribution utilities - air-gap wheelhouse build, verify, signing |
- | `endpoints/` | Local-model worker tier: endpoint conformance and signed certification |
- | `errors/` | Structured first-run error categorization for Bernstein |
- | `events/` | Eventing v2 - the chain-projected unified event feed (#2548) |
- | `evidence/` | Verification evidence bundles (issue #2362) |
- | `fleet/` | Fleet dashboard - supervise multiple Bernstein projects in one view |
- | `git/` | git sub-package |
- | `grpc_gen/` | Generated gRPC stubs - run ``scripts/generate_proto.sh`` to populate |
- | `handoff/` | Session handoff between terminal and chat/dashboard surfaces (op-005) |
- | `identity/` | Install-rev identity module - passive, operator-decodable install fingerprint |
- | `integrations/` | Integrations sub-package |
- | `interop/` | Cross-organisation interoperability surfaces |
- | `knowledge/` | knowledge sub-package |
- | `lifecycle/` | Lifecycle-hooks subsystem |
- | `lineage/` | Lineage v1 - Sigstore-style per-artefact transparency log |
- | `memory/` | memory sub-package - persistent memory stores |
- | `notifications/` | Outbound notification subsystem (release 1.9) |
- | `observability/` | observability sub-package |
- | `orchestration/` | orchestration sub-package |
- | `payments/` | Sub-package: enforce, mandate, receipt |
- | `persistence/` | persistence sub-package |
- | `planning/` | planning sub-package |
- | `plugins_core/` | plugins_core sub-package |
- | `preview/` | ``bernstein preview`` - sandboxed dev-server with public tunnel link |
- | `protocols/` | protocols sub-package |
- | `quality/` | quality sub-package |
- | `replay/` | Deterministic replay package for Bernstein agent runs |
- | `review/` | Per-adapter perspective assignment and chain coordination for reviews |
- | `review_responder/` | PR review responder - react to inline review comments on Bernstein PRs |
- | `routes/` | FastAPI router modules for the Bernstein task server |
- | `routing/` | routing sub-package |
- | `run_service/` | Detached run service: submit a goal, disconnect, reattach later (#2352) |
- | `sandbox/` | Pluggable sandbox backends for agent isolation (oai-002 phase 1) |
- | `security/` | security sub-package |
- | `server/` | server sub-package - re-exports for backward compatibility |
- | `sessions/` | Session-level orchestration primitives that span multiple subsystems |
- | `simulate/` | Digital-twin orchestration simulator (issue #1374) |
- | `skills/` | Progressive-disclosure skill packs (oai-004) |
- | `storage/` | Pluggable artifact storage sinks (oai-003) |
- | `substrate/` | Substrate: register Bernstein into host applications (MCP servers, etc.) |
- | `tasks/` | tasks sub-package |
- | `teams/` | Named team manifests - pinned bundles of roles, model policies, and response profiles |
- | `telemetry/` | Opt-in operator observability for Bernstein |
- | `tokens/` | tokens sub-package |
- | `tools/` | Tool support, execution, and coverage helpers |
- | `tournament/` | Tournament runs: parallel attempts selected by deterministic evaluators (#2353) |
- | `trackers/` | Tracker adapter subsystem |
- | `trigger_sources/` | Trigger source adapters - normalize raw events into TriggerEvent |
- | `tunnels/` | Tunnel provider abstraction and registry |
- | `volunteer/` | Volunteer-workers substrate: opt-in project policy and its trust anchor |
- | `workflows/` | Declarative YAML workflow manifests |
- | `worktrees/` | Worktree inventory and garbage-collection helpers |
-
- ### `src/bernstein/adapters/` - CLI agent adapters
-
- | File | Purpose |
- |-----------------------------|---------|
- | `_contract.py` | Adapter contract loader and capability checker |
- | `acp_channel.py` | Adapter-side binding for the ACP event channel (#2522) |
- | `admission.py` | Receipt-gated adapter admission with signed refusal receipts (#2610) |
- | `advisories.py` | Adapter minimum-safe-version advisories (supply-chain posture) |
- | `agy.py` | Antigravity CLI (``agy``) adapter |
- | `aichat.py` | AIChat CLI adapter |
- | `aider.py` | Aider CLI adapter |
- | `amp.py` | Amp CLI adapter |
- | `auggie.py` | Auggie (Augment Code) CLI adapter |
- | `autohand.py` | Autohand Code CLI adapter |
- | `base.py` | Base adapter for CLI coding agents |
- | `caching_adapter.py` | Caching wrapper for CLI adapters to enable prompt prefix deduplication and response reuse |
- | `canary.py` | Adapter conformance canary matrix (issue #2368) |
- | `capability_profile.py` | Declarative adapter capability profiles and the profile factory |
- | `charm.py` | Charm Crush CLI adapter |
- | `claude.py` | Claude Code CLI adapter |
- | `claude_agents.py` | Build per-task Claude Code subagent definitions for the --agents flag |
- | `claude_cache_control.py` | Anthropic API cache-control block builder for the Claude Code adapter |
- | `claude_exit_codes.py` | Map Claude Code exit codes to Bernstein AbortReason/TransitionReason |
- | `claude_mcp_loader.py` | MCP config loading and merging for the Claude Code adapter |
- | `claude_routine.py` | Claude Code Routine adapter - offloads tasks to Anthropic cloud via /fire API |
- | `claude_stream_parser.py` | Parse Claude Code --output-format stream-json events |
- | `claude_wrapper_script.py` | Inline wrapper script source + assembly for the Claude Code adapter |
- | `cline.py` | Cline CLI adapter |
- | `clm.py` | CLM sovereign LLM adapter - drives a customer-side CLM gateway |
- | `clm_tls_launcher.py` | mTLS launcher for the CLM adapter |
- | `codebuff.py` | Codebuff CLI adapter |
- | `codex.py` | OpenAI Codex CLI adapter |
- | `codex_cloudflare.py` | Codex adapter driving Cloudflare's first-party sandbox bridge (issue #2969) |
- | `cody.py` | Sourcegraph Cody CLI adapter |
- | `composio.py` | Composio Agent Orchestrator (``ao``) CLI adapter |
- | `computer_use.py` | Browser / computer-use adapter family (#2606) |
- | `conformance.py` | Adapter tool contract conformance suite harness |
- | `continue_dev.py` | Continue.dev CLI adapter |
- | `copilot.py` | GitHub Copilot CLI adapter |
- | `council_runner.py` | Task-level "council of agents" runner |
- | `cursor.py` | Cursor Agent CLI adapter |
- | `devin_terminal.py` | Devin for Terminal (Cognition) CLI adapter |
- | `droid.py` | Droid (Factory AI) CLI adapter |
- | `env_isolation.py` | Environment variable isolation for spawned agents |
- | `floor_refresh.py` | Adapter security-floor refresh pipeline with signed update receipts (#2515) |
- | `forge.py` | Forge CLI adapter |
- | `gemini.py` | Google Gemini / Antigravity CLI adapter |
- | `generic.py` | Generic CLI adapter for arbitrary coding agent CLIs |
- | `goose.py` | Goose CLI adapter for Bernstein |
- | `gptme.py` | gptme CLI adapter |
- | `hermes.py` | Hermes Agent (Nous Research) CLI adapter |
- | `hook_gate_render.py` | Render in-process verification-gate hooks for capable adapters (issue #2360) |
- | `iac.py` | Infrastructure-as-Code (Terraform/Pulumi) adapter for Bernstein |
- | `junie.py` | JetBrains Junie CLI adapter |
- | `kilo.py` | Kilo CLI adapter (Stackblitz) |
- | `kimchi.py` | Kimchi CLI adapter (#3100) |
- | `kimi.py` | Kimi CLI adapter |
- | `kiro.py` | Kiro CLI adapter |
- | `letta_code.py` | Letta Code CLI adapter |
- | `manager.py` | Manager adapter - spawns the internal Python ManagerAgent orchestrator |
- | `mistral.py` | Mistral Vibe CLI adapter |
- | `mock.py` | Mock CLI adapter for zero-API-key demos and testing |
- | `muse.py` | Muse Code CLI adapter for Bernstein |
- | `ollama.py` | Ollama / OpenAI-compatible local LLM adapter - run coding agents without cloud API keys |
- | `open_interpreter.py` | Open Interpreter CLI adapter |
- | `openai_agents.py` | OpenAI Agents SDK v2 adapter |
- | `openai_agents_builtins.py` | Opt-in builtin tools for the OpenAI Agents runner |
- | `openai_agents_runner.py` | Python entrypoint that runs an OpenAI Agents SDK session |
- | `opencode.py` | OpenCode CLI adapter |
- | `openhands.py` | OpenHands CLI adapter |
- | `pi.py` | Pi (pi-coding-agent) CLI adapter |
- | `plandex.py` | Plandex CLI adapter |
- | `plugin_sdk.py` | Adapter plugin SDK for third-party agent integration |
- | `python_runtime.py` | Generic Python-invoked agent-runtime adapter (#2959) |
- | `python_runtime_runner.py` | Runner script for the generic Python-invoked agent-runtime adapter (#2959) |
- | `q_dev.py` | AWS Q Developer CLI adapter (binary: ``q``) |
- | `qwen.py` | Qwen CLI adapter for OpenAI compatible models |
- | `ralphex.py` | Ralphex (umputun/ralphex) CLI adapter |
- | `registry.py` | Adapter registry - look up CLI adapters by name |
- | `report.py` | Adapter conformance + capability report |
- | `rovo.py` | Atlassian Rovo Dev CLI adapter |
- | `security_floor.py` | Adapter security-floor spawn preflight with signed refusal receipts (#2515) |
- | `session_id.py` | Deterministic session-id binding for adapter replay isolation |
- | `skills_injector.py` | Inject per-task Claude Code skills into the worktree before spawn |
- | `strict_schema.py` | Strict structured-output validation and user-owned-field protection |
- | `use_cases.py` | Per-adapter metadata for the ``bernstein integrations list`` command |
- | `ci/` | CI system adapters for log parsing and failure extraction |
-
- ### `src/bernstein/agents/` - agent catalog & discovery
-
- | File | Purpose |
- |----------------------|---------|
- | `agency_provider.py` | AgencyProvider - loads CatalogAgent instances from msitarzewski/agency-agents format |
- | `catalog.py` | Agent catalog registry - loads agent definitions from external sources |
- | `discovery.py` | Agent directory auto-discovery for Bernstein |
- | `plugin_catalog.py` | Reads agent catalogs laid out as a Claude Code plugin/subagent tree |
- | `registry.py` | Dynamic agent registry with YAML-based definitions and hot-reload support |
-
- ### `src/bernstein/cli/` - Click CLI
-
- | File | Purpose |
- |-------------------------|---------|
- | `badge.py` | Powered-by badge helper for ``bernstein init --add-badge`` |
- | `commit_stats.py` | Commit attribution stats: gather per-role commit stats via git log |
- | `dashboard.py` | Bernstein TUI -- retro-futuristic agent orchestration dashboard |
- | `dashboard_actions.py` | Dashboard side panels and expert views |
- | `dashboard_app.py` | Bernstein TUI application -- main App class and entry point |
- | `dashboard_header.py` | Dashboard header and agent display widgets |
- | `dashboard_polling.py` | Dashboard polling helpers, data loaders, formatters, and constants |
- | `debug_bundle.py` | Debug bundle export -- ``bernstein debug bundle`` |
- | `first_run_guard.py` | First-run guard helpers wiring categorisation into CLI entry points |
- | `helpers.py` | Shared constants, helpers, and utilities for Bernstein CLI modules |
- | `install_check.py` | Installation mismatch detection -- detect multiple Bernstein installs and config conflicts |
- | `keybindings.py` | Keybinding system for the Bernstein TUI |
- | `live.py` | Live view helpers for ``bernstein live --classic`` |
- | `main.py` | CLI entry point for Bernstein -- deterministic orchestrator for CLI coding agents |
- | `notebook_traces.py` | Notebook-aware traces - detect and track Jupyter notebook cell edits |
- | `release_notes.py` | Release notes display - fetch and format release notes for terminal output |
- | `run.py` | Enhanced run output for ``bernstein run`` |
- | `run_archive.py` | Export full run archive as ZIP |
- | `run_bootstrap.py` | Main Click commands and execution bootstrap for Bernstein runs |
- | `run_cmd.py` | Run commands: init, run, serve, start (legacy), and the main CLI group |
- | `run_confirm.py` | Recipe/cook commands, demo, and confirmation helpers for Bernstein runs |
- | `run_names.py` | Memorable deterministic run names for user-facing surfaces (#1626) |
- | `run_preflight.py` | Preflight cost estimation and runtime warnings for Bernstein runs |
- | `settings_snapshot.py` | Settings snapshot - capture and serialize effective settings for traces |
- | `side_query.py` | Side-question ("btw") protocol for non-blocking agent queries |
- | `status.py` | Formatted status output for ``bernstein status`` |
- | `transcript_search.py` | Search across agent transcript/trace files in .sdd/traces/ |
- | `ui.py` | Shared Rich UI components for Bernstein CLI |
- | `usage_provisioning.py` | Usage budget tracking and overage detection for Bernstein |
- | `commands/` | commands sub-package |
- | `display/` | ui sub-package |
- | `doctor/` | Bernstein doctor sub-package - extended diagnostic checks |
- | `plan/` | plan sub-package |
- | `scaffold/` | Bernstein scaffold subsystem |
- | `utils/` | utils sub-package |
-
- ### `src/bernstein/evolution/` - self-evolution engine
-
- | File | Purpose |
- |----------------------------|---------|
- | `_shared.py` | Shared constants, data classes, and helpers for the evolution loop modules |
- | `admission.py` | Empirical-confidence admission gate for upgrade proposals |
- | `aggregator.py` | Metrics aggregation with EWMA, CUSUM, BOCPD, and Goodhart defenses |
- | `applicator.py` | Change applicator - execute upgrades via file modification |
- | `benchmark.py` | Tiered benchmark runner for evolution validation |
- | `circuit.py` | CircuitBreaker - halt evolution when safety conditions are violated |
- | `creative.py` | Creative evolution pipeline - visionary → analyst → production gate |
- | `data_collector.py` | Metric record types and file-based metrics collection for the evolution system |
- | `detector.py` | Opportunity detection from aggregated metrics |
- | `gate.py` | ApprovalGate and EvalGate - risk-stratified routing for evolution proposals |
- | `governance.py` | Adaptive governance for the evolution system |
- | `invariants.py` | InvariantsGuard - hash-lock safety-critical files |
- | `loop.py` | Autoresearch evolution loop - continuous self-improvement via experiment cycles |
- | `observability_signals.py` | Read ``bernstein doctor observe`` snapshots into evolution signals |
- | `oscillation_guard.py` | Oscillation guard for prompt-evolution proposals |
- | `predicted_delta.py` | Predicted-delta gate for prompt-evolution proposals |
- | `proposal_scorer.py` | Proposal risk scoring and routing classification |
- | `proposals.py` | Upgrade proposal generation |
- | `report.py` | Evolution observability - history table and static report generation |
- | `report_generator.py` | Analysis result types, statistical helpers, and Goodhart's Law defenses |
- | `risk.py` | Strategic Risk Score (SRS) computation for evolution proposals |
- | `sandbox.py` | SandboxValidator - isolated testing of evolution proposals |
- | `types.py` | Shared types for the evolution system |
- | `upgrade_targets.py` | Category-to-target-file mapping shared by the upgrade executor and task spawn |
-
- ### `src/bernstein/eval/` - evaluation harness
-
- | File | Purpose |
- |------------------------------------|---------|
- | `ab_comparison.py` | Three-arm profile A/B comparison artifact (issue #2247) |
- | `ab_runner.py` | A/B runner primitive - deterministic prompt-vs-prompt comparison |
- | `baseline.py` | Baseline tracking for eval-gated evolution |
- | `calibration.py` | Calibration log + Brier score for router and judge decisions |
- | `clean_run.py` | Clean-run attestation: prove task ground-truth was never fetched (#2930) |
- | `gate_receipt.py` | Signed verdict receipts for statistical eval gating (#2520) |
- | `golden.py` | Golden benchmark suite - curated tasks for eval |
- | `harness.py` | Eval harness - multiplicative scoring, LLM judge, failure taxonomy |
- | `incident_synthesizer.py` | Convert dead-letter and post-mortem incidents into regression eval cases |
- | `judge.py` | LLM judge - evaluate code quality of agent-produced changes |
- | `metrics.py` | Custom eval metrics - each metric is a dataclass with a compute method |
- | `pentest_consensus.py` | Consensus aggregation for the multi-adapter pentest fan-out |
- | `pentest_runner.py` | Driver that runs the ``security-pentest`` scenario end-to-end |
- | `pentest_scorer.py` | Precision and recall scorer for security pentest eval scenario |
- | `promotion.py` | Deterministic stage promotion and revocation for eval gating (#2520) |
- | `scenario_generator.py` | Forward-looking synthetic scenario generator |
- | `scenario_runner.py` | Scenario runner - execute YAML-defined eval scenarios against the live codebase |
- | `significance.py` | Exact statistics for eval gate verdicts (#2520) |
- | `taxonomy.py` | Failure taxonomy - classify every eval failure into a closed set |
- | `telemetry.py` | Telemetry contract - strict schema for agent output metadata |
- | `trajectory_receipt.py` | Signed, independently-replayable trajectory receipts for benchmark scores (#2925) |
- | `trajectory_receipt_projection.py` | COSE / in-toto DSSE / RFC 6962 transparency projection for trajectory receipts |
- | `vcr_fixture.py` | VCR fixture pattern - dehydrate/hydrate deterministic test fixtures (T805) |
- | `yaml_runner.py` | YAML eval harness - operator-runnable spec format with judge and golden diff |
- | `bench/` | bernstein-bench: runnable, reproducibility-gated evaluation harness |
- | `cases/` | cases/ sub-package |
- | `golden_data/` | Packaged golden benchmark fixtures (ships in wheel via package-data) |
-
- ### `src/bernstein/plugins/` - plugin system (pluggy)
-
- | File | Purpose |
- |-------------------------|---------|
- | `hookspecs.py` | Hook specifications - defines extension points for Bernstein plugins |
- | `manager.py` | Plugin manager - discovers, loads, and invokes Bernstein plugins |
- | `permission_explain.py` | Progressive disclosure for permission requests -- explain-before-approve mode |
- | `plugin_errors.py` | Plugin error collection and reporting |
- | `plugin_trust.py` | Plugin trust checking and risk scoring for Bernstein plugins |
- | `security_review.py` | Security review: regex-based pattern scanning for agent-produced diffs |
-
- ### `src/bernstein/tui/` - Textual TUI
-
- | File | Purpose |
- |---------------------------|---------|
- | `accessibility.py` | TUI-013: Accessibility mode for the Bernstein TUI |
- | `agent_duration.py` | Agent duration display for TUI agent panel |
- | `agent_log.py` | Log and quality gate widgets for the Bernstein TUI |
- | `agent_states.py` | TUI-005: Visual distinction for agent states |
- | `app.py` | Main Textual application for the Bernstein TUI session manager |
- | `approval_panel.py` | Approval, waterfall, tool observer, and SLO widgets for the Bernstein TUI |
- | `away_summary.py` | Away summary generation for orchestration recap |
- | `clipboard.py` | TUI-007: Copy-to-clipboard for task IDs, agent logs, error messages |
- | `color_mode.py` | Terminal color mode detection - auto-detect truecolor/256-color/ANSI |
- | `command_palette.py` | Command palette with fuzzy search for TUI actions |
- | `context_files_doctor.py` | Context warnings for bernstein doctor -- detect stale configs, bad files, MCP issues |
- | `context_tokens.py` | Context token accounting - analyze where context budget is spent |
- | `contextual_tips.py` | Contextual tips system with cooldown for Bernstein CLI |
- | `cost_sparkline.py` | TUI-006: Cost sparkline for the TUI sidebar |
- | `dependency_graph.py` | ASCII-art dependency graph renderer for tasks |
- | `diff_folding.py` | Diff folding - collapsible diff display for large changes |
- | `diff_render.py` | Word-level diff rendering for Bernstein TUI |
- | `event_stream.py` | SSE thread consumer for the TUI (issue #2297) |
- | `fallback.py` | Rich-based fallback display for unsupported terminals (TUI-003) |
- | `help_screen.py` | Help screen modal for TUI - shortcuts plus discoverability hints |
- | `keybinding_config.py` | TUI-004: Configurable keybinding system with YAML-based key map |
- | `layout_cache.py` | Dirty-flag layout caching - skip layout recalculation when nothing changed |
- | `layout_persistence.py` | Persistent layout customization and presets for the Bernstein TUI |
- | `log_viewer.py` | Syntax highlighting, diff folding, and markdown rendering for agent logs |
- | `mouse_support.py` | TUI-017: Mouse support for panel interaction |
- | `notification_badge.py` | TUI-020: Notification badge for background events |
- | `progress_bar.py` | TUI-010: Task progress bar with completion percentage |
- | `scheduling_panel.py` | Scheduling panel widget for TUI - visualizes scheduling decisions |
- | `session_analytics.py` | Session analytics - analyze task traces for insights |
- | `session_recorder.py` | TUI-019: Session recording and playback |
- | `snapshot_testing.py` | TUI visual regression snapshot testing utilities |
- | `split_pane.py` | TUI-008: Split-pane view (tasks list + live agent log) |
- | `status_bar.py` | Status, scratchpad, and coordinator widgets for the Bernstein TUI |
- | `task_context.py` | Task context panel for the Bernstein TUI |
- | `task_detail_overlay.py` | TUI-018 / UX-006: Task detail overlay with tabbed sections |
- | `task_list.py` | Task display widgets and constants for the Bernstein TUI |
- | `task_search.py` | Task search, filter parsing, and input widget for the TUI |
- | `themes.py` | TUI-011: Dark/light theme support |
- | `timeline.py` | Timeline view of task execution for the Bernstein TUI |
- | `toast.py` | TUI-009: Notification toast for events |
- | `tokens.py` | Per-agent token usage tracker - lightweight thread-safe token accounting |
- | `vim_mode.py` | TUI-014: Vim-mode keybindings for TUI navigation |
- | `widgets.py` | Custom Textual widgets for the Bernstein TUI |
- | `worker_badges.py` | Worker badge identity module - format worker metadata into Rich badge strings |
- | `worktree_status.py` | Compact runtime and worktree health pane for the Bernstein TUI |
-
- ### `src/bernstein/github_app/` - GitHub App integration
-
- | File | Purpose |
- |--------------------------|---------|
- | `app.py` | GitHub App authentication: JWT creation and installation token exchange |
- | `check_runs.py` | GitHub Check Runs API client |
- | `ci_router.py` | CI failure routing: blame attribution and enriched fix-task generation |
- | `cost_reporter.py` | PR cost annotation: post agent run cost summaries as GitHub PR comments |
- | `evidence_projection.py` | Tracker-comment projection of a sealed evidence bundle (issue #2362) |
- | `mapper.py` | Event-to-task conversion: maps GitHub webhook events to Bernstein task payloads |
- | `review_projection.py` | Tracker-comment projection of an attested review receipt (issue #2296) |
- | `slash_commands.py` | Slash command parser for /bernstein comments on GitHub issues and PRs |
- | `webhooks.py` | Webhook parsing and HMAC-SHA256 signature verification |
-
- ### `src/bernstein/mcp/` - MCP server
-
- | File | Purpose |
- |-----------------------|---------|
- | `approval_gate.py` | The gates shared by every MCP surface that exposes an approval or completion verb |
- | `capability.py` | Runtime capability cards for the Bernstein MCP server |
- | `cost_meter.py` | Per-call cost-meter and observability envelope for MCP tool responses |
- | `input_validation.py` | Schema-validated MCP tool-call inputs with deny-by-default |
- | `oauth.py` | OAuth-2 / OIDC discovery metadata for the Bernstein MCP server |
- | `prompts.py` | Built-in MCP prompts for the Bernstein server |
- | `remote_transport.py` | Streamable HTTP transport for Bernstein MCP server |
- | `routine_tools.py` | MCP tools for the rt-003 Routine <-> Scenario bridge |
- | `server.py` | Bernstein MCP server |
- | `signal_paths.py` | Containment barrier for the MCP shutdown-signal path |
- | `streaming.py` | In-flight tool-call tracking with cancellation and partial-result preservation |
- | `resources/` | MCP resource registrars for Bernstein |
- | `tool_schemas/` | tool_schemas/ sub-package |
-
- ### `src/bernstein/benchmark/` - SWE-bench
-
- | File | Purpose |
- |-------------------|---------|
- | `comparative.py` | Comparative Benchmark Suite for Bernstein |
- | `golden.py` | Golden test suite for the Bernstein orchestrator |
- | `programbench.py` | ProgramBench evaluation harness for Bernstein |
- | `reproducible.py` | Reproducible benchmark suite for Bernstein |
- | `swe_bench.py` | SWE-Bench evaluation harness for Bernstein |
-
- ### Key non-package directories
+ Full per-file map: `docs/sdd/module-map.md` (generated).
- | Path | Purpose |
- |----------------------------|---------|
- | `templates/roles/` | Jinja2 role prompts (manager, backend, qa, security, devops, etc.) |
- | `templates/prompts/` | Prompt templates (judge.md, etc.) - bundled into wheel |
- | `.sdd/` | All runtime state (never commit `.sdd/runtime/`) |
- | `.sdd/backlog/open/` | YAML task specs waiting to be picked up |
- | `.sdd/backlog/claimed/` | Tasks currently being worked |
- | `.sdd/backlog/closed/` | Completed/cancelled tasks |
- | `.sdd/runtime/` | PIDs, logs, session state, signal files |
- | `.sdd/metrics/` | JSONL metric records |
- | `.sdd/traces/` | JSONL agent traces |
- | `.sdd/agents/catalog.json` | Registered agent catalog |
- | `tests/unit/` | Fast unit tests (no network) |
- | `tests/integration/` | Integration tests (require running server) |
- | `scripts/run_tests.py` | Per-file isolated test runner |
+ | 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 |
**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.