feat(0.2): empty-state helpers + visual regression goldens (Tracks 10.6/10.8)

[pmclSF]

Summary

Two Track 10 deliverables that lift the visual / UX side of 0.2.0
from "every renderer invents its own empty-state message" to "one
designed vocabulary, regression-locked."

• Track 10.6 — Empty state helpers. Seven designed kinds
  (zero-findings, no-AI-surfaces, no-policy, first-run,
  no-impact, no-test-selection, no-migration-candidates) with
  terminal-text + markdown render targets, voice & tone rules
  locked at the test level.
• Track 10.8 — Visual regression goldens (foundation). Seven
  byte-for-byte golden files + drift gate that verifies the
  goldens directory tracks the shipped enum 1:1. Pattern extends
  to PR-comment markdown / SARIF / HTML when those land.

What changed

New code:

• internal/reporting/empty_states.go — EmptyStateKind enum,
  EmptyStateFor / RenderEmptyState / EmptyStateMarkdown helpers
• internal/reporting/insights_report_v2.go — first integration:
  swaps the bare "No significant issues detected." line for the
  designed EmptyZeroFindings rendering

New tests (11):

• contract: all shipped kinds have a designed header
• voice & tone: no exclamation, no emoji, no British spellings
• next-move: every kind references a command in backticks
• markdown render: blockquote callout shape
• terminal render: header + indented arrow next-move
• goldens: 7 byte-for-byte assertions
• drift gate: goldens dir matches shipped enum 1:1

New goldens:

• testdata/empty_state_goldens/{zero_findings,no_ai_surfaces, no_policy_file,first_run,no_impact,no_test_selection, no_migration_candidates}.txt — one per kind

Why these two together

10.6 (helpers) and 10.8 (goldens) form a single coherent unit:
the helpers define the vocabulary, the goldens lock it. Shipping
just the helpers without the goldens leaves the visual contract
unenforced; shipping just the goldens without designed messages
makes them low-leverage. Together they give the broader Track 10
visual identity work a stable foundation to build on.

Test plan

• go build ./... clean
• go test ./internal/reporting/... — 11 new tests pass +
  existing tests unaffected
• go test ./... — full suite green, no regression
• make docs-verify passes
• Manual smoke: terrain insights on a clean repo renders
  the new "Nothing to flag" header with next-move (separate
  verification — needs a clean fixture)

Plan tracker

Closes Track 10.6 + 10.8. Track 10 remaining: 10.2 renderer audit

• 10.3 PR-comment redesign + 10.4 HTML report redesign + 10.5
  progress indicators + 10.7 voice & tone pass. Those depend on the
  uitokens design system foundation (Track 10.1, in PR feat(0.2): internal/uitokens/ design system foundation (Track 10.1) #136); they
  land cleanly once that PR merges.

🤖 Generated with Claude Code

[github-actions]

[RISK] Terrain — Merge with caution

High-severity gaps found in changed code.

Metric	Value
Changed files	11 (2 source · 3 test)
Impacted units	6
Protection gaps	2
Tests selected	2 of 774 (0% of suite)

---

Coverage gaps in changed code

• internal/reporting/empty_states.go [MED] — Exported function EmptyState has no observed test coverage.
  → Add unit tests for exported function EmptyState — this is public API surface.
• internal/reporting/insights_report_v2.go [MED] — Exported function RenderInsightsReport has no observed test coverage.
  → Add unit tests for exported function RenderInsightsReport — this is public API surface.

---

Pre-existing issues (2)

• internal/reporting/empty_states.go [HIGH] — [blastRadiusHotspot] Changes to this file propagate to 1801 tests (120 direct, 1681 indirect). High blast radius increases regression risk.
• internal/reporting/insights_report_v2.go [HIGH] — [blastRadiusHotspot] Changes to this file propagate to 1801 tests (120 direct, 1681 indirect). High blast radius increases regression risk.

---

Recommended tests

2 test(s) with exact coverage of 4 impacted unit(s). 2 impacted unit(s) have no covering tests in the selected set.

Test	Confidence	Why
internal/reporting/empty_state_goldens_test.go	exact	exact coverage of EmptyStateKind, RenderEmptyState
internal/reporting/empty_states_test.go	exact	exact coverage of EmptyStateFor, EmptyStateMarkdown

---

Owners: PMCLSF

Limitations

• No coverage artifacts provided; protection gaps reflect missing data, not measured absence. Provide --coverage to improve accuracy.
• Mixed test cultures reduce cross-framework optimization confidence. Consider standardizing on fewer frameworks.

_{Generated by Terrain · terrain pr --json for machine-readable output}

Targeted Test Results

Terrain selected 2 test(s) instead of the full suite.

• Go tests: passed

[github-actions]

Terrain AI Risk Review

Metric	Value
AI surfaces	13
Eval scenarios	16
Impacted scenarios	0
Uncovered surfaces	13

Decision: PASS — AI surfaces are covered.