VERA 2.0 Architecture

.github/CODEOWNERS

@@ -0,0 +1,17 @@
+# Architecture and domain packages require maintainer review.
+/docs/architecture.md @SpringCare/vera-mh-maintainers
+/docs/vera-cli-use-cases.md @SpringCare/vera-mh-maintainers
+/llm_clients/ @SpringCare/vera-mh-maintainers
+/judge/ @SpringCare/vera-mh-maintainers
+/generate/ @SpringCare/vera-mh-maintainers
+/run_pipeline.py @SpringCare/vera-mh-maintainers
+/openspec/ @SpringCare/vera-mh-maintainers
+/pyproject.toml @SpringCare/vera-mh-maintainers
+
+# Stable interfaces -- changing these requires a design doc (see docs/architecture.md#stable-interfaces-agent-coding-optimization)
+/llm_clients/llm_interface.py    @SpringCare/vera-mh-maintainers
+/utils/role.py                   @SpringCare/vera-mh-maintainers
+/utils/naming.py                 @SpringCare/vera-mh-maintainers
+# /workers/queue.py, /utils/config_schema.py, and /storage/storage_backend.py will be
+# added here once each file exists (Phase 5, Phase 3, and Phase S respectively --
+# see docs/architecture.md#migration-from-current-layout)

AGENTS.md

@@ -29,19 +29,24 @@ cp .env.example .env       # Add API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, et
 
 | Area | Key paths | When to edit |
 |------|-----------|--------------|
-| **Generation** | `generate.py`, `generate_conversations/` | Conversation simulation, turns, personas |
-| **Judging** | `judge.py`, `judge/` | Rubric scoring, TSV output, question navigation |
+| **CLI** | `vera.py` | Subcommands: generate, judge, score, pool, pipeline |
+| **Generation** | `generate_conversations/` | Conversation simulation, turns, personas |
+| **Judging** | `judge/` | Rubric scoring, TSV output, question navigation |
 | **LLM providers** | `llm_clients/`, `llm_clients/llm_factory.py` | New models, custom HTTP/API providers |
-| **Pipeline** | `run_pipeline.py`, `scripts/` | End-to-end generate → judge → score workflows |
+| **Pipeline helpers** | `scripts/` | Pooling and automation until absorbed into `vera pool` |
 | **Data** | `data/` (personas, rubrics) | Evaluation inputs (committed) |
 | **Output** | `output/` (gitignored) | Generated transcripts, evaluations, logs |
 | **Config** | `utils/model_config_loader.py`, `llm_clients/config.py` | Model name resolution, API keys |
 | **Shared utils** | `utils/` | Naming, logging, conversation layout |
 
-**Entry points:** `generate.py` (simulate), `judge.py` (evaluate), `run_pipeline.py` (full workflow), `judge/score.py` (scoring/visualization).
+**Entry point (target):** `vera.py` subcommands only. Legacy scripts (`generate.py`, `judge.py`, `run_pipeline.py`) are deleted entirely at the end of Phase 1 of the migration (not the full 6-phase migration) — see [docs/architecture.md](docs/architecture.md#migration-from-current-layout).
 
 **Temporary experiments:** `tmp_tests/` (not committed). **Permanent tests:** `tests/`.
 
+## Architecture compliance
+
+Read [docs/architecture.md](docs/architecture.md) before structural changes. See its [ESCALATE section](docs/architecture.md#escalate-stop-and-ask) for when to stop and ask, and [Enforcement](docs/architecture.md#enforcement) for the pre-push verification commands.
+
 ## Testing
 
 The project uses [pytest](https://docs.pytest.org/) with unit and integration tests under `tests/`. Coverage is enforced (`--cov-fail-under=30` in `pyproject.toml`).
@@ -76,28 +81,39 @@ uv run pytest tests/integration/
 
 ## Key Commands
 
+Target CLI (`vera.py` — not implemented yet; use legacy commands below until Phase 1 of the migration completes):
+
 ```bash
-# End-to-end pipeline (preferred for full workflows)
-uv run python run_pipeline.py \
+# End-to-end pipeline (target)
+uv run python vera.py pipeline \
   --user-agent claude-sonnet-4-5-20250929 \
   --provider-agent gpt-4o \
   --runs 1 \
   --turns 10 \
   --judge-model claude-sonnet-4-5-20250929 \
   --max-personas 5
 
-# Generate conversations only
-uv run python generate.py \
-  -u claude-sonnet-4-5-20250929 \
-  -p gpt-4o \
-  -t 6 -r 1
+# Generate / judge / score (target)
+uv run python vera.py generate -u claude-sonnet-4-5-20250929 -p gpt-4o -t 6 -r 1
+uv run python vera.py judge -f output/{YOUR_P_RUN}/ -j claude-sonnet-4-5-20250929
+uv run python vera.py score -r output/{YOUR_P_RUN}/evaluations/{YOUR_J_RUN}/results.csv
+```
+
+Legacy (current implementation):
+
+```bash
+uv run python run_pipeline.py \
+  --user-agent claude-sonnet-4-5-20250929 \
+  --provider-agent gpt-4o \
+  --runs 1 \
+  --turns 10 \
+  --judge-model claude-sonnet-4-5-20250929 \
+  --max-personas 5
 
-# Judge/evaluate an existing generation run
-uv run python judge.py \
-  -f output/{YOUR_P_RUN}/ \
-  -j claude-sonnet-4-5-20250929
+uv run python generate.py -u claude-sonnet-4-5-20250929 -p gpt-4o -t 6 -r 1
+uv run python judge.py -f output/{YOUR_P_RUN}/ -j claude-sonnet-4-5-20250929
 
-# Recommended published-score profile (scripted)
+# Recommended published-score profile (scripted; legacy)
 ./scripts/run_recommended_vera_pipeline.sh <provider-agent-model>
 
 # Development
@@ -119,7 +135,7 @@ Use dated model IDs (e.g. `claude-sonnet-4-5-20250929`) as in README; shorthand
 - **Formatting:** `uv run ruff format .`
 - **Linting:** `uv run ruff check .`
 - **Type checking:** `uv run pyright` (basic mode)
-- **Pre-commit:** `pre-commit install` — see `docs/pre-commit-hooks.md`
+- **Pre-commit:** `pre-commit install` — see [docs/pre-commit-hooks.md](docs/pre-commit-hooks.md)
 - Configuration: `pyproject.toml`
 
 ## Git Conventions
@@ -151,7 +167,8 @@ One canonical home per concern — cross-link, don't copy paragraphs.
 
 | Doc | Audience | Use for |
 |-----|----------|---------|
-| [README.md](./README.md) | Humans | Setup, CLI usage, output layout, detailed architecture |
+| [README.md](./README.md) | Humans | Setup, CLI usage, output layout |
+| [docs/architecture.md](./docs/architecture.md) | Humans and agents | Target architecture, invariants, layer model |
 | **AGENTS.md** (this file) | All coding agents | Style, architecture map, testing, key commands, git conventions |
 | [CLAUDE.md](./CLAUDE.md) | Claude Code only | Slash commands, `.claude/` maintenance |
 | [docs/](./docs/) | Humans and agents | Topic deep dives (see links below) |
@@ -162,6 +179,7 @@ One canonical home per concern — cross-link, don't copy paragraphs.
 
 ### Links
 
+- **Architecture:** [docs/architecture.md](docs/architecture.md)
 - **Setup, pipeline, output layout:** [README.md](./README.md)
 - **Custom LLM providers:** [docs/evaluating.md](./docs/evaluating.md)
 - **Judge behavior:** [docs/judge.md](./docs/judge.md)

README.md

@@ -429,7 +429,9 @@ VERA-MH simulates realistic conversations between Large Language Models (LLMs) f
 
 ## Architecture
 
-### Core Components
+See **[docs/architecture.md](docs/architecture.md)** for the target layer model, invariants, and single CLI orchestrator (`vera.py`). Below is a quick module reference; CLI usage and output layout are in the sections above.
+
+### Core Components (current implementation)
 
 - **`generate.py`**: Main entry point for conversation generation with configurable parameters
 - **`judge.py`**: Main entry point for evaluating conversations using LLM judges