Document internal component boundaries

docs/internal/changes.md

@@ -1,62 +1,61 @@
 # Changes Internals
 
-This document describes the implemented structured change comparison boundary.
+This document describes structured Recent Changes comparison.
 
 ## Purpose
 
-`internal/changes` compares current and prior structured briefing snapshots and
-produces compact change records for prompt input data packages.
+`internal/changes` compares current and prior briefing packages and emits
+compact change records for prompt input data packages.
 
-## Inputs and Outputs
+## Inputs And Outputs
 
 Inputs:
 
 - prior briefing package
 - current briefing package
-- configured Recent Changes thresholds
+- comparison thresholds from configuration
 
-Output:
+Outputs:
 
-- ordered `changes.Change` records with type, message, previous value, and
-  current value where useful
+- ordered `changes.Change` items with type, message, previous value, and current
+  value where useful
 
 ## Boundaries
 
 - This package compares structured briefing data only.
-- It does not read state directly, render Markdown, invoke `scriptorium`, or
-  compare generated report text.
+- It does not read filesystem state, find prior snapshots, render Markdown,
+  invoke Scriptorium, or compare generated report text.
 
 ## Config Fields Used
 
-The app maps these config fields into comparison thresholds:
+The app maps these fields into comparison thresholds:
 
 - `recent_change.temperature_degrees`
 - `recent_change.precip_probability_points`
 - `recent_change.wind_gust_miles_per_hour`
 - `recent_change.precip_timing_shift_minutes`
 
-## Behavior
+## External Adapters Used
 
-Daily, 3-Day, and Weekend comparison currently detect:
+None.
 
-- temperature changes crossing configured thresholds
-- precipitation probability and timing changes
-- alert additions and removals
-- peak wind gust changes
-- snow, ice, and thunder risk changes
+## State Or Manifest Behavior
 
-When no prior comparable snapshot exists, the app sends an empty Recent Changes
-section in the data package. Daily Today and Daily Tomorrow are compatible for
-same-valid-date comparison through the report registry. 3-Day Outlook compares
-with prior 3-Day Outlook snapshots for the same valid local date. Weekend
-Outlook compares with prior Weekend Outlook snapshots for the same weekend
-window.
+None directly. The app loads prior briefing snapshots through `internal/state`
+before calling comparison functions.
+
+## Skip And Resume Behavior
+
+No resume behavior. When the app has no prior comparable snapshot, it sends an
+empty Recent Changes list without calling a comparison function.
 
 ## Failure Behavior
 
-Daily comparison requires both inputs to contain Daily briefing content. 3-Day
-comparison requires both inputs to contain 3-Day briefing content. Weekend
-comparison requires both inputs to contain Weekend briefing content.
+- Daily comparison requires both inputs to contain Daily briefing content.
+- 3-Day comparison requires both inputs to contain 3-Day briefing content.
+- Weekend comparison requires both inputs to contain Weekend briefing content.
+- Storm Report currently has no comparison implementation, so the app leaves
+  Recent Changes empty for Storm reports.
 
 ## Tests
 
@@ -70,5 +69,6 @@ Inspect:
 ## Invariants
 
 - Recent Changes are based on structured snapshots, not Markdown report text.
-- Comparison thresholds come from configuration.
-- The comparison output remains compact enough for prompt input.
+- Report compatibility is determined outside this package by report definitions
+  and state lookup.
+- Output stays compact enough for prompt input.