docs: roadmap replaces migration phases and TODO; bump to v2.0.3

[luca-belli]

Summary

Splits the migration plan out of docs/architecture.md into a new docs/roadmap.md, folds the root TODO file into it, and bumps the CHANGELOG to v2.0.3. architecture.md now describes the target state only.

Stacked on #248 because both PRs change the same AGENTS.md lines. GitHub retargets this PR to main once #248 merges.

docs/roadmap.md

• Phases have names, not numbers, so reordering never changes what an existing reference means. Order: Scoring split → Rubric-agnostic scoring (new) → Traceability → Model spec boundary → Shared engine → Quality gates. Storage and OpenSpec are independent of the rest.
• Rules: every phase keeps legacy/ working ("legacy adapts; the domain doesn't bend"). Each phase needs maintainer sign-off before it starts. A broken phase is rolled back by reverting its PRs.
• Pyright becomes a per-package blocking step, added as each package reaches zero errors.
• Backlog: smaller items that belong to no phase, grouped by area.
• Deferred: removing legacy/ (triggered by a tagged release); per-persona system prompts.
• Completed: target manifests, the vera CLI, the package moves (chore: move the legacy scripts into legacy/ (v2.0.2) #243, refactor: rename generate_conversations package to generate #245, refactor: move scoring into top-level score package (run, aggregate, viz) #246), and multi-rubric evaluation (below).

Multi-rubric evaluation is done, by design

Evaluating conversations with several evaluators (rubrics) means one target per rubric, each judged separately with vera judge --target <name>. That was the intended end state, not a stopgap. Scores from different rubrics aren't comparable and must never be merged, so keeping them in separate runs is deliberate. The old plan for several rubrics inside one run (judging.rubrics length > 1, per-rubric judge-model overrides) is dropped. judging.rubrics keeps its list shape and length-1 check, so revisiting it later wouldn't break the schema. vera judge --target all remains, as a convenience that ships with Traceability. docs/architecture.md, vera_cli/judge.py, and the CHANGELOG say the same.

TODO deleted

• Phase-sized items became phase content with their detail intact: pooled pipeline score, config checksums, SI dimensions and rubric fingerprint, the END-token bug, dimension_verdicts, risk_level from the judge.
• The 13 smaller items moved to the roadmap's Backlog. Corrected the load_dotenv item: it isn't done, since llm_clients/config.py still loads .env at import time.
• Repointed every reference to TODO: docs/architecture.md, docs/vera-cli-use-cases.md, .github/workflows/live.yml, the dimension_verdicts design record.

Version bump to v2.0.3

The current [Unreleased] entries now sit under ## [v2.0.3] \- Unreleased, in the same style as v2.0.2, and a fresh empty [Unreleased] sits above them. No tag is created; a human tags when the release goes out. Note: v2.0.3 contains package renames, which under strict SemVer would be a major release. A patch release was chosen deliberately.

Phase references

All 21 references to old phase numbers or the deleted section now use phase names. Outside docs they appear only in comments and docstrings: vera_cli/judge.py, legacy/judge.py, utils/rubric_manifest.py, three tests, docs/ARCHITECTURE-SPINE.md, docs/vera-cli-use-cases.md, CODEOWNERS. AGENTS.md gets a roadmap row in the Documentation Map.

Notes for reviewers

• Merge order: docs: AGENTS.md conventions for changelog, module naming, pyright, legacy #248 → refactor: move scoring into top-level score package (run, aggregate, viz) #246 → this PR. When rebasing after refactor: move scoring into top-level score package (run, aggregate, viz) #246, expect a conflict in test_score_parity.py's docstring; keep this PR's wording. TODO will also conflict, because this PR deletes it; keep the deletion. Move refactor: move scoring into top-level score package (run, aggregate, viz) #246's "Scoring moved to score/" CHANGELOG entry into [v2.0.3].
• Assumes refactor: move scoring into top-level score package (run, aggregate, viz) #246: the roadmap describes the state after refactor: move scoring into top-level score package (run, aggregate, viz) #246 (score/ with run.py/aggregate.py/viz.py, pyright-clean).
• CODEOWNERS: utils/config_schema.py now exists but is still not listed. The roadmap ties formalizing it as a stable interface to Traceability.

Test plan

• No Phase <n>, #migration-from-current-layout, or root-TODO references left outside CHANGELOG history
• Every relative link and anchor in the changed docs resolves. The only broken links are five in historical CHANGELOG entries, which were already broken.
• uv run ruff check . and ruff format --check .. Code changes are comments and docstrings only.

🤖 Generated with Claude Code