Add forecast daypart derivation

docs/internal/forecast-derivation.md

@@ -0,0 +1,63 @@
+# Forecast Derivation Internals
+
+This document describes the implemented deterministic forecast summarization
+boundary.
+
+## Purpose
+
+`internal/forecast` converts a normalized forecast bundle into inspectable
+daily daypart summaries. These summaries are structured data for later briefing
+builders; they are not rendered report text.
+
+## Inputs and Outputs
+
+Inputs:
+
+- `forecast.Bundle`
+- local date and timezone
+- configured daypart definitions with `HH:MM` start and end values
+
+Output:
+
+- `forecast.DailySummary` with a civil-day period, daypart summaries, selected
+  narrative periods, alert overlaps, discussion context, source warnings, and
+  source provenance.
+
+## Boundaries
+
+- This package groups and summarizes already-normalized forecast data.
+- It does not fetch weather data, resolve report definitions, compare prior
+  snapshots, build prompt input packages, or call `scriptorium`.
+
+## Behavior
+
+- Daypart windows use half-open intervals.
+- Overnight dayparts are supported when the end clock is not after the start
+  clock.
+- Hourly forecast periods are selected by overlap with the daypart window.
+- Each daypart computes temperature range, apparent-temperature range, maximum
+  precipitation probability, peak wind speed, peak wind gust, dominant
+  condition, notable conditions, and basic weather indicators.
+- Alerts are selected by overlap with the daily period and each daypart.
+- Narrative periods and discussion context are selected as broader source
+  context for later briefing builders.
+
+## Failure Behavior
+
+- Missing hourly forecast data returns an error.
+- Invalid daypart definitions return actionable parse errors.
+- Alert records without parseable RFC3339 start/end fields are skipped.
+
+## Tests
+
+Inspect:
+
+- `internal/forecast/derive_test.go`
+- `internal/timeutil/periods_test.go`
+
+## Invariants
+
+- Weather facts come from normalized source data, not generated prose.
+- Outputs remain JSON-inspectable.
+- Forecast derivation remains independent of CLI, HTTP adapters, and report
+  registry behavior.

docs/internal/weather-data.md

@@ -5,7 +5,7 @@ This document describes the implemented weather data ingestion boundary.
 ## Purpose
 
 `internal/adapters/weatherapi` fetches normalized weather data from one
-configured weather API endpoint and assembles an `internal/forecast.Bundle`.
+configured weather API endpoint and assembles a `forecast.Bundle`.
 
 ## Inputs and Outputs