# bernstein - CLAUDE.md
<!-- AUTO-GENERATED by `bernstein agents-md sync` - DO NOT edit by hand. Source: AGENTS.md. -->

## Overview

Bernstein is named after Leonard Bernstein, the American conductor and composer. The project orchestrates a crew of CLI coding agents the way Bernstein conducted the New York Philharmonic: every player on cue, the score deterministic, the conductor accountable for the result. He is the original orchestrator the project takes its name from.

## 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 |
| `instrumentation.py`        | Wave-3 per-agent instrumentation: LLM calls, tool calls, and conversation history |
| `streaming_merge.py`        | Streaming task results for long-running agents (incremental merge) |
| `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 |
| `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 |
| `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 |
| `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 |
| `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 |
| `workflows/`                | Archon-inspired 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 |
| `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) |
| `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 |
| `cloudflare_agents.py`      | Cloudflare Agents SDK adapter for local wrangler dev or deployed worker trigger |
| `codebuff.py`               | Codebuff CLI adapter |
| `codex.py`                  | OpenAI Codex CLI adapter |
| `codex_cloudflare.py`       | Codex adapter for Cloudflare Sandbox execution |
| `cody.py`                   | Sourcegraph Cody CLI adapter |
| `composio.py`               | Composio Agent Orchestrator (``ao``) CLI adapter |
| `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 |
| `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) |
| `kimi.py`                   | Kimi CLI adapter |
| `kiro.py`                   | Kiro CLI adapter |
| `letta_code.py`             | Letta Code CLI adapter |
| `manager.py`                |  |
| `mistral.py`                | Mistral Vibe CLI adapter |
| `mock.py`                   | Mock CLI adapter for zero-API-key demos and testing |
| `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 |
| `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 |
| `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 |
| `registry.py`        | Dynamic agent registry with YAML-based definitions and hot-reload support |

### `src/bernstein/cli/` - Click CLI

| File                    | Purpose |
|-------------------------|---------|
| `api_warmup.py`         | API preconnect warmup -- send a minimal request to warm provider connections |
| `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 -- declarative agent orchestration |
| `notebook_traces.py`    | Notebook-aware traces - detect and track Jupyter notebook cell edits |
| `release_notes.py`      | Release notes display - fetch and format CHANGELOG.md 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, conduct, downbeat (legacy start), 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 |
| `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 |
| `cycle_helpers.py`         | Evolution cycle helper logic - community, creative, and GitHub sync |
| `cycle_runner.py`          | Evolution cycle execution engine |
| `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 |

### `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 |
| `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 |
| `scenario_generator.py`   | Forward-looking synthetic scenario generator |
| `scenario_runner.py`      | Scenario runner - execute YAML-defined eval scenarios against the live codebase |
| `taxonomy.py`             | Failure taxonomy - classify every eval failure into a closed set |
| `telemetry.py`            | Telemetry contract - strict schema for agent output metadata |
| `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 |
| `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 |
| `activity_tracker.py`     | Activity tracking metrics with duration accounting |
| `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 |
| `output_styles.py`        | Output style customization -- load per-project agent output format preferences |
| `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 |
| `session_rename.py`       | Session rename functionality - rename the current session safely |
| `session_tags.py`         | Session tag system - add searchable tags to the current orchestration session |
| `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 |
|-----------------------|---------|
| `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 |
| `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

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

## Build & test

```
pip install -e .[dev]      # install
pytest                     # tests
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 |

**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.
