feat: add promptlens compare for run-to-run regression detection

[brainsparker]

What this adds

promptlens compare BASELINE CANDIDATE: a run-to-run comparison command with regression detection, answering the question that matters after any prompt tweak or model swap: is this better or worse than what we had?

# Compare a known-good baseline against the most recent run
promptlens compare 20260810_120000 latest

# Gate CI on it
promptlens compare baseline-run pr-run --fail-on-regression

# Write reports for PR comments or CI artifacts
promptlens compare baseline-run pr-run --output comparison.md --json-output comparison.json

How it works:

• Runs are referenced by run ID (from promptlens list-runs), run directory, or a direct results.json path. latest resolves via the existing symlink.
• Test cases are paired by (test case ID, model), so comparisons survive reordered, added, and removed cases. Added and removed cases are reported but never counted as regressions.
• A paired case is regressed when its judge score drops beyond --score-threshold (default 0, any decrease) or when it newly errors. Error transitions dominate scores: ok to error is always a regression, error to ok is always an improvement. --score-threshold 1 ignores one-point judge jitter on the 1-5 scale.
• Terminal output is a rich summary table plus a list of regressed cases. --output writes a Markdown report suitable for PR comments; --json-output writes the full typed comparison.
• --fail-on-regression exits non-zero when any paired case regressed, mirroring the --fail-under gate shipped in feat: add JUnit XML exporter and --fail-under CI quality gate #43. Without the flag the comparison is informational.

Why this, why now

• deepeval just shipped this exact capability as a first-class CLI verb (deepeval compare), with chronological run pairing, regression detection, and --fail-on-regression for CI: Add local test run comparison CLI with regression reporting confident-ai/deepeval#2935. Their hosted platform markets baseline comparison as a headline feature: https://www.confident-ai.com/frameworks/deepeval
• promptfoo delivers the same outcome through its GitHub Action, re-running evals on base vs head and posting a delta scorecard per PR, which validates strong demand for before/after eval diffing: https://www.promptfoo.dev/docs/integrations/github-action/
• Practitioners name the gap directly: without a baseline "you cannot even answer the one question that matters after a change: is this better or worse than what we had?" https://medium.com/@alexrodriguesj/testing-llm-prompts-like-code-regression-evals-in-ci-cd-with-promptfoo-5242b4dcb9be
• Timing: the current wave of model releases (Gemini 3.1 Pro, Claude Opus 4.5, GPT-5.1) has teams benchmarking new checkpoints against production baselines before switching. PromptLens already stores every run as a portable results.json, so this lands as pure local post-processing: no cloud dependency, which is the project's core positioning.
• This is the natural next step after feat: honor runtime retry and timeout execution settings in all providers #42/feat: add JUnit XML exporter and --fail-under CI quality gate #43: --fail-under catches absolute quality floors, compare --fail-on-regression catches relative slippage between versions.

Runner-up candidates considered today: GitHub Copilot export target for you.md, and a drift-check command for you.md. Both remain good future options; this one had the strongest demand evidence and the cleanest single-PR fit.

Implementation notes

• New module promptlens/comparison.py: pydantic models (CaseComparison, ModelSummary, ComparisonResult), pairing/classification logic, and a Markdown renderer. No new dependencies.
• New compare command in promptlens/cli.py with _resolve_run_reference accepting run IDs, run directories, or results.json paths.
• Status classification: regressed, improved, unchanged, unscored, added, removed. Regressions sort first in reports.
• Per-model aggregates reuse the existing RunResult.get_average_score / get_total_cost helpers.
• README: feature bullet, CLI reference entry, and a "Comparing Runs and Catching Regressions" section in CI/CD Integration with a baseline-artifact recipe.

Test status

• 25 new tests in tests/test_comparison.py covering classification (score drops, thresholds, error transitions, unscored cases), pairing (reordering, added/removed cases, multi-model), aggregates, Markdown rendering, and the CLI (run-ID and path resolution, exit codes, report writing).
• Full suite: 83 passed locally on Python 3.9.
• Verified end to end against fabricated baseline/candidate run directories: correct terminal output, Markdown and JSON reports, exit code 1 with --fail-on-regression, exit code 0 without.