feat(engine): statistical envelopes — N-run baselines and topological equivalence - #36

What

Pillar 1 of 0.5.0. Baselines can capture N ≥ 2 runs (record --runs 5) into a versioned agentdiff_baseline_envelope artifact (schema 2.0.0, additive — agent_trace.schema.json untouched per D2). Statistical compare judges a candidate against normal variance: min-TDI-of-N alignment (D1), step-count band (|drift| ≤ k·sigma), envelope-relative cost ceiling (max of the relative cap and the variance band), divergence ceiling. Also: topological equivalence — independent same-work reorders merge to matched_commutative with zero TDI penalty — and [scenario.<name>] config sections per the PRD's v0.5 TOML spec.

Why

The #1 adoption killer of v0.3/0.4 (PRD §1): a rigid LCS match against one static baseline.json fails builds on harmless variance — tool-order shifts, ±1 steps, jitter. Agents are non-deterministic; the gate must model that. This is the load-bearing pillar for the release's success metric (≥3 teams, zero false-positive flakes).

How

• models/envelope.py: BaselineEnvelope + StatBand + compute_bands() (step count, tokens, cost, latency, per-tool tool:<name> bands); cached envelope block is recomputed from runs on load, never trusted
• loader.load_baseline(): v1 bare traces wrap as envelopes with N=1, mode strict — full back-compat; N<2 statistical envelopes demote to strict
• engine/comparator.compare_envelope(): aligns against every run, keeps the best explanation, evaluates band gates + reuses evaluate_gate for path gates and hard invariants
• engine/aligner.mark_commutative_swaps(): pairs REMOVED/ADDED by signature — requires identical inputs/outcomes, a genuine positional swap (matched steps between), and data-independence in both parent graphs (property-guarded); otherwise untouched
• config.py: [scenario.x] with nested hard_invariants/tolerances (ScenarioConfig); sole scenario needs no --scenario flag
• CLI: envelope baselines take the statistical path; --update-baseline rotates a rolling window of sample_runs and refreshes bands; record --runs N writes envelopes
• New status matched_commutative renders as "reordered" in terminal/JSON/markdown/PR/tree; excluded from culprit/first-divergence logic

Testing

• 26 new tests (test_statistical_envelope.py): bands math, v1/v2 loading + demotion, band/ceiling/divergence/loop gates, min-TDI-of-N, commutative vs dependent swaps, arg-change guard, scenario config, CLI envelope flow + rotation + record --runs
• Full suite 401 green; make lint clean; uv build green
• Benchmarks (I2b): N=3/N=5 at 100/500/1000 steps — cost linear in N (N=5 @1000 ≈ 7.4s; KB-scale traces are ms)

Checklist

• make lint + full suite green
• CHANGELOG [Unreleased] entries
• Schema additive + migration note updated (context/schema_migration.md)
• No non-goal violations (deterministic, local-first, no LLM judges)

Links to context/ROADMAP.md Phase M / 0.5.0 (SPEC-0.5.0 Pillar 1). Stacked on #32.