Add hourly generated text contract

docs/internal/generatedtext.md

@@ -0,0 +1,73 @@
+# Generated Text Internals
+
+This document describes structured generated-text handling in
+`internal/generatedtext`.
+
+## Purpose
+
+`internal/generatedtext` validates structured text returned for
+generated-text-template reports and builds curated render contexts for
+templates. The first implemented contract is the Hourly Report.
+
+## Inputs And Outputs
+
+Inputs:
+
+- raw Hourly Report GeneratedText JSON
+- report metadata from `internal/briefing`
+- a module snapshot from `internal/module`
+- validated hourly generated text
+
+Outputs:
+
+- typed `Hourly` generated text
+- normalized stable JSON for validated hourly generated text
+- typed `HourlyRenderContext` values for `internal/reporttemplate`
+
+The hourly generated text JSON accepts:
+
+```json
+{
+  "summary": "string",
+  "timing": "string",
+  "impacts": "string",
+  "confidence": "string"
+}
+```
+
+`summary`, `timing`, and `impacts` are required after trimming whitespace.
+`confidence` is optional and omitted from normalized JSON when blank.
+
+## Boundaries
+
+- This package owns typed generated-text validation and render-context shaping.
+- It uses typed module snapshot decoding through `module.StanzaValue`.
+- It does not invoke Scriptorium, write state artifacts, choose report
+  definitions, compare snapshots, or render templates directly in production
+  workflows.
+- It does not use a Go JSON Schema dependency; schema enforcement in Go is
+  limited to typed JSON decoding, unknown-field rejection, and required-field
+  checks.
+
+## Failure Behavior
+
+- Malformed generated-text JSON fails with decode context.
+- Unknown generated-text JSON fields fail during decoding.
+- Empty required hourly fields fail after trimming whitespace.
+- Missing required render-context stanzas fail with the stanza name.
+- Invalid render metadata, including missing timezone, missing generated time,
+  or invalid valid period, fails before template rendering.
+
+## Tests
+
+Inspect:
+
+- `internal/generatedtext/hourly_test.go`
+- `internal/generatedtext/render_context_test.go`
+
+## Invariants
+
+- Render contexts are curated structs, not raw prompt-input packages.
+- Required generated text is normalized before downstream artifact storage.
+- Missing optional weather narrative stanzas produce empty or fallback render
+  context fields rather than forcing raw module data into templates.