feat(trends): HTML trend report with SVG dot charts

[decko]

Summary

Implements an HTML trend report for raki trends with interactive SVG dot-chart timelines, tier grouping, zone-colour coding, and config-break markers. Adds --html FILE and -o/--output FILE flags to the trends subcommand.

What was built

Task 1 — Data layer (TrendChartData + build_trends_template_data()):

• TrendChartData frozen dataclass with dot_positions, zone_color, config_break_indices, delta_badge
• build_trends_template_data() converts MetricTrend → TrendChartData with SVG coordinates
• _compute_dot_positions(): maps values to SVG pixel space (y-axis inverted for SVG)
• _zone_color_for_trend(): reuses existing html_color_for_score() thresholds
• _detect_config_breaks(): compares adjacent config_hash values

Task 2 — HTML template (trends.html.j2):

• Dark-themed, self-contained HTML with inline CSS
• SVG polyline + circle dot charts per metric
• Tier groups: Operational → Knowledge → Analytical
• Config-break dashed vertical lines, delta badges, direction indicators
• Empty-state for no data

Task 3 — HTML renderer (write_trends_html_report() + build_summary_sentence()):

• Auto-creates parent directories
• build_summary_sentence() counts improving/declining/stable metrics

Task 4 — CLI wiring:

• --html FILE: writes HTML trends report, with path traversal guard
• -o/--output FILE: companion to --json for file output
• Hint line: "Tip: use --html FILE…" after the table when --html not given

Task 5 — changes/280.feature towncrier fragment
Task 6 — New "Trends report" section in docs/comparing-runs.md

Acceptance Criteria

• TrendChartData dataclass with dot_positions, zone_color, config_break_indices, delta_badge
• build_trends_template_data() converts MetricTrend to SVG coordinates
• trends.html.j2 dark-themed template with SVG dot charts and tier grouping
• write_trends_html_report() renderer with auto-directory creation
• --html FILE CLI flag with path traversal guard
• -o/--output FILE companion flag for JSON file output
• Hint line in table output when --html not given
• Towncrier changelog fragment (changes/280.feature)
• Documentation in docs/comparing-runs.md
• 1750 tests passing

Review Results

Finding 1 — IMPORTANT (python-specialist, rag-specialist)

File: src/raki/cli.py:1390
Issue: Missing path traversal guard for --json -o FILE. The --html path has a traversal check (resolved_html.relative_to(project_root)), but the --json -o code path at lines 1390–1394 writes to any user-supplied path without validation. raki trends --json -o /etc/cron.d/evil would write outside the project.
Suggestion: Add the same Path(output_path).resolve().relative_to(Path.cwd().resolve()) guard before the JSON file write, raising click.UsageError on failure. Consider extracting a shared _validate_output_path(path: str) -> Path helper.

Finding 2 — MINOR (python-specialist)

File: docs/comparing-runs.md:249
Issue: Documentation incorrectly claims the y-axis flips for lower_is_better metrics. In reality, _compute_dot_positions() always maps higher values to higher visual positions regardless of higher_is_better.
Suggestion: Simplify to: "Higher values always map to higher dot positions. Use the zone colour and direction indicator to determine whether a value is good or bad for a given metric."

Finding 3 — MINOR (python-specialist, rag-specialist)

File: src/raki/cli.py:1324
Issue: -o FILE without --json silently produces HTML output because line 1324 aliases -o to --html when json_output is False. A user running raki trends -o report.txt may not expect HTML content. Also, when both --html a.html and -o b.html are given, -o is silently ignored.
Suggestion: Either (a) require --html or --json to be explicit when -o is used, or (b) clarify the help text to read "Alias for --html when --json is not given; companion to --json for file output".

Finding 4 — MINOR (rag-specialist)

File: src/raki/cli.py:1388
Issue: --json --html FILE silently ignores the --html flag due to the early return on line 1397. The user gets no warning that their HTML report was skipped.
Suggestion: Either emit a warning when both --json and --html/effective_html_path are set, or write both outputs (JSON first, then HTML).

---

Refs #280

Assisted-by: Claude Opus 4.6 (1M context) noreply@anthropic.com
Assigned-by: decko