feat(anomalies): rewrite summaries for human-scannable text

Replace the mechanical anomaly template with natural-language summaries.
Volume shifts show a multiplier ("3× normal traffic"), dimension spikes
name the slice ("from country=DE jumped to 47"), and sigma is demoted
to a parenthetical. Pitch status flipped to Shipped — pending PR.

- Volume shift: "GET /search saw 3× normal traffic (240 vs ~80/day) (12.0σ above baseline)"
- Dimension spike: "GET /items/:id from country=DE jumped to 47 (normally ~3/day) (8.1σ above baseline)"
- Zero-mean fallback: "X saw N events (no prior baseline)"
- 3 tests pinning both formats and the cold-start edge case

Author: luuuc

.doc/pitches/01a-noise-and-anomaly-curation.md

@@ -3,7 +3,7 @@
 *Make Beacon's data trustworthy by killing noise at the source and making anomalies actionable. Follow-up to pitch 01, cards 3 (anomaly detector), 4 (anomaly read endpoint + MCP tool), and 7 (anomaly dashboard page).*
 
 **Appetite:** small batch (~3 days)
-**Status:** Building
+**Status:** Shipped — pending PR
 **Owner:** Solo founder + AI producers
 **Predecessor:** `pitches/01-ambient-anomalies.md` (shipped the anomaly detector, `beacon.anomalies` MCP tool, and `/anomalies` dashboard page)
 **Related:** `definition/06-http-api.md` (MCP server contract, `/api/anomalies` endpoint), `definition/03-data-model.md` (anomaly records in `beacon_metrics`), `decisions/0002-maket-first-integration.md` (Maket as proof point)
@@ -133,4 +133,4 @@ Cards are in dependency order. Cards 1-3 are P0. Cards 4-5 are P1.
 
 - [x] **Anomaly dismiss** — add `dismissed_at` column to anomaly records in `beacon_metrics`. Dashboard: "×" button on anomaly cards, htmx DELETE to `/anomalies/:id/dismiss`. HTTP API: `DELETE /api/anomalies/:id`. `GetAnomalies` excludes dismissed records. *Done when:* dismissing an anomaly in the dashboard removes it from the list, a dismissed anomaly stays gone across page refreshes and API queries, and `DELETE /api/anomalies/:id` returns 200 with subsequent `GET /api/anomalies` excluding it.
 
-- [ ] **Smarter anomaly summaries** — rewrite the summary template in the anomaly detector to produce human-scannable text. Volume shifts: "X saw N× normal traffic (current vs ~baseline/day)". Dimension spikes: "X from dimension=value jumped to N (normally ~baseline/day)". σ as parenthetical. *Done when:* new summaries appear in both dashboard and MCP responses, and a test asserts the new format against a known anomaly record.
+- [x] **Smarter anomaly summaries** — rewrite the summary template in the anomaly detector to produce human-scannable text. Volume shifts: "X saw N× normal traffic (current vs ~baseline/day)". Dimension spikes: "X from dimension=value jumped to N (normally ~baseline/day)". σ as parenthetical. *Done when:* new summaries appear in both dashboard and MCP responses, and a test asserts the new format against a known anomaly record.

internal/reads/reads.go

@@ -765,8 +765,7 @@ func (h *Handler) GetAnomalies(ctx context.Context, req GetAnomaliesRequest) (*A
 			stddev = *m.P95
 		}
 
-		summary := fmt.Sprintf("%s %s: %d in 24h vs baseline of %.0f",
-			m.Name, m.Fingerprint, m.Count, mean)
+		summary := anomalySummary(m.Fingerprint, m.Name, m.Dimensions, m.Count, mean, deviation)
 
 		entries = append(entries, AnomalyEntry{
 			ID:             m.ID,
@@ -830,6 +829,39 @@ func (h *Handler) handleDismissAnomaly(w http.ResponseWriter, r *http.Request) {
 }
 
 // ---------------------------------------------------------------------------
+// anomalySummary builds a human-scannable summary for an anomaly record.
+//
+//	volume_shift:    "GET /search saw 3× normal traffic (240 vs ~80/day) (12.0σ above baseline)"
+//	dimension_spike: "GET /items/:id from country=DE jumped to 47 (normally ~3/day) (8.1σ above baseline)"
+func anomalySummary(anomalyKind, name string, dims map[string]any, current int64, mean, sigma float64) string {
+	sigmaStr := fmt.Sprintf("(%.1fσ above baseline)", sigma)
+
+	if anomalyKind == "dimension_spike" && len(dims) > 0 {
+		// Build "dim1=val1, dim2=val2" string.
+		keys := make([]string, 0, len(dims))
+		for k := range dims {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+		parts := make([]string, 0, len(keys))
+		for _, k := range keys {
+			parts = append(parts, fmt.Sprintf("%s=%v", k, dims[k]))
+		}
+		dimStr := strings.Join(parts, ", ")
+		return fmt.Sprintf("%s from %s jumped to %d (normally ~%.0f/day) %s",
+			name, dimStr, current, mean, sigmaStr)
+	}
+
+	// Volume shift.
+	if mean > 0 {
+		multiplier := float64(current) / mean
+		return fmt.Sprintf("%s saw %.0f× normal traffic (%d vs ~%.0f/day) %s",
+			name, multiplier, current, mean, sigmaStr)
+	}
+	return fmt.Sprintf("%s saw %d events (no prior baseline) %s",
+		name, current, sigmaStr)
+}
+
 // helpers
 // ---------------------------------------------------------------------------
 

internal/reads/reads_test.go

@@ -705,6 +705,92 @@ func TestHandleDismissAnomaly_HTTP(t *testing.T) {
 	}
 }
 
+func TestAnomalySummary_volumeShift(t *testing.T) {
+	h, fake := newTestHandler(t, Config{})
+	seedMetric(t, fake, beacondb.Metric{
+		Kind: beacondb.KindPerf, Name: "GET /search",
+		PeriodKind: beacondb.PeriodAnomaly, PeriodWindow: "24h",
+		PeriodStart: fixedNow.Add(-1 * time.Hour),
+		Count: 240, Sum: fp(12.0), P50: fp(80), P95: fp(13.3),
+		Fingerprint: "volume_shift",
+	})
+
+	resp, err := h.GetAnomalies(context.Background(), GetAnomaliesRequest{Since: 24 * time.Hour})
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := resp.Anomalies[0].Summary
+	if !strings.Contains(s, "GET /search") {
+		t.Errorf("summary missing name: %q", s)
+	}
+	if !strings.Contains(s, "normal traffic") {
+		t.Errorf("summary missing 'normal traffic': %q", s)
+	}
+	if !strings.Contains(s, "240 vs ~80/day") {
+		t.Errorf("summary missing current vs baseline: %q", s)
+	}
+	if !strings.Contains(s, "12.0σ above baseline") {
+		t.Errorf("summary missing sigma parenthetical: %q", s)
+	}
+}
+
+func TestAnomalySummary_dimensionSpike(t *testing.T) {
+	h, fake := newTestHandler(t, Config{})
+	seedMetric(t, fake, beacondb.Metric{
+		Kind: beacondb.KindAmbient, Name: "GET /items/:id",
+		PeriodKind: beacondb.PeriodAnomaly, PeriodWindow: "24h",
+		PeriodStart:   fixedNow.Add(-1 * time.Hour),
+		Count:         47,
+		Sum:           fp(8.1),
+		P50:           fp(3),
+		P95:           fp(5.4),
+		Fingerprint:   "dimension_spike",
+		Dimensions:    map[string]any{"country": "DE"},
+		DimensionHash: "abc",
+	})
+
+	resp, err := h.GetAnomalies(context.Background(), GetAnomaliesRequest{Since: 24 * time.Hour})
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := resp.Anomalies[0].Summary
+	if !strings.Contains(s, "country=DE") {
+		t.Errorf("summary missing dimension: %q", s)
+	}
+	if !strings.Contains(s, "jumped to 47") {
+		t.Errorf("summary missing 'jumped to': %q", s)
+	}
+	if !strings.Contains(s, "normally ~3/day") {
+		t.Errorf("summary missing baseline: %q", s)
+	}
+	if !strings.Contains(s, "8.1σ above baseline") {
+		t.Errorf("summary missing sigma: %q", s)
+	}
+}
+
+func TestAnomalySummary_zeroMeanFallback(t *testing.T) {
+	h, fake := newTestHandler(t, Config{})
+	seedMetric(t, fake, beacondb.Metric{
+		Kind: beacondb.KindPerf, Name: "GET /new-endpoint",
+		PeriodKind: beacondb.PeriodAnomaly, PeriodWindow: "24h",
+		PeriodStart: fixedNow.Add(-1 * time.Hour),
+		Count: 25, Sum: fp(5.0), P50: fp(0), P95: fp(0),
+		Fingerprint: "volume_shift",
+	})
+
+	resp, err := h.GetAnomalies(context.Background(), GetAnomaliesRequest{Since: 24 * time.Hour})
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := resp.Anomalies[0].Summary
+	if !strings.Contains(s, "no prior baseline") {
+		t.Errorf("summary missing fallback text: %q", s)
+	}
+	if !strings.Contains(s, "25 events") {
+		t.Errorf("summary missing event count: %q", s)
+	}
+}
+
 func TestHandleAnomalies_emptyResponse(t *testing.T) {
 	h, _ := newTestHandler(t, Config{})
 	m := mux(h)