feat: role-aware health baselines (ADR-040)

[JLRansom]

Summary

• Adds lib/health-baselines.ts — a dedicated module that computes 30-day median baselines per agent role (medianCompletionRate, medianErrorDensity, medianWeeklyThroughput) with a 5-minute in-memory TTL cache
• Adds applyRoleBaseline() to lib/health.ts that normalises raw sub-metrics against the role's median before badge thresholds fire — a researcher at 72% completion looks healthy vs a 70% role norm, alarming vs a 92% norm
• Adds dbGetTaskRunsByRole() to taskRunRepo.ts for efficient single-query role-cohort fetches (vs N per-agent queries)
• Wires everything behind ROLE_BASELINES_ENABLED=true feature flag in health-cache.ts — off by default for safe A/B rollout and zero-risk deployment

Degradation contract

Every failure mode has a defined fallback (no silent accuracy bugs):

Condition	Behaviour
Role cohort < 3 qualifying agents	null-metrics baseline → flat thresholds
Agent < 5 runs in rolling window	hasEnoughData: false unchanged
Baseline metric null or zero	Skip normalisation for that sub-metric
Division by zero guard	Raw value preserved
New/unknown agent type	cohortSize = 0 → flat thresholds
DB error on baseline fetch	Stale cache returned; no cache → null-metrics

Design decision: BaselineNorms in health.ts

applyRoleBaseline lives in lib/health.ts. To avoid a circular import (health-baselines.ts → health.ts → health-baselines.ts), a minimal BaselineNorms interface is defined in health.ts. TypeScript's structural typing means RoleBaseline satisfies it automatically — no explicit extends needed, no coupling.

Feature flag

Set ROLE_BASELINES_ENABLED=true to activate. Recommended activation sequence:

1. Deploy (flag off) — verify no regressions
2. Enable on staging — compare badge distributions before/after
3. Enable on production — monitor badge flip rate per role for 2–3 weeks
4. Target: 30–40% reduction in noisy "declining" badges for low-volume roles (tester, researcher)

Prerequisites

• PR fix: explicit status classification in analyticsRepo #26 (fix/analytics-status-classification) merged
• PR feat: agent health scores — per-agent sub-metric badges #27 (feat/agent-health-metrics) merged
• 2–3 weeks of production run data collected (≥3 agents per role with ≥5 runs/week)

Test plan

• __tests__/unit/health-baselines.test.ts — 34 new tests covering medianOf, computeRoleBaseline, getRoleBaseline cache TTL/invalidation, and all applyRoleBaseline normalisation rules and guards
• __tests__/unit/health-cache.test.ts — 4 new integration tests: flag off → raw metrics, flag on → normalised metrics, unknown agent → graceful degradation, cache hit after normalisation
• All 201 existing tests pass unchanged (zero regressions)

🤖 Generated with Claude Code