Files

Eric Rakestraw 2b06541ef8 Record the Stage 12 generated text audit

2026-08-12 16:24:13 +00:00

202 KiB

Raw Blame History

Repository Audit Ledger

Status: In progress; Stages 1-12 complete.

This temporary roadmap document is the evidence ledger for the staged audit defined by the audit plan. It records audit evidence and status, not implemented product behavior. Current contracts remain with the canonical owners identified by the documentation policy.

Executive Summary

Stage 1 established a clean, reproducible baseline. The repository-wide test suite, CLI help check, formatting check, and vet check all pass. Stage 2 found that the implemented package graph and principal workflows follow the intended dependency direction and assigned ownership. It recorded one low-severity candidate finding for unused internal persistence helpers left outside the documented stateless workflows. Stage 3 found one medium-severity correctness defect in wall-clock window construction on daylight-saving transition days and one medium-severity test gap around Daily run-ID uniqueness. Report registry identities, command and configuration lookup policies, batch membership, civil-day periods, and rolling-hour periods otherwise match their documented contracts. Stage 4 found three medium-severity validation defects: unsupported missing-source keys are silently accepted, two single-report notification identities may render blank, and programmatically constructed report overrides are silently ignored. It also found one low-severity secret loading atomicity defect. Defaults, file and CLI precedence, strict YAML field handling, active Promptkit settings, output-path preservation, and maintained examples otherwise match their contracts. Stage 5 found two medium-severity CLI correctness defects: operating-system interrupts never become workflow cancellation, and generate validates report dates only after constructing its executor. It also found a medium-severity test gap around assembled generate and ordinary batch result/exit behavior. Command ownership, flag acceptance, output routing, quiet mode, comparison error bounding, and the implemented result-to-exit mapping otherwise follow the documented contract. Stage 6 found four medium-severity defects at the Weather API boundary: unsupported URL schemes pass validation until transport, non-2xx response bodies flow verbatim into normal diagnostics, the nominal response limit silently truncates instead of rejecting oversized bodies, and required hourly products accept periods without usable time bounds. It also found one low-severity retry-policy defect because warmup retries permanent HTTP failures. Source availability policy, checked-empty products, query construction, cancellation, provenance, normalization ownership, and focused offline fixtures otherwise match their contracts. Stage 7 found three medium-severity derivation defects: metric fallback values lose their unit and are compared or presented as US customary values, overnight dayparts omit alerts that begin after midnight, and precipitation probabilities outside the percentage domain flow into summaries. It also found one low-severity text classification defect because ordinary “icy” conditions do not set the ice indicator. Half-open period selection, deterministic ordering, alert parsing, precipitation-window grouping, checked-empty SPC handling, report-family fact selection, and realistic derivation cost otherwise match their contracts. Stage 8 found two medium-severity module-boundary defects: pointer-shaped AFD options pass registry/config validation but fail during construction, and an empty weather-story object is published as available. It also found one low-severity snapshot compatibility defect because validation accepts any nonempty schema version. Default composition, supported-report rules, source-module omission, checked-empty alerts, ordered snapshots, and curated current/hourly prompt exports otherwise match their contracts. Stage 9 found six medium-severity briefing defects: apparent temperature is published as heat index, normalized daypart keys can overwrite one another, planning applies configurable daypart names inconsistently, outdoor-window ranking ignores snow, ice, and fog, subzero temperatures are described as positive zero-degree bands, and embedded descriptions labeled as official SPC definitions have drifted from the current SPC category table. Derived precipitation timing, deterministic display ordering, missing-data behavior, SPC overlap and threshold selection, and the intended Today versus Daily/Tomorrow planning variation otherwise match their contracts. Stage 10 found two high-severity prompt-contract defects: the shared prompt names nonexistent paths for primary derived facts and alert metadata, and it incorrectly characterizes every retained SPC product as location-matched. It also found three low-severity boundary and contract gaps: raw source-warning types and transport paths cross into provider input, the exported YAML loader accepts several malformed package shapes, and stanza serialization failures lack a focused regression test. Prompt/profile/schema identities, deterministic category ordering, neutral execution lifecycle and error categories, safe bounded errors, debug opt-in, and output-copy isolation otherwise match their contracts. Stage 11 found two medium-severity security defects in the explicit debug path: common credential aliases and URL forms survive heuristic redaction, and pathname-based symlink checks can be raced before sensitive files are created or replaced. Promptkit type containment, source precedence, exact inline execution, credential preflight, cancellation, safe error classification, callback ordering, restrictive modes, atomic file replacement, and ordinary concurrent execution otherwise match their contracts. Stage 12 found one medium-severity catalog defect because known schema/template pairs are accepted for the wrong report, one low-severity schema/decoder mismatch because Go accepts case-variant property names, one medium-severity resource and diagnostic-boundary defect because generated prose and unknown-field errors are unbounded, and one low-severity test maintenance defect from duplicated day-style and misplaced schema assertions. Typed normalization, required-field semantics, immutable schema copies, and the current registry's four identities otherwise match their contracts. Subsystem conclusions and final disposition remain pending the later stages.

Baseline Metadata

Item	Recorded baseline
Audit date	2026-08-12 (UTC)
Commit	`e7c7262404ba0e8e74009ed840d38f7a0142b347` (`Add audit workflow plan`)
Expected commit from audit plan	`151c536cb91ebedb6039270b752bae219dfe33d0` (`Add comparison diagnostics to the future roadmap`)
Baseline difference	The audit uses the current `main`, one commit ahead of the expected commit. The intervening commit adds the audit workflow plan used to conduct this audit.
Branch	`main`
Initial worktree	Clean; `git status --porcelain=v1` produced no entries before the audit ledger was created.
Go toolchain	`go version go1.26.5 linux/amd64`; `go env GOVERSION` reported `go1.26.5`.
Module	`gitea.maximumdirect.net/eric/weatherreporter`; module file `/home/eric/Workspace/weatherreporter/go.mod`; `go 1.26`.
Workspace context	Module mode with no `go.work`; `go env GOWORK` was empty and the repository contains only `./go.mod`.
Graph project	`home-eric-Workspace-weatherreporter`
Graph refresh	Refreshed from the baseline checkout in `moderate` mode without a persisted artifact: 2,674 nodes and 11,572 edges. The indexer excluded `docs`, `examples`, embedded-asset directories, and test-data directories, so their inventories below come from tracked files rather than the graph.
Baseline exclusions	None. There were no pre-existing worktree changes.
Environmental limitations	None encountered. Validation was deterministic and offline.

Scope And Inventory

Stage 1 inventories the checked-out repository without judging subsystem correctness or test sufficiency. The repository has 219 tracked files. Its Go inventory contains 24 packages, 83 non-test source files, and 50 test files.

Go Packages And Files

Package directory	Production `.go` files	`_test.go` files
`cmd/weatherreporter`	1	0
`internal/adapters/distributor`	1	1
`internal/adapters/promptkit`	1	1
`internal/adapters/weatherapi`	1	1
`internal/app`	10	11
`internal/briefing`	21	6
`internal/buildinfo`	1	0
`internal/cli`	4	5
`internal/collect`	1	1
`internal/comparison`	2	2
`internal/config`	7	2
`internal/facts`	1	1
`internal/fileutil`	1	1
`internal/forecast`	3	1
`internal/generatedtext`	8	7
`internal/module`	1	1
`internal/promptassets`	1	1
`internal/promptdebug`	1	1
`internal/promptexec`	2	1
`internal/promptinput`	1	1
`internal/report`	8	1
`internal/reporttemplate`	2	1
`internal/timeutil`	3	2
`internal/weatherdata`	1	1
Total	83	50

Fixtures

Nine tracked fixtures are present:

internal/adapters/weatherapi/testdata/alerts.json
internal/adapters/weatherapi/testdata/convective_outlooks.json
internal/adapters/weatherapi/testdata/current.json
internal/adapters/weatherapi/testdata/discussion.json
internal/adapters/weatherapi/testdata/hourly.json
internal/adapters/weatherapi/testdata/narrative.json
internal/adapters/weatherapi/testdata/observations.json
internal/adapters/weatherapi/testdata/weather_story.json
internal/forecast/testdata/daily_bundle.json

Embedded Assets

The three //go:embed declarations cover 26 tracked assets:

one SPC definition file under internal/briefing/assets/;
three Promptkit profiles, ten prompt files, and four generated-text schemas under internal/promptassets/assets/; and
four report templates and four template partials under internal/reporttemplate/templates/.

The exact embedding owners are internal/briefing/spc_convective_outlook_definitions.go, internal/promptassets/promptassets.go, and internal/reporttemplate/reporttemplate.go.

Canonical Documents And Maintained Examples

There are 38 tracked, non-roadmap canonical documents and three maintained example files. The canonical inventory is:

product and maintainer references: README.md, docs/cli.md, docs/config.md, docs/development.md, docs/operations.md, docs/release.md, and docs/templates.md;
policies: docs/policy/architecture.md, docs/policy/documentation.md, and docs/policy/testing.md;
architecture decisions: docs/adr/0001-stateless-execution.md;
integration contracts: docs/integrations/comparison-bundle.md, docs/integrations/promptkit.md, docs/integrations/weatherapi.md, and the three documents under docs/integrations/distributor/;
internal documents: all 17 tracked documents under docs/internal/; and
release notes: the four tracked documents under docs/releases/.

The maintained examples are examples/config.yml, examples/minimal-config.yml, and examples/weather-light-local-profile.yml. Roadmaps are coordination records, not canonical current-state documents; the four pre-existing roadmap files are therefore outside the canonical count.

Baseline Validation

Command	Result	Evidence
`go test ./...`	Pass	Exit 0. All 24 packages were evaluated; 22 package test suites passed and `cmd/weatherreporter` plus `internal/buildinfo` reported no test files.
`go run ./cmd/weatherreporter --help`	Pass	Exit 0. Help printed usage for help, version, four report generators, two batch commands, and comparison.
`git diff --check`	Pass	Exit 0 with no output on the clean pre-ledger baseline.
`go vet ./...`	Pass	Exit 0 with no diagnostics.

Supplementary baseline commands were git rev-parse HEAD, git rev-list --left-right --count 151c536...HEAD, git status --porcelain=v1, git branch --show-current, go version, go env GOVERSION GOMOD GOWORK GO111MODULE, go list ./..., tracked-file inventory commands, graph index refresh, and graph architecture inspection.

Stage Coverage

Stage	Scope	Status
1	Establish the baseline and audit ledger	Complete
2	Audit architecture and dependency direction	Complete
3	Audit report identity and time foundations	Complete
4	Audit configuration, secrets, and validation	Complete
5	Audit CLI parsing, wiring, and output contracts	Complete
6	Audit weather data acquisition and collection	Complete
7	Audit forecast and fact derivation	Complete
8	Audit module contracts, registry, and source-facing briefing modules	Complete
9	Audit derived, planning, formatting, and SPC briefing modules	Complete
10	Audit prompt inputs, assets, and neutral execution contracts	Complete
11	Audit Promptkit adaptation and secure prompt debugging	Complete
12	Audit generated-text validation and catalog contracts	Complete
13	Audit render contexts, templates, and Markdown rendering	Pending
14	Audit application preparation and prompt preflight	Pending
15	Audit single-report generation and atomic output	Pending
16	Audit batch orchestration and Distributor notification	Pending
17	Audit comparison contracts and transactional publication	Pending
18	Audit comparison execution and CLI integration	Pending
19	Audit test hermeticity and execution hygiene	Pending
20	Audit test risk coverage and ownership	Pending
21	Audit test durability, duplication, and maintenance cost	Pending
22	Audit cross-cutting efficiency and complexity	Pending
23	Audit cross-cutting refactoring and deduplication opportunities	Pending
24	Audit documentation coherence and executable contracts	Pending
25	Run dynamic robustness and final diagnostic validation	Pending
26	Verify, consolidate, and triage findings	Pending
27	Produce the remediation roadmap and close the audit	Pending

Risk-To-Test Coverage

Stage 1 records where tests exist but does not infer sufficiency from package counts or a passing suite. Assigned stages will replace these pending entries with evidence about meaningful risks, test ownership, gaps, and duplication.

Risk area	Current test owner or evidence source	Audit stage	Coverage assessment
Architecture and dependency direction	Assembled app and CLI tests; graph traces	2	Sufficient at the architectural boundary: direct imports are acyclic, external dependency types remain adapter-local, and representative workflow ordering and publication boundaries have focused tests. `AUD-001` records unused persistence APIs that do not participate in normal execution.
Report identity, periods, dates, and timezones	`internal/report`, `internal/timeutil`, plus focused `internal/app` and `internal/forecast` callers	3	Partly insufficient. Registry identities, alias policies, batch membership, civil-day boundaries, and elapsed six-hour periods are coherent and exercised. `AUD-002` records incorrect wall-clock windows on daylight-saving transition days, and `AUD-003` records the missing regression test for Daily run-ID uniqueness across dates.
Configuration, validation, and secrets	`internal/config`, focused `internal/cli` and Promptkit adapter mapping, maintained examples	4	Partly insufficient. Defaults, precedence, known-field parsing, active URL/duration/template checks, output-path preservation, profile-source rules, secret redaction, and examples are exercised. `AUD-004` through `AUD-007` record unsupported missing-source keys, blank notification identities, constructed-report override inconsistency, and non-atomic secret environment mutation.
CLI parsing, output, and exit behavior	`cmd/weatherreporter`, `internal/cli`, representative app-facing CLI tests	5	Partly insufficient. Command/flag ownership, paths, one-executor mapping, stream separation, quiet mode, comparison safe errors, and visible result/exit rules are coherent. `AUD-008` records missing signal cancellation, `AUD-009` records late generate date validation, and `AUD-010` records missing assembled non-comparison CLI protection.
Weather transport and normalized collection	`internal/adapters/weatherapi`, `internal/collect`, `internal/weatherdata`	6	Partly insufficient. All eight source requests, required/optional policy, checked-empty products, retryable source statuses, cancellation, normalized provenance, and collection error ownership have focused offline coverage. `AUD-011` through `AUD-015` record unsupported schemes, unsafe response-body diagnostics, an unenforced body-size limit, structurally invalid required hourly periods, and overbroad warmup retries.
Forecast and fact derivation	`internal/forecast`, `internal/facts`	7	Partly insufficient. Half-open selection, stable ordering, alert parsing and clipping, precipitation-window grouping, report-family selection, and SPC checked-empty behavior have focused owners. `AUD-016` through `AUD-019` record unit collapse, overnight alert omission, invalid percentage acceptance, and incomplete ice-text classification.
Module and briefing contracts	`internal/module`, `internal/briefing`	8-9	Partly insufficient. Registry/default composition, report support, missing optional sources, checked-empty alerts, output identity, ordering, current/hourly prompt curation, precipitation timing, and SPC selection have focused owners. `AUD-020` through `AUD-028` record inconsistent pointer options, false weather-story availability, permissive snapshot schema validation, apparent-temperature mislabeling, daypart-key collisions, inconsistent planning identities, incomplete outdoor hazard scoring, incorrect subzero phrases, and stale official SPC descriptions.
Prompt inputs, embedded assets, and execution contracts	`internal/promptinput`, `internal/promptassets`, `internal/promptexec`	10	Partly insufficient. Prompt/profile/schema identities, deterministic grouping, validation/execution result categories, safe bounded errors, explicit debug, and copy isolation have focused owners. `AUD-029` through `AUD-033` record raw warning types and transport paths crossing the boundary, stale embedded prompt paths, incorrect SPC locality instructions, permissive YAML loading, and missing serialization-failure coverage.
Promptkit boundary and sensitive debug output	`internal/adapters/promptkit`, `internal/promptdebug`	11	Partly insufficient. Exact prompt/profile inspection, source precedence, inline execution, credential checks, cancellation, safe classified errors, callback ordering, debug opt-in, static symlink rejection, restrictive modes, atomic replacement, and distinct concurrent captures have focused owners. `AUD-034` and `AUD-035` record incomplete credential redaction and a check/use symlink race.
Generated-text validation	`internal/generatedtext`	12	Partly insufficient. The four current registry definitions dispatch to typed validators with coherent required-field and normalization behavior, and schema bytes are independently copied. `AUD-036` through `AUD-039` record report-independent catalog matching, case-insensitive Go field aliases, unbounded prose/diagnostics, and duplicated or misplaced contract tests.
Render contexts and templates	`internal/generatedtext`, `internal/reporttemplate`	13	Pending
Prompt preflight and prepared inputs	`internal/app`	14	Pending
Single-report publication and preservation	`internal/app`, `internal/fileutil`	15	Pending
Batch partial success and notification	`internal/app`, `internal/adapters/distributor`	16	Pending
Comparison identity and transactional publication	`internal/comparison`	17	Pending
Comparison concurrency and CLI behavior	`internal/app`, `internal/cli`	18	Pending
Hermeticity, execution hygiene, portfolio coverage, and durability	Repository-wide suite	19-21	Pending
Cross-cutting efficiency and maintainability	Graph metrics plus focused tests	22-23	Pending
Documentation and executable-contract coherence	Canonical documents, code, schemas, templates, examples	24	Pending
Dynamic robustness and diagnostic checks	Repository-wide deterministic checks	25	Pending

Findings

AUD-001: Unused persistence helpers remain after the stateless redesign

Stage: 2
Status: candidate
Severity: low
Confidence: high
Category: architecture
Area: internal/promptinput.Save, internal/adapters/weatherapi.SaveBundle, and internal/fileutil.WriteJSONAtomic
Evidence: Graph inbound traces show promptinput.Save has no callers, weatherapi.SaveBundle is called only by TestSaveBundle, and fileutil.WriteJSONAtomic is called only by SaveBundle and its focused test. Repository text search found no documentation or other call sites. Representative generate, batch, comparison, and collection traces do not reach any of these helpers. promptinput.Save and SaveBundle write intermediate prompt input or normalized weather data to arbitrary paths, while normal publication uses fileutil.WriteFileAtomic for selected Markdown and comparison.Publish for selected bundles.
Contract at risk: The architecture policy and ADR 0001 define normal execution as an in-memory stateless transformation whose durable files are operator-selected report outputs, comparison bundles, or explicitly requested secure prompt debugging.
Impact: These unreachable exported functions do not create state during current workflows, but they retain an unsupported persistence surface and low-value tests that can invite accidental reintroduction of intermediate artifacts or require maintenance despite having no product caller.
Recommendation: Remove the two unused domain/adapter save functions, remove WriteJSONAtomic if it then has no production use, and delete or consolidate tests that protect only those retired APIs.
Test implications: TestSaveBundle and TestWriteJSONAtomic protect unused persistence mechanisms; promptinput.Save has no focused test. Preserve tests for WriteFileAtomic, normal report publication, comparison publication, and explicit prompt-debug writes.
Validation: Graph and text searches show no remaining production references to the retired helpers; go test ./... passes; normal output, comparison, and debug-publication tests remain unchanged and pass.
Related findings: none
Remediation reference: pending

AUD-002: Clock windows shift on daylight-saving transition days

Stage: 3
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: internal/timeutil.ClockWindow and internal/forecast.ResolveDayparts
Evidence: ClockWindow obtains the local civil-day start and creates its boundaries with elapsed-duration additions such as day.Start.Add(17 * time.Hour). In America/Chicago, adding 17 elapsed hours to local midnight produces 18:00 on the 2026-03-08 spring transition and 16:00 on the 2026-11-01 fall transition; adding six hours produces 07:00 and 05:00 respectively. Its only production caller is forecast.ResolveDayparts, which uses those boundaries for daily summaries and facts. The focused time test covers only an overnight window in a fixed offset zone, so both transition cases pass unnoticed.
Contract at risk: Configured daypart clocks are local wall-clock boundaries. Civil-day and timezone policy requires those clocks to retain their stated local hour across 23-hour and 25-hour days.
Impact: On daylight-saving transition dates, observations can enter or leave a configured daypart an hour early or late, shifting derived daily summaries and any downstream facts or report content that consume them.
Recommendation: Construct each boundary as a civil date plus local clock in the target location, including explicit handling for 24:00 and overnight windows, rather than adding elapsed hours to midnight.
Test implications: Add table-driven America/Chicago coverage for both spring-forward and fall-back dates, asserting the requested wall-clock start and end and the intended overnight date rollover. Retain the existing half-open period assertions.
Validation: The new regression test fails against the elapsed-addition implementation and passes when transition-day boundaries retain their configured local clocks; focused timeutil and forecast suites pass.
Related findings: none
Remediation reference: pending

AUD-003: Daily run-ID uniqueness lacks a focused contract test

Stage: 3
Status: candidate
Severity: medium
Confidence: high
Category: testing
Area: internal/report.Resolved.runID, validStartDateRunIDDisambiguator, and focused report tests
Evidence: Daily run IDs append the resolved valid-start date to the shared generation timestamp and report ID. This distinguishes multiple Daily reports planned for different dates in one batch, where GeneratedAt is the same. Focused report tests assert that registry identities are nonempty and app tests use nonempty or fixture run IDs, but no test resolves two Daily dates at one clock instant and asserts distinct IDs. Downstream plannedReportsByRunID rejects duplicate IDs before building a batch notification, and Distributor idempotency also consumes the run ID.
Contract at risk: A run ID must identify one resolved report product, while one batch may legitimately contain several Daily products for different valid dates.
Impact: An accidental removal or weakening of the date disambiguator can give distinct Daily products the same identity, causing batch notification construction to fail and creating Distributor idempotency collisions even though the existing focused suite remains green.
Recommendation: Add a focused report test that resolves two Daily dates with the same injected Now, asserts distinct nonempty run IDs, and verifies that each ID carries the corresponding valid-start date. Prefer this relational contract over freezing unrelated timestamp formatting.
Test implications: The regression must fail if the Daily disambiguator is removed while allowing harmless changes to the common run-ID timestamp representation. An app-level assertion may additionally protect the multi-Daily batch consumer, but should not duplicate the report invariant.
Validation: Removing the date disambiguator makes the new focused test fail; with the invariant intact, report and multi-Daily batch tests pass and plannedReportsByRunID receives unique keys.
Related findings: none
Remediation reference: pending

AUD-004: Unsupported missing-source keys are silently accepted

Stage: 4
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: internal/config.Validate, MissingSourceConfig.Sources, and internal/adapters/weatherapi.policyFor
Evidence: The configuration contract lists seven optional source keys and states that hourly forecast data is always required. Validate checks only that each map key is nonblank and its policy is one of error, warn, or none; it never checks the key against the supported set. The Weather API adapter looks up policies by its own literal source names and otherwise uses the default. Its required-hourly path returns an error before consulting the policy. Consequently a typo such as alert: error, an arbitrary key, or an ineffective hourly: none loads successfully. Focused config tests cover an invalid policy value but no unsupported key.
Contract at risk: missing_source.sources accepts only the documented optional source identities, and invalid configuration must fail loading rather than silently changing the effective failure policy.
Impact: An operator can believe a source-specific error, warn, or none rule is active while runtime collection ignores it and applies the default; the mistake is visible only when that source is missing or malformed.
Recommendation: Give internal/config one authoritative supported-source set and reject every other key, including hourly. Keep adapter source names aligned with that owner without introducing a second independently maintained list.
Test implications: Add loaded and constructed configuration cases for every supported key plus representative typo, unknown, blank, and required-hourly keys. Assert behavior through Validate or LoadFile, not private map iteration.
Validation: The new unsupported-key cases fail against the current validator and pass when validation rejects keys that cannot affect optional-source policy; focused config and Weather API policy tests remain green.
Related findings: none
Remediation reference: pending

AUD-005: Single-report notification identities may render blank

Stage: 4
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: validateDistributorNotify, RenderDistributorBundleID, and RenderDistributorIdempotencyKey
Evidence: Enabled single-report notification validation rejects an empty template and unknown variables, and RenderDistributorPipelineID rejects a whitespace-only result. In contrast, the bundle-ID and idempotency-key renderers return whitespace unchanged and validation does not perform a nonblank result check. Batch renderers consistently reject whitespace-only pipeline, bundle, and idempotency identities. The Distributor adapter checks only equality with the empty string, so whitespace values also pass its local request checks. Focused tests cover the single pipeline case and all three batch cases, but omit the two single-report cases.
Contract at risk: Enabled notification requires usable pipeline, bundle, and idempotency identities; configuration validation must reject invalid active templates before report execution.
Impact: A whitespace bundle ID or idempotency key can reach Distributor after report publication, risking rejected uploads or collisions between otherwise distinct report deliveries while configuration preflight reports success.
Recommendation: Apply the same trimmed-nonempty invariant to all three single-report identity renderers and exercise those renderers during active configuration validation.
Test implications: Extend the existing single-report validation table with whitespace-rendered bundle and idempotency identities, and retain the batch table as the parallel contract owner.
Validation: Both new cases fail against the current single-report renderers and pass when all active rendered identities are nonblank; focused config, app notification, and Distributor adapter tests pass.
Related findings: none
Remediation reference: pending

AUD-006: Constructed report overrides depend on inaccessible presence flags

Stage: 4
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: ReportConfig, ReportDistributorConfig, Config.ReportModuleOverrides, and Config.ReportDistributorPathOverrides
Evidence: YAML unmarshalling sets private deterministicModulesSet and pathTemplatesSet flags to distinguish omission from an explicit list. Both public override accessors skip exported DeterministicModules and PathTemplates values unless the corresponding private flag is true. Code outside package config therefore cannot construct an equivalent override: setting a nonempty exported slice in Config.Reports is silently ignored, and Validate skips its contents as well. Tests named for loaded/constructed consistency reside inside package config and manually set the private flags, so they do not exercise the configuration shape available to app callers. Graph traces show the accessors feed app report resolution and single/batch Distributor path rendering.
Contract at risk: Loaded and programmatically constructed configurations with the same exported values should validate and produce the same report module and path overrides.
Impact: Repository callers and tests that construct a config.Config can silently run default modules or Distributor paths instead of their requested values, while invalid constructed overrides can pass validation unused.
Recommendation: Represent presence through an API available to downstream callers, such as constructors/setters or an optional-list representation that preserves omitted versus explicitly empty YAML without private state that exported values cannot establish.
Test implications: Move or add behavior tests from an external config test package or an app boundary so they can use only exported construction APIs; assert both nonempty overrides and explicit-empty rejection.
Validation: The external-boundary test fails with direct exported-field construction today and passes when loaded and constructed forms yield the same overrides and validation result.
Related findings: none
Remediation reference: pending

AUD-007: Failed configuration loads can leave secrets applied

Stage: 4
Status: candidate
Severity: low
Confidence: high
Category: security
Area: internal/config.Load and loadSecrets
Evidence: Load calls loadSecrets before Validate. The secret loader validates and applies directory entries one at a time with os.Setenv, with no preflight of all entries and no restoration of prior environment values. A valid secret is therefore installed even when later configuration validation fails, and an earlier secret remains installed when a later invalid entry, unreadable value, or failed environment assignment aborts the directory load. Existing tests cover successful replacement, line-ending trimming, rejection diagnostics, and omission of secret values from errors, but do not assert failure atomicity.
Contract at risk: A rejected configuration should not partially apply its secret-bearing environment interaction, and repeatable in-process loads should not inherit state from an unsuccessful attempt.
Impact: The normal CLI process exits after a load failure, limiting the operational effect, but embedded runners, repeated actions, and tests can observe or consume credentials from a configuration that was never accepted.
Recommendation: Validate non-secret configuration before secret application, preflight and read the complete secret directory before mutation, and either apply environment changes atomically with rollback or return a scoped lookup rather than mutating process-global state incrementally.
Test implications: Add cases for a valid secret followed by an invalid entry and for valid secrets paired with a later-invalid configuration, asserting that prior set/unset environment state is restored.
Validation: Both failure cases leave the environment exactly as it was before loading; successful overwrite and single-line-ending behavior remain intact.
Related findings: none
Remediation reference: pending

AUD-008: Process interrupts do not cancel active workflows

Stage: 5
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: cmd/weatherreporter.main and CLI cancellation propagation
Evidence: main calls cli.Run with context.Background(). Repository code search found no signal.Notify, signal.NotifyContext, os.Interrupt, or termination-signal handling. Runner.Run correctly forwards the supplied context to generate, batch, and comparison workflows, and focused app tests prove that context cancellation prevents pending publication and joins comparison execution. The production executable never supplies a context that an operator interrupt can cancel, so those paths are reachable only by programmatic callers and tests.
Contract at risk: Documented cancellation failures must reach workflow cancellation checks so pre-publication destinations are preserved and a bounded failed result can be finalized when available.
Impact: SIGINT or SIGTERM terminates the process abruptly instead of canceling in-flight collection, Promptkit work, publication preflight, or notification. The CLI cannot emit its documented canceled result path or allow workflow cleanup/coordination to finish, increasing interruption risk around output and comparison transactions.
Recommendation: Derive the root context from signal.NotifyContext for operator interrupt and termination signals, stop signal delivery on return, and pass that context through the existing CLI boundary. Preserve the current nonzero failure exit and bounded error behavior.
Test implications: Add a narrow executable-boundary test or a testable signal context seam proving that an interrupt cancels the context passed to CLI. Keep detailed destination-preservation and goroutine-join assertions with their existing app/publication owners.
Validation: An interrupt observed during a controlled blocking action cancels its workflow context, returns the expected failed/canceled result when available, and leaves the existing destination intact; ordinary help, version, and successful exits are unchanged.
Related findings: AUD-010
Remediation reference: pending

AUD-009: Generate validates report dates after constructing its executor

Stage: 5
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: internal/cli.Runner.resolveGenerateAction
Evidence: Generate validates the command name and syntactic flags, then loads configuration and constructs the Promptkit executor before checking that Daily has --date or parsing a supplied Daily/Today date. Executor construction can open and parse configured profile files/directories and can fail first. The equivalent comparison resolver validates profile selection before configuration and performs report-date checks before constructing its one executor. Focused comparison tests assert that input failures construct no executor, but generate has no corresponding test. The production generate daily diagnostic confirms the missing-date failure is pre-result, but source tracing shows the executor has already been constructed.
Contract at risk: Basic command input should be rejected before constructing an external-dependency adapter or performing work unrelated to the invalid request; pre-run errors should identify the user's actionable input failure.
Impact: A missing or malformed report date can instead surface a profile source/configuration error, needlessly reads configured Promptkit sources, and follows secret loading from AUD-007 even though the report request can never execute.
Recommendation: After flag parsing, reject a missing Daily date immediately; then load configuration for the effective timezone, parse/default the date, resolve paths, and construct the executor only after all request-local validation succeeds.
Test implications: Add generate input-failure cases with an injected executor factory and assert zero factory/application calls and no stdout/stderr for a missing Daily date, malformed Daily/Today date, unsupported flag, and unexpected argument. Avoid duplicating timeutil parser cases.
Validation: Every generate input failure returns its input diagnostic without constructing an executor or emitting a partial summary; valid requests still construct exactly one executor.
Related findings: AUD-007, AUD-010
Remediation reference: pending

AUD-010: Assembled non-comparison CLI result paths lack durable tests

Stage: 5
Status: candidate
Severity: medium
Confidence: high
Category: testing
Area: internal/cli.Runner.Run, generate/run command tests, and cmd/weatherreporter
Evidence: The CLI suite directly tests generate summary field copying and shared output helpers, but has no assembled Runner.Run generate success, result-bearing failure, quiet failure, or pre-result failure test. Generate calls app.GenerateDetailed directly, unlike the injectable batch and comparison functions, which makes its user-visible wiring difficult to test. Batch has one assembled notification-failure case but no representative ordinary success, report partial failure, quiet failure, or returned-error mapping case. Comparison has comprehensive parser, construction, success, partial failure, cleanup failure, quiet, and pre-execution tests. The command package has no test for executable exit or signal behavior.
Contract at risk: Generate and run must translate result presence, action status, quiet mode, stdout JSON, batch stderr lines, returned errors, and the executable's success/failure exit consistently with the CLI reference.
Impact: A change can suppress a required failed summary, emit routine output in quiet mode, return success for a failed result, write to the wrong stream, or construct dependencies for invalid input without a focused CLI test failing, even while summary-helper and lower app tests remain green.
Recommendation: Add the smallest generate application injection seam symmetrical with batch/comparison, then cover one success, one result-bearing failure, quiet failure, and pre-result failure. Add only representative batch success/report-failure cases and one executable exit/cancellation check; leave workflow details with app tests.
Test implications: Prefer structured JSON/status/error assertions and typed errors over complete output snapshots or private call choreography. These tests should own CLI translation, not repeat publication, collection, prompt, or notification mechanics.
Validation: Mutations to result/error branching, quiet gating, stream selection, or failure return status break a focused CLI test, while internal app refactors that preserve request/result contracts require no CLI edits.
Related findings: AUD-008, AUD-009
Remediation reference: pending

AUD-011: Unsupported Weather API URL schemes fail only at transport

Stage: 6
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: internal/config.Validate and internal/adapters/weatherapi.New
Evidence: Both boundaries accept any parsed absolute URL with a scheme and host. The adapter always constructs an http.Request and executes it with http.Client, so a configured URL such as ftp://weather.example.test passes configuration and adapter construction but fails during warmup with an unsupported-protocol transport error. The integration contract defines an HTTP request boundary, and focused configuration and adapter tests cover malformed or missing URLs but no unsupported absolute scheme.
Contract at risk: A syntactically valid configuration must select a transport the Weather API adapter can execute, and intrinsic endpoint incompatibility should fail validation rather than an attempted collection.
Impact: An operator can pass configuration validation and Promptkit preflight only to receive a runtime weather-fetch failure for a base URL that can never work. This obscures an actionable configuration defect as external availability and performs avoidable setup before failure.
Recommendation: Define http and https as the supported Weather API schemes, document that bound in the configuration and integration owners, and reject every other scheme during config validation and defensively in adapter construction.
Test implications: Add relational config and adapter cases that accept local HTTP and HTTPS shapes and reject a representative unsupported absolute URL without making a request. Do not duplicate generic URL-parser cases.
Validation: Unsupported schemes fail before Weather API or Promptkit work; ordinary HTTP test servers and configured HTTPS URLs remain accepted.
Related findings: none
Remediation reference: pending

AUD-012: Weather API failures expose upstream response bodies

Stage: 6
Status: candidate
Severity: medium
Confidence: high
Category: security
Area: internal/adapters/weatherapi.Client.warmupOnce and fetchHTTPOnce
Evidence: Both non-2xx branches interpolate the complete body read by their 10 MiB reader into the returned error. That error is wrapped without redaction by fetchHTTP, FetchBundle, and collect.Run, then reaches the application/CLI error path. Focused tests require endpoint and status context but neither require response text nor prove that marker secrets or large provider diagnostics are absent. The integration contract promises endpoint context; it does not make arbitrary upstream bodies part of the diagnostic contract.
Contract at risk: Normal errors and summaries must remain bounded and must not expose provider response detail, credentials echoed by an intermediary, internal infrastructure diagnostics, or large HTML/error payloads.
Impact: A failing or compromised service can place up to 10 MiB of arbitrary text into normal stderr and wrapped action errors. Besides disclosure, this can overwhelm machine-readable output consumers and make the actionable endpoint/status diagnostic difficult to use.
Recommendation: Return the relative endpoint, status code, and a stable classification only. If response text is operationally necessary, admit a small sanitized allowlisted excerpt or capture it only through an explicit secure diagnostic mechanism.
Test implications: Serve non-2xx bodies containing a unique secret marker and a large payload; assert that neither appears in the adapter/collection error while endpoint, status, retry identity, and cancellation remain inspectable.
Validation: Normal failure output is bounded and marker-free for warmup and source requests, with existing actionable and retry tests still passing.
Related findings: AUD-013
Remediation reference: pending

AUD-013: The Weather API response limit silently truncates bodies

Stage: 6
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: internal/adapters/weatherapi.Client.warmupOnce and fetchHTTPOnce
Evidence: Both readers call io.ReadAll(io.LimitReader(resp.Body, 10<<20)) and never determine whether more bytes remain. Most oversized JSON is incidentally rejected as truncated syntax, but a complete JSON envelope followed by enough whitespace or later invalid bytes can be accepted from the first 10 MiB while the remainder is ignored. Warmup accepts every 2xx prefix regardless. No focused test defines behavior at, below, or above the nominal limit.
Contract at risk: The documented per-response input bound must distinguish a complete response within the limit from an oversized response; provenance hashes and decoding must describe the complete accepted source payload.
Impact: A buggy or hostile service can make Weatherreporter accept a partial response, hash only its prefix, or treat an oversized warmup as healthy. Ordinary oversized products usually fail with a misleading JSON decode error rather than an actionable limit error.
Recommendation: Give the transport one shared bounded-body reader that reads at most the maximum plus one byte, rejects excess input explicitly, and is used by both warmup and source attempts. Keep the configured timeout and body closure ownership unchanged.
Test implications: Exercise one response at the limit and one over it, including a valid JSON prefix with ignored trailing content; assert a stable size failure and no source decoding or retry for a non-transient size error.
Validation: No over-limit warmup or source response is accepted, while a complete at-limit response remains readable and response bodies always close.
Related findings: AUD-012
Remediation reference: pending

AUD-014: Required hourly periods can lack usable time bounds

Stage: 6
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: internal/adapters/weatherapi.bundleBuilder.fetchHourly and internal/weatherdata.ForecastRun
Evidence: Required hourly validation rejects a missing/null payload, a JSON type error, and a zero-length periods slice. Go decoding leaves absent issuedAt, startTime, and endTime fields as zero time.Time values, so {"data":{"periods":[{}]}} passes collection with one hourly period. The adapter also does not reject a period whose end is not after its start. Downstream period selection depends on those bounds, and the focused required hourly test covers only explicit null rather than structurally unusable periods.
Contract at risk: Hourly is the required normalized forecast product; a present array must contain usable forecast periods rather than merely one decodable object.
Impact: Collection can report success and provenance for an hourly product that cannot contribute to any report period. Later derivation may present an empty or incomplete forecast as a successful collection instead of the required-source failure.
Recommendation: Validate the smallest required hourly invariant at the normalization boundary: a nonzero issue time if contractually required and, for every period, nonzero bounds with endTime after startTime. Keep meteorological selection and overlap policy in Stage 7 owners.
Test implications: Add table-driven adapter cases for missing bounds, zero or reversed duration, and one valid period. Assert direct required-source failure without duplicating downstream forecast selection tests.
Validation: Every accepted required hourly period has a usable half-open time range, and existing valid fixtures still normalize unchanged.
Related findings: none
Remediation reference: pending

AUD-015: Weather API warmup retries permanent HTTP failures

Stage: 6
Status: candidate
Severity: low
Confidence: high
Category: correctness
Area: internal/adapters/weatherapi.Client.warmup and warmupOnce
Evidence: Source fetching retries only transport/read failures and the documented 408, 429, 500, 502, 503, and 504 statuses. Warmup uses a separate attempt implementation and retries every error until its budget is exhausted, including permanent 400, 401, 403, and 404 responses. Focused warmup tests cover successful retry of 502 and exhausted 502, while the non-retryable status test covers only a source request.
Contract at risk: The Weather API retry policy distinguishes transient failures from permanent request/status failures consistently across HTTP attempts.
Impact: Permanent warmup failures cause redundant requests and delay an actionable error by the full retry schedule. The small default budget bounds the effect, so this is primarily avoidable latency and upstream load.
Recommendation: Reuse the shared transport attempt classification for warmup while retaining its distinct success rule that a readable 2xx body need not decode as a source envelope.
Test implications: Add a warmup 404 case that makes one request, retain the 502 retry case, and assert cancellation interrupts its retry delay. Keep source decoding and optional-source policy tests separate.
Validation: Warmup retries only the documented transient classes and fails permanent statuses immediately with endpoint/status context.
Related findings: none
Remediation reference: pending

AUD-016: Metric fallback values lose their unit during daypart derivation

Stage: 7
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: internal/forecast.SummarizeDaypart, numericIndicators, and unitless Range/TimedValue summary fields
Evidence: Normalized forecast periods keep temperatures in explicit Fahrenheit/Celsius fields and winds in explicit mph/km/h fields. SummarizeDaypart selects the first populated temperature or wind field and stores the raw number in a summary field with no unit. numericIndicators likewise selects mph before km/h but compares either result to the mph thresholds of 35 for gusts and 25 for sustained wind. Metric mode is an accepted runtime setting, and focused derivation fixtures populate only Fahrenheit and mph. Consequently, a metric-only gust of 35 km/h is marked hazardous even though it is about 22 mph, while metric temperature and wind summary values are indistinguishable from US customary values to immediate facts consumers.
Contract at risk: Derivation must preserve or normalize measurement units so equivalent meteorological inputs produce equivalent summaries and hazard classifications under every supported units setting.
Impact: Metric reports can exaggerate wind hazards and carry Celsius or km/h numbers into downstream fields that consumers interpret as Fahrenheit or mph. The defect can materially change planning facts and generated report content.
Recommendation: Give derived ranges and timed values an explicit unit, or convert metric fallbacks into one documented canonical unit before storing or comparing them. Apply thresholds only in their declared unit and avoid silently preferring one of two populated representations unless their equivalence is validated.
Test implications: Add paired US/metric cases for temperature, apparent temperature, wind speed, and gust. Assert equivalent canonical summaries and indicators at values immediately below, at, and above the thresholds, including periods with both unit fields populated.
Validation: Equivalent US and metric inputs produce the same heat, cold, and wind decisions and unambiguous summary values; all immediate derived-fact consumers retain correct units.
Related findings: none
Remediation reference: pending

AUD-017: Overnight dayparts omit alerts that begin after midnight

Stage: 7
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: internal/forecast.BuildDailySummary and overlapsWithin
Evidence: BuildDailySummary first limits alerts to the civil-day period and then derives each daypart's alerts only from that reduced set. Configured daypart windows may cross midnight, such as 22:00-06:00, and hourly period selection correctly includes the next morning. An alert beginning at 01:00 the next day does not overlap the prior civil day, so it is discarded before the overnight window is evaluated even though it overlaps that window. Existing tests separately protect direct alert overlap and overnight hourly grouping, but do not combine the two through daily-summary construction.
Contract at risk: Each daypart summary must be derived from its complete configured half-open period, including the next-day portion of a wrapping window.
Impact: A report can include next-morning forecast conditions in its overnight daypart while omitting an active alert for exactly those hours, understating overnight risk.
Recommendation: Compute daypart alert overlaps directly from the source alert run and each daypart period. Keep the top-level daily alert list scoped to the civil day so its separate contract does not widen.
Test implications: Add an integration case with an overnight daypart and an alert wholly after midnight. Assert that the alert appears clipped in the daypart, does not appear in the prior day's top-level list, and an alert beginning exactly at the daypart end remains excluded.
Validation: Every wrapping daypart includes all and only alerts overlapping its full period, while daily alert summaries retain civil-day boundaries.
Related findings: AUD-002
Remediation reference: pending

AUD-018: Invalid precipitation percentages flow into derived summaries

Stage: 7
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: internal/forecast.BuildPrecipTiming, SummarizeDaypart, and weatherdata.ForecastPeriod.ProbabilityOfPrecipitationPercent
Evidence: Both derivation paths accept any non-nil probability without enforcing the percentage domain. Values above 100 can become daypart or timing maxima and open precipitation windows, while negative values can become maxima in otherwise sparse input. The Weather API normalization boundary decodes the field but does not range-check it. Focused tests cover zero, ordinary values, and values immediately around the default 40-percent threshold, but not values below zero or above 100.
Contract at risk: A field named and consumed as a percentage must remain within 0 through 100 before meteorological comparisons or presentation.
Impact: Malformed upstream data can produce impossible precipitation facts and misleading timing windows while collection and derivation both report success.
Recommendation: Enforce the numeric domain at the normalization boundary so every consumer receives valid percentages. Define whether a malformed value makes required hourly input fail or is omitted with an explicit warning; derivation should not silently clamp it because that hides source corruption.
Test implications: Add normalization and derivation cases for negative, 100, and above-100 values, plus non-finite values if the wire decoder can produce them. Protect the exact threshold and zero semantics already tested.
Validation: No accepted derived fact contains a probability outside 0-100, and malformed source behavior is deterministic and visible under the chosen source-failure policy.
Related findings: AUD-014
Remediation reference: pending

AUD-019: Ordinary “icy” forecast text does not set the ice indicator

Stage: 7
Status: candidate
Severity: low
Confidence: high
Category: correctness
Area: internal/forecast.indicatorsForText
Evidence: Ice detection checks for the literal substrings ice, freezing, and sleet. The common condition adjective icy contains none of those byte sequences, so a description such as “Icy roads” does not set the ice indicator. Focused tests exercise broader fixture summaries but provide no table of representative positive and negative condition phrases.
Contract at risk: The documented text indicators identify snow, ice, fog, and wind mentions in normalized forecast descriptions.
Impact: Reports can omit an ice hazard indicator for plainly icy conditions. Other text or numerical signals may still reveal the condition, which keeps severity low.
Recommendation: Define a small explicit vocabulary or token-aware matcher for supported condition forms, including icy, rather than relying only on incidental substrings. Keep the vocabulary bounded to avoid false positives.
Test implications: Add table-driven phrases for ice/icy/freezing/sleet, mixed case, punctuation, and nearby negative words; retain separate tests for snow, fog, wind, heat, and cold.
Validation: Representative icy descriptions set the ice indicator without broadening matches to unrelated words.
Related findings: none
Remediation reference: pending

AUD-020: Pointer-shaped AFD options pass validation but fail construction

Stage: 8
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: internal/briefing.ModuleDefinition.ValidateOptions, buildAreaForecastDiscussionModule, and internal/config.normalizeModuleOptions
Evidence: Option validation explicitly accepts either the declared value type or a pointer to it. Configuration normalization returns an already-valid typed value unchanged. The area-forecast-discussion builder, the only in-scope builder that consumes its options, asserts only the non-pointer module.AreaForecastDiscussionOptions type. Therefore &module.AreaForecastDiscussionOptions{...} passes composition and config validation but later fails module construction with an option-type error. The focused pointer acceptance test uses CurrentConditionsOptions, whose builder ignores options, so it does not protect the end-to-end option contract.
Contract at risk: An option shape accepted by registry and configuration validation must be consumable by the corresponding builder without a later type failure.
Impact: A programmatically constructed report configuration can pass preflight and then fail report preparation solely because it uses the registry's documented accepted pointer form. Loaded YAML normally decodes to the value form, limiting the affected path but making the failure surprising.
Recommendation: Choose one canonical builder input shape. Prefer normalizing accepted pointers to the declared value type before storing/building, or reject pointers consistently if they are not part of the intended contract.
Test implications: Exercise the AFD option consumer through composition, constructed-config normalization, and BuildModule with both accepted shapes. Assert identical selected sections, not merely validation success.
Validation: Every option value accepted by ValidateOptions reaches the AFD builder in a usable canonical form, and invalid shapes still fail during preflight.
Related findings: AUD-006
Remediation reference: pending

AUD-021: Empty weather-story data is published as available

Stage: 8
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: internal/briefing.buildWeatherStoryModule and the normalized weatherdata.WeatherStory source boundary
Evidence: Weather-story collection accepts a decoded non-null object without a minimum content invariant. Unlike current conditions, narrative, hourly, and AFD builders, buildWeatherStoryModule performs no empty-value check; any non-nil pointer, including &weatherdata.WeatherStory{}, emits a module with Available: true, blank period labels, and otherwise empty fields. Focused tests cover a populated story and a missing nil source, but not a checked structurally empty object.
Contract at risk: Source-facing module availability must mean that usable source content exists; missing, empty, and available states must not be conflated.
Impact: Prompt and render consumers can be told a weather story is available when there is no title, description, alternate text, image, or valid period, producing misleading or empty report sections.
Recommendation: Define the smallest usable weather-story invariant at the normalization boundary and apply optional-source policy when it is not met. Retain a defensive module-level empty check so programmatic fact inputs cannot assert availability without content.
Test implications: Add a local adapter case for an empty object and a briefing case for an empty normalized story. Protect populated zero-valued booleans/order independently from the content fields used to determine availability.
Validation: Empty or unusable stories follow the declared missing-source policy or are omitted, while a usable story emits Available: true with its structured fields intact.
Related findings: none
Remediation reference: pending

AUD-022: Module snapshots accept unsupported schema versions

Stage: 8
Status: candidate
Severity: low
Confidence: high
Category: compatibility
Area: internal/module.Snapshot.Validate
Evidence: A snapshot declares the exact version weatherreporter.modules.v1, and NewSnapshot always assigns it, but Snapshot.Validate rejects only an empty version. A manually decoded, cloned, or programmatically constructed snapshot labeled with an old or future nonempty version passes this validation and can continue to prompt or render consumers. The prompt-input package's analogous validation requires its exact current version. Module tests assert constructor output and missing structural fields but do not exercise an unsupported version.
Contract at risk: A versioned module envelope must reject versions whose field and value semantics the current consumer does not implement.
Impact: Current production construction uses the right constant, so ordinary reports are unaffected. The exported validation boundary nevertheless gives false compatibility assurance to alternate/test callers and to any future decoded snapshot path.
Recommendation: Require SchemaVersion == SnapshotSchemaVersion during validation and return an error naming the supported version.
Test implications: Add one focused unsupported-version case alongside the current constructor/version and duplicate-output tests.
Validation: Only the current module snapshot schema passes validation; all normal snapshot construction and downstream consumers remain unchanged.
Related findings: none
Remediation reference: pending

AUD-023: Apparent temperature is published as heat index

Stage: 9
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: internal/briefing.derivedDailySummaryValue and DerivedDailySummaryModule.HeatIndexMaxF
Evidence: Daypart derivation aggregates the source's generic ApparentTemperatureF values into DaypartSummary.ApparentTemperature. The daily briefing builder takes the maximum of that range unconditionally and publishes it as heat_index_max_f. There is no heat-indicator, temperature, humidity, or source-field check that establishes the value as a heat index. The ordinary focused test uses a hot apparent value and therefore confirms only the coincidentally valid case; no cold, mild, or wind-chill case exists.
Contract at risk: User-facing derived fields must retain the meteorological meaning of their source values rather than relabel a generic feels-like temperature as a specific heat hazard measurement.
Impact: Cold and ordinary days can carry a purported heat-index maximum that is actually wind chill or another apparent-temperature estimate. Prompt and render consumers can then make a false heat claim from a correctly collected source value.
Recommendation: Preserve the field as apparent temperature with unit-aware naming, or populate a heat-index field only from an explicit heat-index source or a documented, validated derivation under heat-appropriate conditions.
Test implications: Add hot, mild, and below-freezing apparent-temperature cases. Assert that only a semantically established heat index receives that label, while generic apparent temperature remains available under its own identity.
Validation: Cold and mild inputs never emit a heat-index claim; hot inputs retain an accurately named value; focused briefing and downstream schema or render tests pass.
Related findings: AUD-016
Remediation reference: pending

AUD-024: Normalized daypart keys can silently overwrite summaries

Stage: 9
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: buildDerivedDaypartSummariesModule, daypartKey, normalizedKey, and daypart configuration validation
Evidence: The builder stores every derived daypart in a map keyed by a lowercase name whose non-alphanumeric runs become underscores. It assigns without checking whether the key already exists. Configuration requires only a nonblank name and parseable clocks; it does not require unique names or unique normalized names. Consequently duplicate names, or distinct names such as early morning and early-morning, produce the same key and the later summary silently replaces the earlier one. Existing tests exercise ordinary unique default names only.
Contract at risk: Every configured local-time window selected into derived facts must remain represented in the briefing module and prompt package.
Impact: A valid configuration can silently lose a complete daypart's temperature, precipitation, hazard, and alert facts, causing generated reports to reason from an incomplete day.
Recommendation: Define one canonical daypart identity policy and reject duplicate canonical identities during configuration validation. Retain a defensive collision error in the module builder so programmatic facts cannot overwrite data silently.
Test implications: Add exact-duplicate, case-only, punctuation-normalized, and non-colliding Unicode/name cases at configuration and builder boundaries. Assert an explicit error rather than map length alone.
Validation: Every accepted daypart maps to one distinct output entry, and every collision is rejected before prompt construction.
Related findings: AUD-025
Remediation reference: pending

AUD-025: Planning applies configurable daypart identities inconsistently

Stage: 9
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: buildTodayPlanning, buildMorningCommuteOvernightPlanning, and daypartNamed
Evidence: Morning, overnight, afternoon, and evening role lookup uses case-insensitive daypartNamed, while the commute/workday loop excludes only names exactly equal to lowercase overnight or evening. Daypart names are configurable nonblank strings, and neither configuration nor derivation canonicalizes them into semantic roles. A configured Overnight window is therefore used for overnight-watch guidance and also treated as a daytime commute/workday window; renamed windows silently lose the special planning role altogether. Focused planning tests use only lowercase default names.
Contract at risk: Equivalent accepted configuration identities must produce equivalent planning behavior, and display labels must not double as inconsistently compared semantic keys.
Impact: Harmless casing changes can duplicate overnight/evening hazards into workday concerns, while customized labels can replace real readiness or late-day analysis with generic fallback text.
Recommendation: Separate stable semantic daypart roles from display names, or explicitly constrain and canonicalize the names accepted by configuration. Apply that policy once across every planning lookup and exclusion.
Test implications: Exercise default, mixed-case, and renamed configurations through Today, Tomorrow, and Daily planning, asserting which windows feed morning, workday, late-day, and overnight sections.
Validation: Equivalent daypart configurations yield identical planning classification, and unsupported role configurations fail explicitly rather than degrading to fallback prose.
Related findings: AUD-024
Remediation reference: pending

AUD-026: Outdoor-window ranking ignores snow, ice, and fog

Stage: 9
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: scoreOutdoorWindow and Today outdoor planning
Evidence: Outdoor scoring considers precipitation probability, gust speed, alert count, heat, and cold. It does not inspect the already-derived snow, ice, or fog indicators. When one of those indicators occurs without a high precipitation probability, gust, alert, heat, or cold signal, the daypart receives score zero and the reason quiet weather; it can be selected as the best outdoor window. The same planning helper file correctly treats snow and ice as travel concerns and fog as a morning visibility concern, proving the facts are available. Existing outdoor tests cover precipitation, wind, alerts, heat, and cold but no indicator-only winter or fog case.
Contract at risk: Best/worst outdoor guidance and its reasons must account for material weather constraints already present in the selected daypart.
Impact: A snowy, icy, or foggy period can be recommended as the day's best outdoor window and explicitly called quiet, creating misleading planning advice even when upstream classification is correct.
Recommendation: Give each supported outdoor hazard an explicit scoring and reason policy, sharing the indicator vocabulary with planning notes where appropriate. Document tie behavior and avoid implying safety merely from a zero score.
Test implications: Add isolated snow, ice, and fog cases plus mixed hazards and deterministic ties. Assert both ranking and user-facing reasons.
Validation: None of the supported hazard-only periods is described as quiet, and best/worst selection reflects the documented relative policy.
Related findings: AUD-019
Remediation reference: pending

AUD-027: Subzero temperatures are rendered as positive zero-degree bands

Stage: 9
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: temperatureBandPhrase, temperatureBandIndex, and derived daypart temperature trend prose
Evidence: Both helpers compute a decade with Go integer division toward zero. Values from -9 through -1 therefore receive decade 0; the absolute remainder then produces phrases such as mid 0s or upper 0s, which denote positive temperatures. The same band index can also distort trend ordering around zero. Focused phrase tests cover only positive values in the upper 60s through lower 80s, so realistic cold-weather values are unprotected.
Contract at risk: Temperature phrases and trend summaries must preserve the sign and ordering of the underlying Fahrenheit values.
Impact: A dangerous below-zero forecast can be understated by roughly ten degrees and described on the wrong side of zero in prompt-facing daypart summaries.
Recommendation: Define explicit signed temperature-band semantics, including conventional below zero wording and monotonic band ordering across zero, rather than applying positive-decade arithmetic to negative values.
Test implications: Add table-driven values on both sides of every zero-area boundary, including -11, -10, -9, -5, -1, 0, 1, and 9, plus rising/falling trends that cross zero.
Validation: Every negative input produces unambiguously below-zero wording, and band indices remain monotonic from colder to warmer values.
Related findings: AUD-016
Remediation reference: pending

AUD-028: Embedded official SPC category descriptions have drifted

Stage: 9
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: assets/spc_convective_outlook_definitions.json and spcOutlookBackgroundDefinition
Evidence: The embedded asset labels one field official_description but carries no source URL, source date, or revision metadata. The current NOAA Storm Prediction Center outlook reference, updated March 3, 2026, defines Thunderstorms as an area with a 10% or higher thunderstorm probability and describes Marginal through High using current organization, coverage, and intensity language. Multiple embedded strings differ materially, including Thunderstorms as only No severe thunderstorms expected and Slight as isolated intense storms that are short-lived or not widespread. Tests lock the key set and nonblank grammar but do not compare externally owned meaning or provenance. The CIG vocabulary and conditional-versus-probability warning otherwise align with the current NOAA explanation.
Contract at risk: Content presented as an official external definition must identify and track its authoritative source closely enough to avoid misrepresenting current risk terminology.
Impact: Every matching SPC outlook can carry stale or inaccurately attributed background text into prompts and reports, where users may treat it as NOAA's current official description.
Recommendation: Refresh the categorical descriptions from the current SPC reference, record source URL and revision date beside the asset, and define a periodic review/update owner. If repository prose is intentionally interpretive, rename the field so it is not represented as verbatim official guidance.
Test implications: Retain schema/key/lookup tests, add required provenance, and protect stable domain identifiers rather than freezing unsourced prose. A maintainer review should compare externally owned wording at each update.
Validation: Every official_description is traceable to the recorded authoritative revision, and repository-authored summaries are labeled as such; asset and briefing tests pass.
Related findings: none
Remediation reference: pending

AUD-029: Raw source warnings cross the curated prompt boundary

Stage: 10
Status: candidate
Severity: low
Confidence: high
Category: security
Area: internal/promptinput.Metadata, promptinput.Package.SourceWarnings, and weatherdata.SourceWarning.Endpoint
Evidence: promptinput.Build copies the complete normalized []weatherdata.SourceWarning into the top-level prompt package, and YAML serialization includes each warning's endpoint. The Weather API adapter populates that field with the source's fixed relative transport path whenever an optional source is missing or malformed. In contrast, the briefing metadata module intentionally projects warnings into a prompt-safe type without endpoint or provenance fields, and its test asserts those omissions. No prompt-input test asserts that raw weather-domain fields or transport paths are absent.
Contract at risk: Only curated prompt-facing values may cross the model boundary; raw weather-domain and transport/provenance fields must not be serialized merely because they are present on an upstream type.
Impact: An optional-source failure sends an internal relative transport path to Promptkit and the selected model provider and duplicates a safer warning summary already in the briefing. Current adapter paths contain no host, query, or credentials, limiting present disclosure, but future fields added to the raw shared type would serialize without a prompt-boundary review.
Recommendation: Replace the top-level raw warning field with a prompt-owned safe projection, or remove it in favor of the metadata-module summary. Admit only reviewed source, code, severity, bounded safe message, and completeness fields; never endpoint, query, hash, or response detail.
Test implications: Build and marshal a package from a warning with a unique endpoint marker, then assert the marker is absent while intended safe warning facts remain. Keep the assertion at the serialized provider-boundary owner.
Validation: The exact bytes submitted for prompt execution contain no raw transport/provenance fields; ordinary warning meaning and existing deterministic YAML tests remain intact.
Related findings: none
Remediation reference: pending

AUD-030: The shared prompt instructs nonexistent briefing paths

Stage: 10
Status: candidate
Severity: high
Confidence: high
Category: correctness
Area: internal/promptassets/assets/prompts/common/data_package.user.md and internal/promptinput.BriefingStanzas
Evidence: The shared user prompt directs every report prompt to read briefing.derived_daily_summary, briefing.derived_daypart_summaries, briefing.precip_timing, and briefing.outdoor_windows. The deterministic serializer places all four under briefing.derived_summaries.<stanza>. It also directs alert relevance checks to briefing.metadata.alerts, but the prompt-facing metadata module has no alerts field; relevant counts live in briefing.applicable_risk_products.alert_digest. Asset tests verify prompt, profile, input-schema, and output-schema identities and successfully inspect the real Promptkit definitions, but do not relate prose field references to a representative serialized package.
Contract at risk: Embedded instructions and the exact curated input schema must evolve as one provider-facing contract.
Impact: All four normal report prompts can overlook their primary derived summaries or search the wrong alert location, pushing the model toward raw data, unsupported inference, or false statements about alert relevance.
Recommendation: Update the common prompt to name the actual categorized paths and define one maintainable contract manifest or representative serialized fixture from which semantic path assertions can be made. Avoid a brittle whole-prose snapshot.
Test implications: Inspect all embedded report prompts and assert the shared instruction references paths present in a representative real promptinput.MarshalYAML output, including derived and alert examples.
Validation: Every named input path in the shared instruction resolves in the current serialized package and a category move or prompt-path regression fails one focused compatibility test.
Related findings: none
Remediation reference: pending

AUD-031: The shared prompt overstates SPC product locality

Stage: 10
Status: candidate
Severity: high
Confidence: high
Category: correctness
Area: internal/promptassets/assets/prompts/common/data_package.user.md, briefing.buildSPCConvectiveOutlooks, and briefing.buildSPCConvectiveDiscussion
Evidence: The shared instruction says all active hazard and risk products have already been filtered or matched to the forecast location and should be treated as locally relevant. The SPC outlook module deliberately preserves all selected overlapping records; only its categorical risk_digest applies ContainsLocation, rank, type, and overlap filters. SPC discussions are regional text selected by qualifying outlook day/type/rank/overlap, not by point containment. Stage 9 retained this distinction as RET-020 and focused builder tests protect it, but the prompt-assets suite does not protect the corresponding instruction semantics.
Contract at risk: Safety-sensitive prompt guidance must distinguish location-matched conclusions from regional context retained for grounded interpretation.
Impact: A model can present a non-containing SPC outlook record or regional discussion as a hazard at the configured point, overstating severe-weather risk despite the curated digest carrying the correct local conclusion.
Recommendation: State explicitly that the alert relevant count and SPC categorical risk digest are location-matched, while individual outlook records and discussions require their containment/geographic limitations to be preserved. Remove the blanket locality claim.
Test implications: Add a focused semantic assertion for the shared instruction and a representative package containing a non-local outlook alongside a location-matched digest. Do not duplicate SPC selection tests.
Validation: The embedded prompt cannot reasonably instruct a consumer to treat regional or non-containing SPC material as point-local, while still requiring locally relevant digest facts to lead the report.
Related findings: AUD-030
Remediation reference: pending

AUD-032: The exported YAML loader accepts malformed package shapes

Stage: 10
Status: candidate
Severity: low
Confidence: high
Category: correctness
Area: internal/promptinput.LoadYAML and Validate
Evidence: Focused temporary probes confirmed that LoadYAML accepts a package with no metadata stanza, ignores a value-map entry absent from briefing order, ignores unknown top-level or report fields, and silently accepts a trailing YAML document. Validate checks the current schema, report identity, nonempty order, ordered-value presence, duplicates, and known category placement, but not metadata presence or an exact order/value bijection. The decoder neither enables KnownFields(true) nor performs a second decode expecting EOF. Inbound graph traces find only test callers for this loader, limiting current runtime impact.
Contract at risk: Loading and validating an exported data package should reject ambiguous, incomplete, or forward-unknown representations rather than normalize them silently.
Impact: Tooling or a future production consumer can accept a package that loses stanzas on remarshal, lacks required provenance, carries unnoticed unsupported fields, or hides a second document, giving a false compatibility signal. The live Build-to-Marshal execution path remains valid.
Recommendation: Require metadata exactly once, enforce an exact order/value bijection, enable strict known-field decoding for structured fields, and reject all content after the first YAML document.
Test implications: Add a compact table for missing metadata, orphan value, unknown root/nested fields, and a second document, retaining the current round-trip, duplicate, misplaced, and old-schema cases.
Validation: Each malformed probe fails with bounded context, one canonical document round-trips deterministically, and no production execution behavior changes.
Related findings: none
Remediation reference: pending

AUD-033: Stanza serialization failures lack a focused contract test

Stage: 10
Status: candidate
Severity: low
Confidence: high
Category: testing
Area: internal/promptinput.BriefingStanzas.MarshalYAML and yamlNode
Evidence: Stanza values are normalized through JSON before YAML, and the implementation wraps conversion failures with the stanza name. Existing tests cover deterministic output, category placement, round trips, uncategorized stanzas, and schema rejection, but none supplies an unserializable value such as a non-finite float to execute this failure branch. Normal registry outputs currently use fixed serializable shapes, so no present default module triggers it.
Contract at risk: A serialization failure must remain contextual and must stop execution before any provider call; this behavior should not depend on incidental library diagnostics.
Impact: A future or changed prompt export can fail without a durable test protecting stanza attribution, making provider-preflight errors harder to diagnose or tempting unsafe fallback serialization. Current default reports are unaffected.
Recommendation: Add one focused prompt-input test using a deliberately unsupported stanza value and assert a non-nil, stanza-attributed error. The application-level no-provider-work consequence belongs to Stage 14.
Test implications: Protect the repository context and error category, not the complete encoding-library message; do not duplicate every unsupported Go value shape.
Validation: The focused test fails if conversion errors lose stanza context or are swallowed, and deterministic successful serialization remains green.
Related findings: none
Remediation reference: pending

AUD-034: Prompt-debug credential redaction misses common aliases and URL forms

Stage: 11
Status: candidate
Severity: medium
Confidence: high
Category: security
Area: internal/promptdebug.safePromptDebugEndpoint, redactPromptDebugParameters, and isPromptDebugSecretKey
Evidence: Debug preparation deliberately persists the resolved provider endpoint and effective extra parameters after key-based redaction. The key normalizer recognizes strings containing credential, secret, password, token, API key, or authorization. A deterministic temporary probe confirmed that common synthetic aliases such as access-key, signature, auth, and cookie retain their marker values in endpoint queries or nested parameters. URL user information and the existing API-key fixture are redacted, but URL path credentials and unrecognized query names are also retained. The probe was removed after reproduction and no sensitive fixture value was recorded.
Contract at risk: Prompt-debug artifacts may contain content-rich execution detail, but their explicit safe mapping and focused tests promise that provider credentials are not persisted.
Impact: An operator profile or backend using an unrecognized credential alias or signed URL can write a live credential into preparation.json. Files are mode 0600 beneath a mode 0700 root, limiting exposure, but the credential becomes durable and subject to backup, retention, or later permission mistakes despite the artifact claiming redaction.
Recommendation: Stop trying to prove arbitrary provider maps and complete URLs safe through a denylist. Persist an allowlisted endpoint projection and allowlisted non-secret execution parameters, or replace all provider-specific extras with names/type summaries. Define how signed paths and queries are omitted rather than expanding an indefinitely incomplete alias list.
Test implications: Add table-driven synthetic markers across URL user info, paths, common query aliases, case/separator variants, and nested maps/lists; assert that no marker reaches serialized debug bytes while reviewed ordinary parameters remain useful. Do not use real credential-like fixture values.
Validation: Every supported debug projection is allowlisted, adversarial marker tests find no value leak, and normal summaries remain content-free.
Related findings: none
Remediation reference: pending

AUD-035: Prompt-debug symlink checks can be raced before writes

Stage: 11
Status: candidate
Severity: medium
Confidence: high
Category: security
Area: internal/promptdebug.ensureSecureDirectory, runDirectory, and writeSecureJSON
Evidence: Directory validation walks path strings with os.Lstat and rejects every symlink visible at that moment. runDirectory then joins and creates paths by name, and writeSecureJSON later creates a temporary file and renames it through the same pathname. No directory handle pins the validated root or descendants, so a process able to replace a component in a writable ancestor can swap it for a symlink after validation and before Mkdir, CreateTemp, or Rename. Static root/component symlink tests and concurrent missing-ancestor tests pass, but they cannot protect this check/use window.
Contract at risk: Sensitive debug artifacts must remain beneath the explicitly authorized root, and symlink rejection must hold at the file operation rather than only during an earlier observation.
Impact: Under an explicitly enabled debug run and a replaceable ancestor, a local filesystem attacker can race sensitive rendered prompts or model output into a directory outside the authorized root. Restrictive final modes do not restore path containment after redirection.
Recommendation: Anchor traversal and creation to opened directory handles and use no-follow, directory-only operations for every component and final replacement, with platform-specific handling where necessary. Alternatively require and document a pre-existing trusted root while still pinning it for each write; string containment and repeated Lstat are not sufficient.
Test implications: Add a deterministic filesystem seam or supported-platform race harness that replaces a component between validation and creation and proves no artifact appears outside the root. Retain the cheaper static symlink, mode, collision, and concurrent-distinct-run cases.
Validation: Debug creation and atomic replacement remain relative to the originally validated root handle across component swaps; attempted redirection fails closed without an external file or partial target.
Related findings: none
Remediation reference: pending

AUD-036: The generated-text catalog accepts a known pair for the wrong report

Stage: 12
Status: candidate
Severity: medium
Confidence: high
Category: correctness
Area: internal/generatedtext.LookupDefinition and the generated-text catalog
Evidence: Catalog entries contain only schema ID, template ID, validator, and render-context builder. LookupDefinition accepts the first matching schema/template pair and copies the caller's report ID into the handler without checking that the pair belongs to that report. A temporary probe changed a copied Daily definition to the known hourly/hourly pair; lookup returned an Hourly handler with no error. The current registry loop test compares handler IDs with the same definition it supplied, and the report registry test requires only nonempty schema/template IDs, so neither test detects a coherent but wrong known pair.
Contract at risk: Each generated-text report definition must resolve to its one report-specific schema, validator, template, and context builder before provider work begins; the separate Daily, Today, Tomorrow, and Hourly value types preserve that identity even where fields currently match.
Impact: A registry or constructed-definition regression can route a report through another report's output contract. Depending on the selected pair it can fail only after provider execution during context assembly, or render a semantically wrong report if the downstream inputs remain structurally compatible.
Recommendation: Include report.ID in every catalog entry and require the exact report/schema/template triple. Keep unknown schema, unknown template, known-but-mismatched pair, and wrong-report diagnostics distinct and bounded.
Test implications: Assert the exact four report-to-pair mappings from an independent expectation table, and reject every known pair when attached to a different report. Avoid deriving the expected pair from the definition under test.
Validation: Every current definition resolves once, and swapping any two known pairs fails during lookup before prompt inspection or provider work.
Related findings: none
Remediation reference: pending

AUD-037: Typed decoding accepts property names rejected by the schema

Stage: 12
Status: candidate
Severity: low
Confidence: high
Category: correctness
Area: internal/generatedtext.decodeGeneratedText and the four generated- text schemas
Evidence: The schemas require the exact lowercase names summary, forecast_discussion, and precipitation_timing while rejecting additional properties. Go's encoding/json matches tagged struct fields without regard to ASCII case. A temporary probe showed that Hourly validation accepts Summary and Forecast_Discussion, then normalizes them to the canonical lowercase names. A real offline Promptkit execution against the embedded schema classified the same response as failed. The exact-name raw-map check happens only for precipitation_timing, leaving the other two fields inconsistent.
Contract at risk: The schema validator and repository-owned typed validator should accept the same property vocabulary, and typed decoding is documented as rejecting unknown fields without a second JSON Schema engine.
Impact: The normal Promptkit path currently rejects these aliases first, but direct handler callers or another conforming executor that reports completed validation can accept output the canonical schema forbids. This weakens the typed validator as an independent boundary and makes behavior depend on the executor implementation.
Recommendation: Inspect top-level raw object keys with exact matching before struct decoding, rejecting case variants, duplicates, missing names, and additions under one explicit policy. Preserve typed decoding for field shapes and semantic normalization.
Test implications: Add one shared exact-key contract across all four public validators and an embedded-schema integration case proving the two layers agree. Do not repeat every casing variant in each report-specific suite.
Validation: A corpus of canonical, missing, added, case-varied, duplicate, null, and wrong-type fields produces compatible schema and Go decisions.
Related findings: none
Remediation reference: pending

AUD-038: Generated prose and decoder diagnostics have no size boundary

Stage: 12
Status: candidate
Severity: medium
Confidence: high
Category: reliability
Area: the generated-text schemas, decodeGeneratedText, day-style arrays, and application propagation of validation errors
Evidence: None of the four schemas declares string-length, array-item, or total-output bounds, and the Go validators impose none before decoding, trimming, filtering, and normalizing. Embedded profiles intentionally omit output-token limits. Temporary offline probes showed both Promptkit schema validation and ValidateHourly accepting and copying a synthetic response with a two-MiB summary. Another probe used a 64-KiB synthetic unknown-field name; encoding/json copied the complete name into a 65,603-byte error. profileExecutionError and generatedReportError wrap validator text verbatim, so an executor that reaches this independent layer can carry that content into ordinary errors. All probes were removed.
Contract at risk: Provider output crosses a bounded, content-safe validation boundary before normalization and rendering; ordinary errors must exclude response-body content and remain safe to summarize or log.
Impact: A provider, fake, or future executor can force repeated large allocations in validation/normalization and produce an unexpectedly large Markdown artifact from schema-valid prose. Malformed field names can also turn provider-controlled response text into normal diagnostics. Provider context limits and current Promptkit rejection of unknown fields reduce but do not define the repository's accepted size or independent error contract.
Recommendation: Define reviewed total raw-output, per-string, and day-style paragraph-count/aggregate bounds; express compatible bounds in JSON Schema and enforce the total before decoding. Translate decoder failures into bounded categories that identify canonical fields without echoing arbitrary keys or raw content.
Test implications: Exercise exact boundary and one-over cases for total bytes, string lengths, paragraph count/aggregate size, and oversized unknown names with synthetic markers. Assert normalized bytes and every ordinary error remain bounded without duplicating all cases per day-style report.
Validation: Schema and Go limits agree, excessive output fails before normalization/rendering, and no malformed provider value can make normal error text exceed the documented diagnostic bound.
Related findings: none
Remediation reference: pending

AUD-039: Generated-text contract tests duplicate policy across owners

Stage: 12
Status: candidate
Severity: low
Confidence: high
Category: testing
Area: internal/generatedtext/{daily,today,tomorrow,day_style}_test.go and schema assertions in internal/reporttemplate/reporttemplate_test.go
Evidence: Daily, Today, and Tomorrow each carry nearly line-for-line copies of normalization and malformed-input tables, while the shared day-style suite repeats summary, discussion, normalization, empty timing, missing timing, unknown-field, and retired-field behavior across the same three validators. Separately, reporttemplate_test.go imports promptassets and repeats four schema-shape assertions, including three duplicated day-style blocks, even though reporttemplate owns Markdown assets and promptassets_test.go already owns the schema inventory, strict-object shape, required fields, identity, and copy isolation.
Contract at risk: Similar public validators should remain independently protected without copying shared semantics, and schema tests should reside with the asset owner rather than an unrelated template package.
Impact: One intentional day-style or schema change requires synchronized edits across several files and packages, creates noisy failures outside the responsible owner, and can still miss cross-layer discrepancies such as AUD-037 because duplicated examples are not an agreement test.
Recommendation: Keep one table-driven shared day-style behavior suite with a thin per-exported-validator identity/type case. Move complete schema-shape ownership to promptassets; keep only a generated-text integration contract that compares schema acceptance with typed validation where their semantics intentionally overlap. Remove schema assertions from reporttemplate.
Test implications: Preserve distinct Hourly behavior and each public report identity while deleting repeated semantic cases. A mechanical refactor of a private day-style helper should not require unrelated test edits.
Validation: The leaner suite still fails for a wrong report dispatch, schema/type disagreement, required-field regression, or normalization change, and report-template tests fail only for template/render behavior.
Related findings: AUD-037
Remediation reference: pending

Retained Decisions

RET-001: Keep the application package as the explicit composition owner

The package import graph, outbound traces from GenerateDetailed, RunBatchDetailed, and compareDetailed, and their focused tests were inspected. internal/app has deliberately broad outbound dependencies because it sequences project-owned domain, collection, execution, publication, and notification contracts; those dependencies do not point back into app. Splitting that fan-out merely to reduce a graph metric would obscure workflow ownership. Reconsider only if a second composition owner emerges or a coherent workflow can move behind a narrower contract without duplicating ordering policy.

RET-002: Keep external dependencies behind repository-owned contracts

Production import and data-flow inspection found Promptkit imports only in internal/adapters/promptkit and Distributor imports only in internal/adapters/distributor. The Promptkit adapter implements promptexec.Executor; Weather API collection returns weatherdata.Bundle; and Distributor results are translated before application and CLI summaries. This explicit translation prevents dependency types and sensitive diagnostics from becoming application contracts. Reconsider only when an upstream type is intentionally adopted as a public repository contract with corresponding architecture and compatibility changes.

RET-003: Keep publication mechanisms separate by artifact contract

Filesystem-write discovery and call traces were inspected for single reports, comparison bundles, and secure prompt debugging. fileutil.WriteFileAtomic owns one-file replacement, comparison.Publish owns guarded transactional directory replacement and recovery, and promptdebug owns secure explicit diagnostic files. Their shared use of temporary paths and rename operations is mechanical similarity, while their authorization, permissions, commit, and recovery semantics differ materially. Reconsider common abstraction only if multiple artifact kinds acquire the same complete transaction contract.

RET-004: Keep collection as a narrow application-facing seam

The app.Collector contract, collect.Run, the Weather API adapter boundary, and focused collection tests were inspected. Although collect.Run is small, it keeps adapter creation and error context out of orchestration and gives app tests a dependency-neutral deterministic seam. Reconsider if collection gains no additional policy and an equally narrow project-owned adapter contract can replace it without leaking transport construction into app.

RET-005: Keep report definitions explicit and independently reviewable

The four registry definitions were compared across stable ID, prompt and version, template and schema, period resolver, modules, output name, Distributor paths, and run-ID policy. Their similar structure is contract data, while meaningful differences include Daily's required date and dynamic output identity, Today's current local day and Morning membership, Tomorrow's next local day and both batch memberships, and Hourly's rolling elapsed period. Explicit definitions make those differences visible and focused tests assert the exact retained registry surface. Reconsider a shared declarative builder only if the registry grows enough that it can reduce maintenance while preserving independent review of every identity field.

RET-006: Keep command and configuration report lookup policies separate

IDForCommandName accepts only the four exact CLI command names, while IDForConfigKey deliberately trims space, folds case, and normalizes hyphens for configuration keys. Tests also reject retired aliases. Combining the two lookups because their successful mappings are similar would risk broadening the CLI contract or narrowing configuration compatibility. Reconsider only if the accepted-input policies intentionally converge or registry metadata can generate both maps without changing either boundary.

RET-007: Keep civil-day and rolling elapsed-time period policies distinct

Daily, Today, and Tomorrow use CivilDay, whose AddDate boundary correctly produces 23-hour and 25-hour local days. Hourly instead adds six elapsed hours to the injected clock, matching its documented rolling-horizon contract. Batch coverage likewise walks the actual hourly instants within each civil day, and focused app tests exercise daylight-saving dates. Unifying these period calculations would conflate calendar and elapsed-time semantics. Reconsider only if a report's product contract changes which kind of time it represents.

RET-008: Keep configured output paths declarative during loading

Configuration preserves a nonblank output.directory exactly as supplied and does not clean, absolutize, inspect, create, expand, or rebase it. App and publication owners later resolve it against the invocation working directory and perform destination-specific preflight. This keeps configuration loading free of working-directory and filesystem lifecycle policy while still rejecting a meaningless whitespace-only setting. Reconsider only if a new configuration contract requires an intrinsic path property that can be checked without assuming an execution destination.

RET-009: Keep inactive optional integrations free of active-field validation

Distributor templates and delivery settings are validated only when notification is enabled, and batch templates only when both Distributor and batch notification are enabled. Likewise, a blank Promptkit local endpoint means the backend is unregistered and its configured default concurrency is dormant; CLI mapping forwards the limit only with an endpoint, while the adapter rejects an active limit without one. This lets complete defaults and examples describe optional integrations without making unused credentials or templates mandatory. Reconsider only if dormant configuration must become an installation-time lint contract distinct from runtime configuration loading.

RET-010: Keep Promptkit profile source precedence in its adapter boundary

Configuration owns mutual exclusion of profile_file and profile_dir, URL and concurrency shape, and the selected profile ID. The Promptkit adapter owns opening configured sources, complete-definition precedence, embedded and built-in fallbacks, and classification of malformed profile errors before collection. Maintained profile tests exercise that boundary offline. Moving profile parsing into config would duplicate dependency-specific behavior and leak Promptkit mechanics. Reconsider only if Weatherreporter adopts a repository-owned profile format independent of Promptkit.

RET-011: Keep command-specific parsers around one shared flag core

The three action parsers use separate flag.FlagSet values so unsupported flags fail at the command that owns them: generate alone accepts --out, run and compare accept --out-dir, compare alone accepts repeated --profile and --replace, and only Daily/Today generate or compare accept --date. addCommonFlags shares only config, units, timezone, and prompt-debug options. This small explicit split keeps the acceptance matrix reviewable without a general command framework. Reconsider if additional actions make the common registration or post-parse checks materially larger or divergent.

RET-012: Keep action summaries distinct and bounded by CLI ownership

Generate, batch, and comparison have different public result contracts, so separate summary types and constructors are preferable to a generic result envelope. Generate copies selected fields and a compact notification result; batch preserves ordered report outcomes and independent notification status; comparison locks its field order and converts top-level failures to bounded safe categories. Pre-result failures emit no JSON, while result-bearing failures emit a failed summary before returning an error, and one shared output gate implements quiet mode. Reconsider common abstraction only if multiple actions acquire the same complete summary and failure semantics.

RET-013: Keep source-specific normalization explicit

The eight source methods share transport and missing-policy helpers but retain visible source semantics: query parameters differ, hourly alone is required, alerts alone treats explicit null as checked empty data, SPC empty arrays are also checked data, and issue/update timestamps come from different payload fields. Collapsing those methods into a generic descriptor would hide the normalization decisions that need independent review. Reconsider a declarative table only if it can express every source's availability, empty-value, timestamp, and validation policy without callbacks that recreate the current methods indirectly.

RET-014: Keep selected forecast periods structurally intact

Hourly, narrative, and daily selection uses half-open overlap and returns the complete normalized source periods in stable chronological order. It does not fabricate clipped forecast periods at the requested boundary; alert overlap is separately clipped because it explicitly represents an intersection. Focused tests protect inclusion of an already-active hourly period at a rolling horizon and exclusion at exact end boundaries. This preserves source identity, values, and timestamps for downstream reasoning. Reconsider only if a consumer requires synthetic boundary-aligned values and that interpolation or clipping policy is made explicit rather than implied by selection.

RET-015: Keep fact projection shallow under immutable workflow ownership

BuildCollected and CollectedFacts.Bundle allocate independent top-level provenance and warning slices but retain pointers to normalized weather products and nested values. Derivation treats those products as immutable, and prepared-report construction later deep-copies complete inputs before handing them to consumers. Deep-copying the full weather bundle at every fact boundary would add repeated allocation without protecting a currently mutable seam. Reconsider if facts begin mutating normalized products, an external consumer can retain and mutate them concurrently, or the fact API promises complete snapshot isolation rather than immutable workflow ownership.

RET-016: Keep module envelopes separate from briefing policy

internal/module owns stable IDs, option and fact vocabulary, outputs, and ordered snapshots without importing report definitions. internal/briefing owns the registry that connects those neutral contracts to report support, fact availability, missing-data policy, builders, and prompt exporters. Configuration validates through that registry and application composition builds through the same one, so policy is not duplicated at the neutral envelope layer. Reconsider only if another independent builder implementation needs the same policy metadata or the neutral package acquires report-specific behavior.

RET-017: Keep rich module values and curated prompt exports distinct

Module snapshots retain rich deterministic values for repository-owned render contexts, while DataPackageValue selects a separately constructed prompt value when the registry declares an exporter. Current conditions and hourly forecast use this to omit lowercase, display-label, and precipitation-mention helpers without weakening template facts; pass-through remains explicit for modules whose complete structured value is intended for the prompt. Focused tests compare both representations and prove prompt values are excluded from snapshot JSON. Reconsider if the rich and prompt schemas converge completely or a generated projection can preserve equally explicit field-level review.

RET-018: Keep checked-empty alert modules distinct from missing sources

The alert digest uses normalized source provenance and alert presence to emit separate checked, missing, active-count, and relevant-count facts. Its registry behavior permits an explicit empty module, so a successful check with no alerts does not disappear like an unavailable optional source. This distinction is useful prompt and template information and has a focused behavioral test. Reconsider only if the normalized source availability model changes or all downstream consumers gain an equivalent status channel.

RET-019: Keep Today planning richer than Daily and Tomorrow planning

Daily and Tomorrow intentionally share one morning, commute/workday, and overnight planning shape, while Today adds outdoor-window guidance and a late-day change watch. The distinction follows the report horizon: Today can act on the remainder of the current day, whereas Daily and Tomorrow retain a compact next-day readiness structure. Builders reuse the common planning helper and focused tests protect both shapes. This is meaningful product variation rather than drift. Reconsider only if report schemas intentionally converge or a new horizon requires the same additional planning sections.

RET-020: Keep SPC outlook records separate from selected briefing digests

The SPC outlook module preserves all selected overlapping outlook records and adds background definitions only for known type/label pairs. Its risk digest then applies a location-specific categorical severity threshold, while the discussion module separately selects discussion days from qualifying categorical outlooks. Focused tests cover type, rank, location, day, overlap, unknown definitions, and checked-empty behavior. Keeping the complete selected record set distinct from narrower editorial digests preserves evidence without forcing every consumer through one filter. Reconsider only if SPC product semantics or the report contract adopts a single shared selection policy.

RET-021: Keep prompt category grouping explicit and serialization normalized

The prompt package owns a small fixed category vocabulary and emits metadata, applicable risk products, derived summaries, narrative products, and raw data in one explicit order while preserving module order inside each category. Stanza values pass through JSON normalization before YAML, preventing Go- and YAML-specific value shapes from becoming an accidental provider contract. The highest scoped marshal complexity operates over those fixed categories and service-sized module lists, so a generic reflective serializer would add policy opacity without a realistic cost benefit. Reconsider if the module catalog becomes large or category metadata can be generated from one reviewed manifest without weakening unknown/misplaced-stanza rejection.

RET-022: Keep neutral prompt execution lifecycle values dependency-owned

promptexec defines only repository-owned inspection and execution requests, completed results, safe categories, validation rejections, and explicit debug values. The interface carries context to both operations; callbacks run before provider execution; validation rejection is a completed result, while operational failure returns no result; errors preserve causes without exposing their text; and mutable returned bytes/maps are copied. Promptkit production types remain adapter-local. This is a coherent narrow seam rather than an anemic duplicate of the dependency API. Reconsider only if a second executor implementation demonstrates a missing neutral semantic; Promptkit-specific cancellation and diagnostic translation remain Stage 11.

RET-023: Keep Promptkit source resolution and prepared handles in the adapter

The adapter supplies embedded prompt/schema/profile filesystems and configured profile sources directly to one Promptkit engine, then maps exact inspections and one-use prepared executions into repository-owned values. It does not reparse Promptkit YAML, merge profile fields, duplicate backend capacity, or expose dependency handles. Focused tests cover complete-source precedence, malformed matching definitions, built-in fallback, exact inline input, callback-before-provider ordering, credential checks, cancellation, and all stable error categories. Promptkit v0.5.0 explicitly documents its engine as concurrency-safe and has its own concurrent prepare/run contract test, while Weatherreporter's race-enabled adapter/app suites pass. Reconsider only if the dependency contract changes or Weatherreporter adopts an independent profile format requiring repository-owned resolution.

RET-024: Keep explicit prompt-debug storage separate from normal publication

The debug writer is disabled without an absolute operator root and otherwise owns versioned per-report/run JSON records, restrictive directory/file modes, validated path segments, atomic same-file replacement, and distinct comparison run directories. Application callbacks make a requested preparation-write failure stop before provider generation, and execution-write failure prevents report publication. These authorization, sensitivity, and failure semantics differ materially from ordinary Markdown and comparison publication, so a generic filesystem writer would obscure the contract. Retain the separate owner while remediating AUD-034 and AUD-035; reconsider shared mechanics only after a common primitive can preserve every artifact's security and transaction boundary.

RET-025: Keep report-specific generated values over shared day-style mechanics

Daily, Today, and Tomorrow currently share the same three fields and one private validation path, but they remain distinct exported value types and catalog handlers. This lets context builders reject a value validated for a different report and leaves each report free to evolve without converting a temporary structural similarity into a public interchangeability promise. The private dayStyleFields projection, trimming, nonblank filtering, and normalization remove mechanical duplication without erasing identity. Retain that split while fixing catalog identity in AUD-036 and consolidating tests under AUD-039; reconsider only if the reports intentionally adopt one shared generated-text contract and migration policy.

RET-026: Keep semantic typed validation after schema validation

Promptkit's embedded JSON Schema validates provider shape, while internal/generatedtext produces repository-owned typed values, trims prose, removes blank day-style paragraphs, requires usable summaries/discussions, and normalizes the result. Those are distinct boundary and domain responsibilities: schema success alone cannot construct the typed render input, and decoding alone should not make execution correctness depend on a particular executor. Retain both layers and make their overlapping vocabulary and limits agree when remediating AUD-037 and AUD-038; do not replace semantic validation with a second general-purpose schema engine.

Open Questions

No Stage 1 open questions or unexplained baseline failures remain.

Stage 2 routed these investigation leads without treating graph metrics or an unusual edge as findings:

internal/config imports internal/briefing to use module definitions while validating report-module options. Stages 4, 8, and 23 should determine whether this remains the smallest single-owner validation path or creates avoidable registry coupling.
The graph identifies internal/cli.Run, internal/app.RunBatchDetailed, and internal/app.compareDetailed as relatively complex orchestration paths. Their ownership and top-level ordering are coherent; Stages 5, 16, 18, 22, and 23 should assess their local behavior and maintainability rather than inferring a finding from metrics.

Stage 3 routed these investigation leads to their assigned later stages:

LoadLocation accepts numeric offsets through 23:59, while the config reference does not state an offset range. Stage 4 should assess the effective configuration contract and validation ownership before judging that bound.
The report-registry document says focused tests cover run IDs and output names, but Stage 3 found no behavioral run-ID assertion and only indirect dynamic output-name coverage. AUD-003 captures the consequential run-ID gap; Stage 24 should reconcile the broader documentation claim with the eventual executable contract.
Prompt, template, schema, and module IDs are internally consistent at the report registry. Stages 8 and 10-13 remain responsible for validating the referenced registries, embedded assets, generated-text schemas, and render compatibility rather than duplicating those audits here.

Stage 4 routed these investigation leads to their assigned later stages:

Configuration accepts any absolute URL scheme with a host, matching the documented term “absolute URL.” Stages 6, 11, and 16 should assess transport scheme support at the Weather API, Promptkit, and Distributor boundaries before narrowing the configuration contract.
weather_api.base_url may be empty in a valid configuration because only collection workflows require it. Stages 5-6 should verify action-specific failure timing and diagnostics rather than making every non-collection configuration require an endpoint.
Report config-key normalization accepts trimmed and case-folded spellings in addition to the documented hyphen/underscore equivalence. Stage 24 should decide whether the canonical reference should describe that compatibility or the executable contract should be narrowed.
Distributor delivery redaction, runtime template consumption, and notification idempotency remain assigned to Stage 16. Stage 4 accounts only for active configuration and safe identity/path rendering before execution.

Stage 5 routed these investigation leads to their assigned later stages:

Generate and batch summaries intentionally carry project-owned app error and warning fields, while comparison applies an additional bounded safe-error translation. Stages 6, 11, and 16 should verify that Weather API, Promptkit, and Distributor producers never place sensitive endpoint, credential, or provider detail in the non-comparison fields before Stage 24 judges the full documented output claim.
Generate and comparison repeat the Daily/Today flag-acceptance and date defaulting policy. They currently agree, and the report registry remains the period owner. Stage 23 should assess whether a shared CLI policy descriptor would reduce drift without moving parsing into the domain registry.
The static help text includes --date in usage but omits it from the Options list and describes --quiet as suppressing successful output even though it suppresses failed action summaries too. docs/internal/cli.md also still says the CLI dispatches only generation and batch actions despite implemented comparison dispatch. Stage 24 should reconcile these documentation/help statements without expanding Stage 5 into the repository-wide documentation audit.
Batch status writes deliberately ignore stderr write failures while JSON encoding errors are returned. Stage 25 should exercise broken-pipe and output writer failures dynamically before deciding whether routine-status I/O must affect the process exit.

Stage 6 routed these investigation leads to their assigned later stages:

facts.BuildCollected and facts.Bundle copy source and warning slices but not nested query maps or warning slices. Prepared-report construction later deep-copies its complete inputs. Stage 7 should judge whether the earlier derivation boundary promises mutation isolation or whether immutable workflow ownership makes the shallow copy intentional.
AlertRun.Raw preserves the complete alert payload in addition to the raw alert items, but graph-augmented use search found no production consumer of the full duplicate. Stage 23 should assess removal with other unused and duplicate internal surfaces; alert-item schema and parsing remain assigned to Stages 7-9.
Source provenance retains the adapter-controlled query parameters in the normalized bundle, while prompt-facing metadata deliberately omits the query map. Stage 10 should confirm that no prompt input or debug artifact widens that boundary, and Stage 24 should judge whether the internal documentation needs an explicit non-secret-query invariant.
The adapter accepts URL user information, base query parameters, and fragments because the current absolute-URL check does not constrain them; endpoint construction drops the fragment and carries base query values into requests/provenance. The current configuration and examples use none of these. Stage 24 should clarify the intended base-URL shape after remediation of AUD-011, rather than Stage 6 inventing undocumented authentication or query behavior.

Stage 7 routed these investigation leads to their assigned later stages:

DifferenceAtLeast, CrossesAtOrAbove, and CrossesBelow are exported forecast helpers with focused tests but no production callers in the graph. Stage 23 should assess removing this unused comparison surface rather than treating locally correct arithmetic as a derivation defect.
The forecast derivation document describes BuildPeriodDailySummaries, but no such symbol or equivalent multi-day constructor exists in the implementation. Current facts intentionally build one civil-day summary for Daily, Today, and Tomorrow. Stage 24 should reconcile the named API and actual one-day report contract.
Planning and derived briefing consumers assign Fahrenheit/mph meaning to the unitless daypart values identified by AUD-016, and hazard wording may amplify the missed text classification in AUD-019. Stage 9 should account for those downstream effects while avoiding duplicate findings for the same derivation causes.

Stage 8 routed these investigation leads to their assigned later stages:

BuildMetadata and its broader Metadata type duplicate part of the metadata module path, but the application retains only a subset for the prompt package and uses the module stanza for briefing content. Stage 23 should assess consolidating this parallel construction without moving prompt package ownership into briefing.
Fact requirement constants, registry declarations, and the two availability switches must evolve together. They currently agree and focused tests cover default compositions, but Stage 23 should assess a definition shape that reduces switch/table drift without hiding missing-data policy.
Current/hourly rich and prompt structs deliberately differ under RET-017, yet their field-by-field copy code is sizeable. Stage 23 should evaluate whether small projection helpers or generated mappings reduce maintenance while preserving reviewable prompt curation.
AFD text, alert descriptions/instructions, weather-story content and URLs, and narrative fields currently use pass-through prompt exports. Stage 10 should verify the complete serialized prompt boundary and intended curation; Stage 8 accounts only for their source-to-module transformations.

Stage 9 routed these investigation leads to their assigned later stages:

The derived and planning modules amplify the unit collapse in AUD-016, the overnight-alert omission in AUD-017, invalid percentages in AUD-018, and incomplete ice classification in AUD-019. Stage 9 did not duplicate those upstream causes; remediation and later end-to-end tests should protect the downstream wording and thresholds as well.
titleWord uppercases the first byte rather than the first rune, and several daypart-oriented helpers repeat display and semantic-name handling. The consequential identity behavior is captured by AUD-024 and AUD-025; Stage 23 should assess Unicode-safe shared formatting and removal of repeated day-style policy without turning display labels into domain identities.
Prompt serialization and rendering of the newly audited fields remain with Stages 10 and 13. Stage 24 should decide where the externally maintained SPC definition source and review date belong in canonical documentation after AUD-028 is remediated.

Stage 10 routed these investigation leads to their assigned later stages:

promptinput.Save and LoadYAML have no production callers, while the prompt-input document describes ordinary atomic saves and focused save coverage that do not exist. AUD-001 and AUD-032 capture the code risks; Stages 23-24 should decide whether to remove the unused API and reconcile the canonical document rather than expanding a dormant persistence workflow.
JSON unmarshalling reconstructs stanza order from map iteration and therefore does not promise deterministic order. There is no exported JSON loader or production consumer, and YAML is the execution format. Stage 23 should assess retiring or explicitly limiting this incidental surface instead of Stage 10 inventing a second ordering contract.
The neutral interface passes context and makes debug detail explicit, but provider cancellation, dependency error translation, and secure prompt-debug publication belong to Stage 11. Application proof that serialization failure prevents provider work belongs to Stage 14 with AUD-033 as its focused package-level prerequisite.

Stage 11 routed these investigation leads to their assigned later stages:

Debug writer construction creates or tightens the explicitly requested root before prompt inspection and collection. This is authorized diagnostic state, not an ordinary-workflow violation, but Stage 24 should make the possibility of an empty root after later preflight failure explicit if operators need that lifecycle detail.
marshalDebugParameters and structured-schema capture discard impossible- under-current-Promptkit JSON marshal errors. Promptkit v0.5.0 constrains those values to JSON-compatible copies, so Stage 11 recorded no defect. Stage 23 should avoid generalizing the adapter around that assumption unless the dependency contract changes.
Application-level inspection ordering, exact prompt/profile consistency, and prepared-input reuse remain Stage 14; comparison scheduling and cancellation aggregation remain Stage 18. Stage 11 accounted for adapter context propagation and Promptkit's concurrent-engine contract without duplicating those orchestration findings.

Stage 12 routed these investigation leads to their assigned later stages:

The application discards the canonical normalized JSON returned beside the typed generated value. This is harmless in the current render path and the package documents the return value, but Stage 23 should decide whether a production consumer justifies retaining that API surface rather than treating non-use alone as a defect.
encoding/json also accepts duplicate object names with last-value wins. The embedded schema validator follows parsed-JSON semantics and no canonical contract currently promises duplicate rejection, so Stage 12 did not invent a uniqueness rule. Stage 25 may include duplicates in its broader adversarial corpus when validating the remediation for AUD-037.
Context construction, template fields, partial execution, and Markdown semantics remain Stage 13. Application proof that catalog and generated-text failures occur before publication remains with Stages 14-18; Stage 12 traced only enough of those callers to establish the raw-output validation boundary.

Stage Log

Stage 1: Establish The Baseline And Audit Ledger

Status: Complete.
Scope reviewed: repository identity, worktree state, Go module and workspace context, graph identity, tracked package/source/test/fixture/asset/document inventory, and required baseline validation.
Exclusions: none beyond the stage boundary; no production code, tests, dependencies, examples, or canonical documents were changed.
Result: the audit is tied to exact commit e7c7262; the expected-baseline difference is explained; every required baseline command passes; and all later stages remain pending.
Findings: none.
Retained decisions: none.
Open questions: none.

Stage 2: Audit Architecture And Dependency Direction

Status: Complete.
Scope reviewed: cmd/weatherreporter, production import boundaries for all 24 Go packages, principal call and data-flow paths, external adapter containment, project-owned interfaces, publication boundaries, filesystem writes, ADR 0001, focused orchestration tests, and the architecture policy.
Exclusions: Detailed report/time, configuration, CLI, weather, domain, module, prompt, rendering, comparison, and notification correctness remains assigned to Stages 3-18. Cross-cutting complexity, deduplication, and full documentation coherence remain assigned to Stages 22-24.

Boundary Accounting

Normative boundary or invariant	Implementation owner and evidence	Disposition
Binary entry and CLI ownership	`cmd/weatherreporter.main` calls `cli.Run`; `internal/cli` owns action parsing, config loading, executor construction, and bounded result output. Graph traces place app calls below action resolution.	Matches policy.
Configuration ownership	`internal/config` owns defaults, YAML loading, normalization, secrets, and validation. CLI loads config and passes effective values down; app does not parse config files.	Matches policy; the config-to-briefing validation edge is routed to Stages 4, 8, and 23.
Application orchestration	`GenerateDetailed`, `RunBatchDetailed`, and `compareDetailed` sequence preflight, collection, preparation, execution, publication, and notification through repository-owned values and interfaces. No lower package imports app.	Matches policy; retained as `RET-001`.
Report and domain ownership	`report`, `timeutil`, `weatherdata`, `forecast`, `facts`, `module`, `briefing`, `promptinput`, `generatedtext`, and `reporttemplate` form one-way deterministic dependencies below app.	Matches policy at package level; local rules remain for Stages 3 and 7-13.
Prompt execution boundary	`promptexec.Executor` is dependency-neutral. CLI constructs the Promptkit adapter once per action, app consumes only `promptexec` requests/results, and the prepared-report data flow supplies curated serialized module packages.	Matches policy; retained as `RET-002`.
Weather API boundary	App calls its `Collector` interface; the production implementation delegates through `collect.Run` to `adapters/weatherapi.FetchBundle`, which returns normalized `weatherdata.Bundle`. Production HTTP imports occur only in external adapters.	Matches policy; retained as `RET-004`.
Distributor boundary	App owns notification timing and repository request/result types; `distributorNotifier` translates them to adapter-local types and the adapter alone imports the Distributor dependency. Comparison exposes no notifier path.	Matches policy.
Prompt preflight and curated inputs	Generate inspects the exact prompt/profile before `collectWeather`; batch inspects all candidates before its one collection; comparison inspects prompt and all profiles before collection, then calls `prepareReport` once. Data-flow traces reach `promptinput.Build` and `MarshalYAML`, not raw bundle serialization into Promptkit.	Matches policy at workflow level; detailed checks remain for Stages 10, 11, 14, and 18.
Single output and notification order	`publishPromptReport` checks context, calls `fileutil.WriteFileAtomic`, records the path, and only then calls `notifyReport`. Focused tests cover pre-publication preservation and notification ordering.	Matches policy; publication split retained as `RET-003`.
Batch output and notification order	`RunBatchDetailed` validates every planned path before sequential execution, suppresses item notification, continues across item failures, and calls `notifyBatch` only after the loop. Focused tests cover preflight, partial failure, and notification-after-publication.	Matches policy at workflow level; detailed review remains for Stage 16.
Comparison publication	App preflights before external work and again before publication. `internal/comparison` owns bundle validation, guarded replacement, staging, commit, restoration, and cleanup results. The comparison request has no notifier and the trace does not reach Distributor.	Matches policy at workflow level; detailed review remains for Stages 17-18.
Stateless execution	Normal traces retain preparation and execution values in memory. Production filesystem writes are limited to selected Markdown publication, selected comparison bundles, explicit prompt-debug capture, and the unreachable helpers in `AUD-001`; no cache, workspace, history, receipt, or resume owner appears in the package graph.	Matches normal-runtime policy; `AUD-001` records the unused persistence surface.
Dependency cycles and direction	The compiler-derived direct-import inventory is acyclic. Entry packages point inward, adapters do not import app/CLI, domain packages do not import orchestration, and no external dependency type appears outside its production adapter.	Matches policy.

Commands And Evidence

Refreshed graph project home-eric-Workspace-weatherreporter in moderate mode. The graph's branch identity remains production baseline e7c7262; Stage 1's intervening commit changes only this excluded audit document.
Used graph architecture views for structure, dependencies, entry points, hotspots, boundaries, layers, and clusters; queried the graph schema and direct import edges.
Used graph search, snippets, inbound/outbound call traces, and data-flow traces for main, cli.Run, GenerateDetailed, RunBatchDetailed, compareDetailed, prepareReport, executePreparedProfile, collect.Run, all three external adapters, publishPromptReport, comparison.PlanDestination, comparison.Publish, and Distributor notification.
Used compiler-derived go list direct imports to separate production edges from test-only graph edges and confirm the build has no import cycle.
Used graph-augmented code search to inventory external dependency imports, HTTP ownership, and production filesystem writes. A bounded text search confirmed the unused persistence helpers have no documentation or hidden non-code callers.
Ran go test ./internal/app ./internal/cli ./internal/collect ./internal/comparison ./internal/adapters/... ./internal/fileutil ./internal/promptdebug ./internal/promptexec; all focused packages passed.
Findings: AUD-001.
Retained decisions: RET-001, RET-002, RET-003, and RET-004.
Open questions: the two leads recorded above are routed to their assigned later stages.

Stage 3: Audit Report Identity And Time Foundations

Status: Complete.
Scope reviewed: all production and focused-test code in internal/report and internal/timeutil; report and timezone contracts in docs/cli.md, docs/config.md, and docs/internal/report-registry.md; and the focused internal/app and internal/forecast callers that consume batch membership, run IDs, civil periods, clock windows, and hourly coverage.
Exclusions: Effective configuration validation and CLI date parsing remain assigned to Stages 4-5. Forecast derivation beyond the time boundary remains assigned to Stage 7. Module, prompt, schema, and template compatibility remains assigned to Stages 8 and 10-13. Batch notification and Distributor idempotency behavior remains assigned to Stage 16, and documentation-wide coherence remains assigned to Stage 24.

Contract Accounting

Contract or risk	Implementation and caller evidence	Disposition
Stable report identities	The default registry contains exactly Daily, Today, Tomorrow, and Hourly. Each definition carries the documented prompt `2.0.0`, matching template/schema identity, modules, output name, and Distributor paths; focused registry tests assert the retained surface.	Matches the registry contract; explicit definitions retained as `RET-005`. Asset compatibility remains for later owner stages.
Alias resolution	Command lookup accepts exact current command names. Config lookup separately normalizes whitespace, case, and hyphens. Both reject retired aliases in focused tests.	Matches the distinct boundary contracts; separation retained as `RET-006`.
Batch membership and ordering	Morning explicitly plans Today then Tomorrow before eligible Daily dates; Evening explicitly plans Tomorrow before eligible Daily dates. Focused app tests cover ordering, flags, multiple Daily dates, and no eligible dates.	Matches CLI and registry contracts. Detailed partial-success and notification semantics remain for Stage 16.
Report period policy	Daily requires an explicit date; Today uses an explicit date or current local date; Tomorrow selects the next local civil day; Hourly spans six elapsed hours from the injected clock. `Resolve` defaults a missing location to UTC and a zero clock to the system clock.	Matches documented selection policy; calendar and elapsed policies retained separately as `RET-007`.
Civil-day and hourly DST behavior	`CivilDay` uses local midnight plus one calendar day, and batch hourly coverage walks actual instants, correctly accommodating 23-hour and 25-hour dates. Focused batch tests exercise DST civil days.	Sufficient for the reviewed policy.
Configured clock windows	`ClockWindow` adds elapsed clock durations to local midnight. The only production path reaches `forecast.ResolveDayparts`, daily summaries, and facts. Fixed-zone tests do not exercise either DST transition.	Incorrect on DST dates; recorded as `AUD-002`.
Date and timezone parsing	`ParseLocalDate` uses strict `YYYY-MM-DD` parsing in the selected location. `LoadLocation` covers IANA names, `America/` fallback, documented aliases, fixed US abbreviations, and signed offsets, returning contextual errors for invalid input.	Implementation is coherent for Stage 3. Effective config validation and CLI error presentation remain for Stages 4-5.
Clock control	All report resolvers accept an injected `Now`; only zero-valued input falls back to `time.Now`. Focused report and batch tests use fixed clocks.	Sufficient for deterministic period selection.
Daily output and run identity	Daily output names derive from the resolved valid-start date, and Daily run IDs append that date so same-clock multi-date products remain distinct. The downstream batch-notification map rejects duplicate IDs.	Implementation is coherent, but the identity invariant lacks a focused behavior test; recorded as `AUD-003`.
Half-open period operations	`Period.Valid`, `Contains`, `Overlaps`, and `Intersection` consistently use `[start,end)` semantics, and focused tests protect overlap boundaries.	Matches the internal period contract.

Commands And Evidence

Used graph search, source snippets, and inbound/outbound traces for the four report definitions, registry construction and lookup, command/config mapping, batch mapping and planning, Resolve, every period resolver, CivilDay, ClockWindow, ParseLocalDate, LoadLocation, period overlap operations, Daily output naming, run-ID construction, ResolveDayparts, batch hourly coverage, and plannedReportsByRunID.
Compared the implementation with docs/cli.md, docs/config.md, and docs/internal/report-registry.md, then inspected the focused report, time, forecast, and app tests. Bounded text searches were used for string and test assertion discovery not represented by the code graph.
Reproduced the clock-window defect with America/Chicago transition dates: 17 elapsed hours after midnight yields 18:00 on 2026-03-08 and 16:00 on 2026-11-01; six elapsed hours yields 07:00 and 05:00 respectively.
Ran go test ./internal/report ./internal/timeutil ./internal/forecast ./internal/app; all focused packages passed.
Findings: AUD-002 and AUD-003.
Retained decisions: RET-005, RET-006, and RET-007.
Open questions: the three leads recorded above are routed to their assigned later stages.

Stage 4: Audit Configuration, Secrets, And Validation

Status: Complete.
Scope reviewed: all production and focused-test code in internal/config; the configuration-to-executor mapping in internal/cli; Promptkit adapter configuration and focused tests; all three maintained examples; docs/config.md; and configuration-related architecture, operations, documentation, and testing rules.
Exclusions: CLI parsing and action-specific diagnostics remain assigned to Stage 5. Weather API transport behavior remains assigned to Stage 6. Promptkit source loading and sensitive execution diagnostics remain assigned to Stage 11. Output publication preflight remains assigned to Stages 15 and 17, Distributor delivery remains assigned to Stage 16, and repository-wide documentation coherence remains assigned to Stage 24.

Precedence And Validation Map

Contract or risk	Implementation and consumer evidence	Disposition
Discovery and precedence	`Load` starts with `Defaults`, merges the explicit or default YAML path, tolerates only an absent implicit default file, applies nonempty units/timezone overrides, normalizes report modules, loads configured secrets, and validates. Representative CLI coverage proves explicit units/timezone beat file values while unrelated file values remain.	Matches the documented defaults → file → CLI order. Environment variables do not override config fields.
YAML schema and migrations	`mergeFile` uses `KnownFields(true)`; custom notification, report, Distributor-path, and module decoders reject their own unknown fields. Retired `scriptorium`, recent-change, and workspace keys have focused migration/rejection tests.	Sufficient for known struct fields and retired top-level contracts. Unsupported keys inside the semantic missing-source map are `AUD-004`.
Defaults and partial merges	Exact documented defaults are built once in `Defaults`; YAML decoding merges partial nested structs over them, and focused tests cover default literals, omitted optional sections, batch partial configuration, and both maintained config examples.	Matches the canonical reference. Exact-default assertions protect user-visible contracts rather than private constants.
Output directory	Config accepts empty, relative, and absolute values, preserves them byte-for-byte, and rejects only nonempty whitespace. Graph traces place path resolution, inspection, creation, and publication below app/filesystem owners.	Matches policy; retained as `RET-008`.
Weather and daypart validation	Config checks absolute base URLs when present, positive timeout, nonnegative precision, nonempty units/timezone, resolvable timezone, JSON format, nonempty dayparts, names, and parseable clocks. Collection separately requires a base URL for collection actions.	Matches the documented split. The Stage 3 DST defect remains `AUD-002`.
Missing-source policy	Policy values and nonblank keys are validated, and the adapter consumes source-specific values by source name with a default fallback. Required hourly failures bypass optional-source policy.	Unsupported and ineffective keys pass silently; `AUD-004`.
Report/module overrides	Loaded aliases, duplicate normalized reports, module identities/order, compatibility, duplicate modules/stanzas, typed options, explicit empty lists, and Distributor path templates are validated through report/module registries.	Loaded YAML behavior is well covered. Exported constructed values cannot establish private presence state; `AUD-006`. Detailed module semantics remain for Stages 8-9.
Promptkit settings	Config validates mutually exclusive profile sources, positive timeout, optional absolute local endpoint, and nonnegative concurrency. CLI maps a dormant endpoint-less limit to the adapter zero value; adapter construction owns file/directory loading, backend registration, fallbacks, and safe error classification.	Matches the documented inactive/active split; retained as `RET-009` and `RET-010`.
Secret directory	Empty disables loading. A configured directory accepts only directly contained regular files with environment-variable basenames, rejects symlinks/directories/nonregular/unreadable entries, removes one LF or CRLF, overwrites the named environment value, and reports only directory/file names and operation context.	Values are absent from tested diagnostics, but failure application is not atomic; `AUD-007`.
Distributor configuration	Disabled notification skips active-field checks. Enabled notification validates endpoint, token variable name, timeout, failure policy, allowed template variables, batch activation, and report path safety/uniqueness. Templates render from repository-owned metadata rather than environment values.	Mostly sufficient. Two single-report rendered identities omit the nonblank invariant; `AUD-005`.
Filesystem and URL timing	Config validates intrinsic string/URL shape. Output destinations are inspected by app/publication owners, Promptkit sources by its adapter, and secret entries by the config loader. No audit command contacted an external service.	Matches ownership boundaries for Stage 4; transport-specific scheme support is routed to later stages.
Constructed configuration	`Validate`, report override accessors, and focused tests attempt to provide loaded/constructed consistency without mutating caller-owned option values.	General scalar validation is consistent, but report override presence is not externally constructible; `AUD-006`.
Maintained examples	Both YAML configuration examples load through the strict config suite. The endpoint-only `weather-light` profile is inspected through the real Promptkit adapter with embedded assets and no network or credential. All examples contain synthetic endpoints and no secrets.	Matches documentation and testing policy.

Commands And Evidence

Used graph search, source snippets, call traces, and graph-augmented test searches for defaults, Load, YAML merging and migration rejection, Validate, secret loading, report/module/path traversal, notification renderers, CLI executor mapping, Promptkit adapter construction, Weather API missing-source policy consumption, and app notification consumers.
Compared executable fields, defaults, precedence, templates, paths, profile settings, source keys, and secret behavior with docs/config.md, maintained examples, and the configuration-related operations and architecture rules.
Ran the production CLI with examples/minimal-config.yml. It reached offline profile credential preflight and returned missing_credential before weather collection, confirming that the endpoint-less local concurrency default is intentionally dormant rather than rejected by adapter construction.
Ran go test ./internal/config ./internal/adapters/promptkit ./internal/cli; all focused packages passed.
Findings: AUD-004, AUD-005, AUD-006, and AUD-007.
Retained decisions: RET-008, RET-009, and RET-010.
Open questions: the four leads recorded above are routed to their assigned later stages.

Stage 5: Audit CLI Parsing, Wiring, And Output Contracts

Status: Complete.
Scope reviewed: cmd/weatherreporter, all production and representative tests in internal/cli, docs/cli.md, docs/internal/cli.md, immediate config/report/time/executor mapping, and app request/result/error boundaries. Comparison parsing and CLI translation were reviewed, while detailed comparison execution remains excluded.
Exclusions: Weather collection, report generation, publication, notification, and comparison execution correctness remain assigned to Stages 6-18. Cross-cutting parser deduplication, test portfolio durability, documentation coherence, and dynamic robustness remain assigned to Stages 21 and 23-25.

Command And Exit Accounting

Command or risk	Parsing, result, and exit evidence	Disposition
Root help and version	No arguments, `-h`, and `--help` print static help without config/provider setup. Exact `--version` prints the injected or build version; extra version arguments fail. Main prints any returned error to stderr and exits `1`; nil returns normally.	Matches the documented root contract. Help wording drift is routed to Stage 24.
Generate dispatch	Requires one of four exact report names. Command-specific flag sets accept only documented flags; Daily requires a date, Today defaults or parses one, and Tomorrow/Hourly reject `--date`. Config and explicit output/working-directory values map into one app request and one executor.	Functional mapping matches, but date validation occurs after executor construction; `AUD-009`. Assembled result/exit coverage is `AUD-010`.
Run dispatch	Requires exact Morning or Evening batch identity, accepts `--out-dir` rather than `--out`, resolves only explicit relative overrides against the absolute invocation directory, preserves configured fallback, and constructs one executor/request.	Matches the parser/wiring contract. Representative assembled result coverage is incomplete in `AUD-010`; detailed batch behavior remains Stage 16.
Compare dispatch	Requires a valid report and two distinct nonblank ordered profiles before config/executor work; applies the same report date eligibility; clears the configured default profile; maps exact bundle destination/replace/debug options; constructs one executor.	Matches the CLI contract. Focused tests cover parser, construction frequency, pre-execution failure, success/partial/cleanup summaries, quiet behavior, and safe errors. Detailed execution remains Stage 18.
Common flags and ownership	`addCommonFlags` registers config, units, timezone, and prompt debug only. Each action separately registers its output, quiet, date, profile, and replacement flags. Report and batch name lookup delegates to `internal/report`; config precedence delegates to `internal/config`.	Intentional explicitness retained as `RET-011`; repeated date policy is routed to Stage 23.
Validation ordering	Unknown commands/reports, unsupported flags, extra args, and comparison profile shape fail before configuration or executor creation. Generate performs Daily presence and Daily/Today parsing after config and executor creation.	Partly incorrect; `AUD-009`.
Output paths	CLI captures/validates one absolute working directory, preserves configured fallbacks, and resolves only nonempty relative explicit output overrides against that directory. App owns default naming and publication.	Matches CLI/config documentation and architecture ownership.
Stdout, stderr, and quiet	Result-bearing actions emit indented JSON to stdout. Run emits compact ordered item/notification/batch lines to stderr first. Quiet returns before both routine channels but the returned error still reaches main stderr. Pre-result failures emit no structured output.	Matches the documented separation; summary design retained as `RET-012`. Broken status-writer behavior is routed to Stage 25.
Generate summaries	Selected report, prompt, time, profile/model, warnings, validation, output, debug, notification, and error fields are copied; status is failed exactly when a result accompanies an error.	Shape matches documentation, but only the constructor is tested; assembled behavior is `AUD-010`. Producer redaction remains for Stages 6, 11, and 16.
Batch summaries and exit	Report counters remain independent of notification failure. Any failed report or failed notification makes summary status/error failed, emits status lines unless quiet, and returns typed `BatchError` so main exits nonzero.	Mapping is coherent and notification failure is assembled-tested. Broader representative translation coverage is `AUD-010`.
Comparison summaries	Field order is fixed by the explicit DTO; profile order is retained; unpublished artifact fields are omitted; errors are mapped to bounded aggregate, cancellation, deadline, Promptkit, destination, cleanup, or application categories.	Matches the documented safe CLI contract with strong focused coverage.
Cancellation	`Runner.Run` forwards its context to every app action, and app tests protect cancellation behavior. Production main supplies an uncancelable background context and has no signal bridge.	Programmatic propagation is correct; executable cancellation is `AUD-008`.
Test ownership	Parser/resolver tests own flag acceptance, paths, configuration mapping, and one-executor construction; summary tests own selected fields; comparison command tests own assembled translation.	Comparison is sufficient. Non-comparison assembled coverage is insufficient in `AUD-010`; lower workflow details correctly remain in app tests.

Commands And Evidence

Used graph inventory, source snippets, inbound/outbound traces, and graph-augmented searches for root dispatch, every action parser/resolver, common flag registration, working/output path resolution, executor mapping, summary/status construction, output routing, error classification, app cancellation consumers, and process signal handling.
Compared executable help, accepted flags, summary fields, error/status rules, and action wiring with docs/cli.md, docs/internal/cli.md, and the configuration, architecture, documentation, and testing contracts.
Ran go test -cover ./internal/cli; the suite passed at 75.8% statement coverage. Coverage was used only to guide test inspection, not as a finding.
Ran go run ./cmd/weatherreporter --help, go run ./cmd/weatherreporter --version, and go run ./cmd/weatherreporter generate daily; help and development-version paths succeeded, while missing Daily date returned the documented pre-result error and nonzero status without contacting an external service.
Findings: AUD-008, AUD-009, and AUD-010.
Retained decisions: RET-011 and RET-012.
Open questions: the four leads recorded above are routed to their assigned later stages.

Stage 6: Audit Weather Data Acquisition And Collection

Status: Complete.
Scope reviewed: all production code and focused tests in internal/adapters/weatherapi, internal/weatherdata, and internal/collect; all eight adapter fixtures; the Weather API integration, normalized weather-data, and collection internal documents; and immediate app/prompt-facing consumers needed to account for provenance, warnings, and error exposure.
Exclusions: Meteorological selection, alert interpretation, forecast/fact derivation, and aliasing policy remain assigned to Stage 7. Prompt-facing curation remains assigned to Stages 8-10, app orchestration to Stages 14-16, cross-cutting cleanup to Stage 23, documentation reconciliation to Stage 24, and adversarial dynamic checks to Stage 25.

Source And Failure Accounting

Source or transport risk	Required, empty, malformed, and provenance behavior	Disposition
Warmup	Calls `/conditions/current` first with format, units, and precision; requires a readable 2xx body; closes it; and stops before source requests on failure. Context cancels requests and retry waits.	Endpoint and cancellation behavior match. Permanent statuses are retried contrary to the shared policy in `AUD-015`; body safety/limits are `AUD-012` and `AUD-013`.
Observations	Optional. Missing/null and malformed data use configured policy. A successful value records observation timestamp as issue time plus endpoint, query, fetch time, and compact-data hash.	Matches the source contract.
Current conditions	Optional. Missing/null and malformed data use configured policy; successful normalized fields and provenance are retained.	Matches the source contract.
Hourly forecast	Required regardless of optional-source policy. Missing/null, decode failure, and an empty period list fail collection; format, units, precision, and timezone are sent.	Availability mapping matches, but periods with zero/reversed time bounds pass; `AUD-014`.
Narrative forecast	Optional. Missing/null and malformed data use configured policy; issue/update timestamps and forecast periods are normalized. An empty period list remains checked data.	Matches the documented source contract. Semantic forecast use remains Stage 7.
Active alerts	Optional. An absent member is missing, explicit `null` is checked empty data with a hash and no warning, and malformed non-null data uses configured policy. Alert items remain raw payloads at this boundary.	Matches the explicit alerts exception. Full duplicate raw payload is routed to Stage 23.
Forecast discussion	Optional. Missing/null and malformed data use configured policy; issue/update times, key messages, and short/long sections are normalized.	Matches the source contract.
Weather story	Optional. Uses format only; missing/null and malformed data use configured policy; start/update provenance is retained when available.	Matches the source contract.
SPC convective outlooks	Optional. Uses format/timezone without units; missing/null uses configured policy; non-null empty outlook/discussion lists are checked data; issue time prefers `issuedAt` and falls back to `asOf`; GeoJSON remains raw.	Matches the explicit SPC empty-data and provenance contract.
Optional-source policy	`error` aborts with no partial bundle, `warn` records the same stable warning in source and bundle, and `none` records a missing source without a warning. Transport/status/envelope failures remain direct request errors.	Matches the documented division. Unsupported policy keys remain the Stage 4 finding `AUD-004`.
Endpoint construction	Joins every fixed endpoint to a base path prefix and applies only the required format/units/precision/timezone matrix.	Query/path behavior matches for HTTP(S); unsupported absolute schemes survive until runtime in `AUD-011`. Base URL query/user-info shape is routed to Stage 24.
HTTP attempt lifecycle	Requests carry context and configured client timeout; response bodies close after bounded reads; source attempts retry transport/read failures and only the documented transient statuses.	Mostly coherent. Unsafe response text and silent truncation are `AUD-012`/`AUD-013`; warmup classification divergence is `AUD-015`.
Normalization and collection ownership	`weatherdata` contains no HTTP/config/filesystem behavior. The adapter translates wire envelopes into project types. `collect.Run` constructs one adapter, forwards context, and distinguishes setup from fetch errors.	Matches architecture; the narrow collection seam remains retained under `RET-004`. Source-specific normalization remains explicit under `RET-013`.
Test assets and ownership	Adapter tests use `httptest.Server` for HTTP/query/status/retry/cancellation/policy behavior and eight small checked-in JSON fixtures for translation. `weatherdata` owns a focused GeoJSON round trip; `collect` owns three real local composition/error cases. Fixtures are synthetic, credential-free, and total under 5 KiB.	Ownership is distinct and offline. Missing high-risk cases are attached to `AUD-011` through `AUD-015`, not inferred from coverage alone.

Commands And Evidence

Used graph architecture, symbol search, source snippets, inbound traces, and graph-augmented use searches for adapter construction, all eight source methods, HTTP attempts and retries, body lifecycle, endpoint/query assembly, missing/malformed policy, hashes and timestamps, normalized source consumers, collect.Run, and propagation toward app/CLI boundaries.
Compared implementation and fixtures with docs/integrations/weatherapi.md, docs/internal/weather-data.md, docs/internal/collect.md, the architecture policy, and the testing policy. Bounded text inspection was used for documentation, JSON fixtures, literal credential markers, and known test assertions outside graph discovery.
Ran go test -coverprofile=/tmp/weatherreporter-stage6-cover.out ./internal/adapters/weatherapi ./internal/weatherdata ./internal/collect; all focused packages passed. Adapter statement coverage was 84.9% and collection coverage 100%; coverage was used only to guide branch inspection.
Findings: AUD-011, AUD-012, AUD-013, AUD-014, and AUD-015.
Retained decisions: existing RET-004 was revalidated and RET-013 records explicit source normalization.
Open questions: the four leads recorded above are routed to their assigned later stages.

Stage 7: Audit Forecast And Fact Derivation

Status: Complete.
Scope reviewed: all production code and focused tests in internal/forecast and internal/facts; the forecast derivation and facts internal documents; normalized forecast types; and immediate briefing/app consumers needed to determine unit meaning, mutation ownership, and whether derived facts participate in normal workflows.
Exclusions: Detailed source-facing, derived, planning, formatting, and SPC briefing behavior remains assigned to Stages 8-9. Cross-cutting test portfolio and cleanup remain assigned to Stages 19-23, documentation reconciliation to Stage 24, and adversarial dynamic checks to Stage 25.

Derivation Rule And Edge-Case Accounting

Derivation rule or risk	Boundary, ordering, and test evidence	Disposition
Valid-period selection	Hourly, narrative, and daily runs use half-open overlap, retain complete source periods, and stable-sort by start time. Nil runs return no facts. Focused tests cover unsorted input, partial overlap, and exact-boundary exclusion.	Matches the source-period contract; complete-period selection is retained as `RET-014`. Structurally invalid required periods remain `AUD-014`.
Civil-day summaries and dayparts	Daily summaries require hourly data, resolve configured local windows, and select each daypart independently. Empty dayparts remain explicit summaries; overnight hourly selection crosses midnight.	Ordinary and empty behavior matches. DST window construction remains `AUD-002`; after-midnight alert selection is incorrect in `AUD-017`.
Temperature and wind aggregation	Min/max and peak selection is deterministic for populated values; numeric heat/cold thresholds distinguish Fahrenheit and Celsius. Wind and all unitless summary fields fall back between explicit unit fields without conversion.	Incorrect for metric fallback values; `AUD-016`. Paired unit-system regressions are absent.
Condition indicators	Text matching is case-insensitive; numerical heat, cold, and wind signals merge monotonically across periods. Dominant-condition ties resolve lexically and notable conditions sort.	Deterministic, but common “icy” text is missed; `AUD-019`. Broader briefing interpretation remains Stage 9.
Precipitation timing	Input is copied and stable-sorted. Exact threshold inclusion, dry input, gaps, maxima, text aggregation, thunder mentions, and intentionally open final windows have focused tests.	Window mechanics match. The percentage domain is unenforced in `AUD-018`; the open final window is an intentional horizon signal.
Alert parsing and overlap	Supported time-field fallbacks, malformed omission, instruction whitespace, half-open clipping, ordering, and direct boundary cases have focused tests.	Direct behavior matches. Daily prefiltering loses alerts in wrapping dayparts; `AUD-017`.
Collected facts and mutation	Collection projects every normalized product and copies top-level sources/warnings. Bundle reconstruction repeats those top-level copies; derivation reads shared nested values without mutation.	Fits immutable workflow ownership and is retained as `RET-015`; no speculative deep-copy requirement was added.
Report-family derived facts	Every report selects valid-period hourly, narrative, daily, alert, precipitation, and SPC facts. Daily/Today/Tomorrow additionally build one daily/daypart summary; Hourly does not; unknown reports and invalid periods fail.	Matches the implemented report-family contract with focused cases. The stale multi-day documentation name is routed to Stage 24.
SPC outlooks and discussions	Only valid overlapping outlook periods are selected. Output ordering uses day, type, severity rank, validity, label, and ID; discussions are retained only for selected days and sorted deterministically. Nil and checked-empty runs remain empty facts.	Matches documented checked-empty and deterministic ordering behavior with focused tests. Detailed briefing meaning remains Stage 9.
Repeated work and realistic size	One derived build performs several linear selections, then each configured daypart scans the hourly run and its alert candidates; selected precipitation and SPC slices are sorted. With the normal four dayparts and service-sized runs of a few hundred periods, this is only low-thousands of simple overlap checks.	No Stage 7 performance finding. Reassess in Stage 22 only if horizons, daypart counts, or alert volumes become materially larger or derivation is repeated per module.
Test ownership	`forecast` owns selection, summaries, thresholds, precipitation, parsing, overlap, ordering, and fixture integration. `facts` owns projection, report-family derivation, SPC filtering/order, and failure cases. `timeutil` owns the underlying period rules.	Ownership is coherent. Missing high-risk unit, overnight-alert, percentage-domain, and icy-text cases are attached to `AUD-016` through `AUD-019`, not inferred from coverage alone.

Commands And Evidence

Used graph architecture, symbol search, source snippets, call traces, and graph queries for every scoped derivation function, report-family consumers, unit-bearing normalized fields, comparison helpers, loops, sorting, and immediate unit interpretations. Text search was limited to documents, literals, fixtures, and focused assertions where graph discovery was not applicable.
Compared implementation and tests with docs/internal/forecast-derivation.md, docs/internal/facts.md, and the architecture, documentation, and testing policies. Existing Stage 3 and Stage 6 findings were treated as dependencies rather than duplicated.
Ran go test -coverprofile=/tmp/weatherreporter-stage7-cover.out ./internal/forecast ./internal/facts ./internal/timeutil; all focused packages passed. Statement coverage was 89.7% for forecast, 73.4% for facts, and 54.5% for timeutil; coverage guided branch inspection but was not itself a finding.
Findings: AUD-016, AUD-017, AUD-018, and AUD-019.
Retained decisions: RET-014 and RET-015.
Open questions: the three leads recorded above are routed to their assigned later stages.

Stage 8: Audit Module Contracts, Registry, And Source-Facing Briefing Modules

Status: Complete.
Scope reviewed: internal/module; briefing registry and package contracts; metadata, current conditions, narrative forecast, hourly forecast, alert digest, area forecast discussion, and weather story builders and their directly related tests; report default composition; configuration module normalization/validation; and the relevant module, briefing, and prompt-input internal documentation.
Exclusions: Derived daily/daypart, precipitation, outdoor/planning, detailed formatting, and SPC builders remain assigned to Stage 9. Complete prompt serialization and asset contracts remain Stage 10, application preparation remains Stage 14, cross-cutting cleanup remains Stage 23, and documentation coherence remains Stage 24.

Registry And Source-Module Accounting

Contract or module	Registry, transformation, and test evidence	Disposition
Neutral module envelope	Stable IDs and fact/option vocabulary live in `internal/module`; snapshots preserve caller order, omit runtime prompt values from JSON, reject missing identities and duplicates, and support typed rich-stanza lookup.	Separation is retained as `RET-016`. Exact version compatibility is not enforced; `AUD-022`.
Registry initialization	Default definitions have unique IDs/stanzas, builders, supported reports, typed defaults, missing-data behavior, requirements, and prompt-export policy. Constructor tests cover duplicates, absent builders, and unsupported `warn`; default report compositions validate.	Default metadata is coherent. Unknown custom missing-data values fail only at build time; low-impact constructor hardening is left for Stage 23 unless the registry becomes extensible.
Configuration and options	Configuration normalizes raw YAML into registry-declared option types, validates compositions through the same registry, and preserves report order. Only AFD has nonempty default selections and consumes a section list.	IDs/defaults/order agree. Accepted pointer/value option shapes diverge at the AFD builder; `AUD-020`.
BuildModule policy	Lookup, report support, option shape, fact availability, omit/error/empty behavior, output identity, and prompt export execute in one boundary. Exporter failures receive module/stanza context and outputs are identity-checked before export.	Coherent for defaults. The branching is policy-driven rather than per-module switch testing; builders are exercised through public registry behavior.
Metadata	Emits report identity, variant, prompt, generation/period context, configured units/timezone/location, and bounded source-warning summaries without endpoint/hash provenance or alert duplication. It remains available with empty source metadata.	Matches the documented prompt-safe module contract with focused field/omission tests. Parallel non-module metadata construction is routed to Stage 23.
Current conditions	Optional source; rounds explicit unit fields, retains day/condition/humidity, derives compass labels, omits a wholly empty value, and uses a curated prompt projection without lowercase/display helpers.	Matches source and prompt-export contracts with focused rich/prompt tests.
Narrative forecast	Daily/Today/Tomorrow only; requires both source presence and selected derived periods, maps only valid-period values, copies unit-bearing fields, and produces local friendly bounds and compass wind labels. Missing or empty selections omit the module.	Matches support, selection, transformation, and omission contracts with focused tests. Invalid normalized percentages remain `AUD-018`.
Hourly forecast	All reports; requires source presence and selected periods, maps the complete selected weather fields, derives labels/compass direction, and marks precipitation at the exact 20-percent threshold. Its prompt export omits rich-only labels and mention helpers.	Matches support, boundary, rich-value, and curated-export contracts with focused tests. Invalid period/percentage inputs remain `AUD-014`/`AUD-018`.
Alert digest	All reports with explicit empty behavior; distinguishes checked-empty and source-missing states, counts raw active and relevant overlaps separately, preserves derived order, and formats full alert periods with guidance.	Matches availability and value contracts; distinction retained as `RET-018`. Overnight relevance remains the upstream `AUD-017`.
Area forecast discussion	Optional for all reports; empty section lists mean all sections, report defaults select long-term for Daily and key messages/short-term for Hourly, unsupported names fail, and selected slices are copied.	Section policy and defaults agree, but pointer-shaped accepted options fail construction; `AUD-020`.
Weather story	Optional for all reports; copies story content, flags, URL, update time, and friendly valid-period labels.	Populated and missing behavior is tested. Structurally empty data is incorrectly emitted as available; `AUD-021`. Complete prompt curation remains Stage 10.
Mutation and ordering	Snapshot outputs copy the outer slice; source modules copy scalar pointers and AFD key-message slices. Prepared-report construction later deep-copies complete inputs. Registry and report order flow unchanged into snapshots.	No shared-mutation finding under immutable preparation ownership. Rich/prompt separation is retained as `RET-017`.
Complexity drivers	`BuildModule` centralizes validation/missing/export branching; fact availability uses parallel requirement switches; default definitions form a long policy table; current/hourly prompt projections copy many fields. Builders otherwise perform small linear maps over service-sized periods/alerts.	No Stage 8 performance finding. Table/switch drift, parallel metadata, and projection duplication are routed to Stage 23 with concrete owners.
Test ownership	Module tests own snapshot structure/order and rich-versus-prompt selection. Briefing registry tests own default composition, support, options, missing behavior, output/export validation, and assembled snapshots. Source-module tests own observable transformations and omissions; config tests own YAML normalization.	Mostly sufficient and behavioral. Missing pointer-consumption, empty-story, and unsupported-schema cases are attached to `AUD-020` through `AUD-022`.

Commands And Evidence

Used graph architecture, symbol search, source snippets, inbound traces, and graph queries for snapshot consumers, registry/config validation, all scoped builders and exporters, source fields, default report compositions, tests, shared-state copying, and complexity drivers. Text inspection was limited to scoped documentation and targeted source/test bodies.
Compared implementation and focused tests with docs/internal/module.md, relevant portions of docs/internal/briefing.md and docs/internal/prompt-input.md, and the architecture, documentation, and testing policies.
Ran go test -coverprofile=/tmp/weatherreporter-stage8-cover.out ./internal/module ./internal/briefing ./internal/config ./internal/report; all focused packages passed. Statement coverage was 86.5% for module, 82.5% for briefing, 86.1% for config, and 48.8% for report; coverage guided risk inspection but was not itself a finding.
Findings: AUD-020, AUD-021, and AUD-022.
Retained decisions: RET-016, RET-017, and RET-018.
Open questions: the four leads recorded above are routed to their assigned later stages.

Stage 9: Audit Derived, Planning, Formatting, And SPC Briefing Modules

Status: Complete.
Scope reviewed: the remaining production code and focused tests in internal/briefing: daily and daypart summaries, precipitation timing, outdoor windows, Daily/Today/Tomorrow planning, shared summary and formatting helpers, SPC outlooks and discussions, and the embedded SPC definition asset; plus relevant briefing, facts, configuration, and authoritative SPC references needed to judge the domain rules.
Exclusions: Complete prompt serialization and embedded prompt assets remain Stage 10; generated-text schemas and render contexts remain Stages 12-13; application preparation remains Stage 14; test-portfolio and cross-cutting cleanup remain Stages 19-23; canonical documentation reconciliation remains Stage 24; and adversarial dynamic checks remain Stage 25.

Derived And Planning Rule Accounting

Module or risk	Threshold, ordering, missing-data, and test evidence	Disposition
Daily summary	Selects narrative high/low and daily precipitation when present, falls back to daypart aggregates, preserves deterministic conditions/hazards, and emits timing/gust facts.	Ordinary and fallback selection are exercised. Apparent temperature is incorrectly relabeled as heat index in `AUD-023`; unit fallback remains upstream `AUD-016`.
Daypart summaries	Emit local periods, ranges, condition/hazard flags, precipitation and gust maxima, temperature phrases/trends, and configured normalized keys; date prefixes prevent ordinary multi-day collisions.	Field and positive-temperature behavior is exercised. Canonical key collisions are `AUD-024`, subzero wording is `AUD-027`, and unit interpretation remains `AUD-016`.
Precipitation timing	Maps dry and rainy windows, open-ended periods, expectation thresholds, type phrases, thunder mentions, and local labels without mutating derived order.	Matches the reviewed briefing contract with focused rainy, dry, threshold, phrase, and missing-daypart cases. Percentage-domain defects remain `AUD-018`.
Outdoor windows	Scores precipitation, gusts, alerts, heat, and cold; preserves deterministic input-order ties and exposes best/worst periods and reasons to Today planning.	Incomplete hazard policy: snow, ice, and fog can score as quiet; `AUD-026`.
Planning variants	Daily and Tomorrow share morning, workday, and overnight sections; Today intentionally adds outdoor and late-day sections. Empty daily summaries produce empty modules or defined fallback prose according to builder context.	Report variation is intentional and retained as `RET-019`. Configurable name classification is inconsistent in `AUD-025`; upstream unit/alert/text defects are not duplicated.
User-facing formatting	Time/date labels use the requested location with UTC fallback, wind compass boundaries are focused-tested, strings are deduplicated in stable order, and sentence casing is Unicode-aware.	Ordinary formatting is coherent. Signed temperature bands are incorrect in `AUD-027`; byte-oriented title casing is routed to Stage 23 after the identity defects.
SPC outlooks	Preserve selected overlapping records and checked/missing status, attach definitions only for recognized normalized keys, and compute a location-specific categorical risk digest at severity rank 3 or higher.	Selection, ordering, threshold equality, type, location, overlap, unknown definitions, and empty/missing states have focused tests; separation retained as `RET-020`. Official categorical descriptions have drifted in `AUD-028`.
SPC discussion	Includes selected discussions only for days with an overlapping categorical outlook meeting the rank threshold; ignores high-rank noncategorical products and nonoverlapping outlooks.	Matches the explicit regional discussion policy with focused threshold, day, type, overlap, missing-text, and missing-source cases.
Complexity and repetition	Scoped builders perform small linear maps over configured dayparts, precipitation windows, outlooks, and discussions. The highest production cognitive scores are in planning, precipitation type selection, and outdoor scoring, with no material service-sized cost.	No Stage 9 performance finding. Repeated daypart role/display logic is routed to Stage 23 with concrete evidence.
Test ownership	One derived-module suite owns daily/daypart/precipitation/planning behavior, format-helper tests own compass mapping, and dedicated SPC suites own risk/discussion/definition behavior.	Mostly behavioral. Missing semantic regressions are attached to `AUD-023` through `AUD-028`, not inferred from coverage alone.

Commands And Evidence

Used graph symbol and augmented-code search, source snippets, inbound traces, and complexity queries for every remaining builder/helper, configured daypart identities, apparent-temperature flow, outdoor hazard inputs, signed temperature bands, SPC selection/definition lookup, and their focused tests. Bounded text inspection was used for scoped documents, configuration examples, and the embedded JSON asset.
Compared SPC vocabulary and externally attributed definitions with NOAA/NWS Storm Prediction Center's current convective-outlook reference and the 2026 Conditional Intensity service-change notice. Categorical definition drift is recorded as AUD-028; supported CIG identifiers and the distinction between occurrence probability and conditional intensity remain coherent.
Ran go test -coverprofile=/tmp/weatherreporter-stage9-cover.out ./internal/briefing ./internal/config ./internal/forecast ./internal/facts; all focused packages passed. Statement coverage was 82.5% for briefing, 86.1% for config, 89.7% for forecast, and 73.4% for facts; coverage guided missing-edge inspection but was not itself a finding.
Findings: AUD-023, AUD-024, AUD-025, AUD-026, AUD-027, and AUD-028.
Retained decisions: RET-019 and RET-020.
Open questions: the three leads recorded above are routed to their assigned later stages.

Stage 10: Audit Prompt Inputs, Assets, And Neutral Execution Contracts

Status: Complete.
Scope reviewed: all production and focused-test code in internal/promptinput, internal/promptassets, and internal/promptexec; every embedded prompt, Promptkit profile, input schema, and output schema; prompt-input and generated-text internal documents; the Promptkit integration contract; and immediate briefing/application consumers needed to establish the provider-boundary data flow.
Exclusions: Promptkit adaptation, provider cancellation/error translation, and secure debug files remain Stage 11; output schemas and generated-text semantics remain Stage 12; application preparation/provider preflight remains Stage 14; cross-cutting API cleanup and documentation coherence remain Stages 23-24; and adversarial repository-wide checks remain Stage 25.

Prompt Boundary And Execution Accounting

Contract or risk	Serialization, asset, caller, and test evidence	Disposition
Curated work-package construction	Application preparation reaches `promptinput.Build` and `MarshalYAML` from ordered module `DataPackageValue` exports, not normalized bundle serialization. Report identity, local date, period, and module categories are explicit.	Module values follow the curated path, but the top-level raw warning copy violates it in `AUD-029`.
Category order and normalization	One fixed table groups known stanzas as metadata, applicable risk, derived, narrative, and raw data; module order is retained within groups. Values normalize through JSON before YAML, and repeated marshals are byte-identical in focused tests.	Coherent and retained as `RET-021`; missing failure-branch coverage is `AUD-033`.
Package validation and loading	Current schema, report/run metadata, ordered stanza presence, duplicate order entries, known category membership, and misplaced stanzas are rejected. A temporary table-driven probe exercised additional malformed shapes.	Incomplete for required metadata, orphan values, unknown struct fields, and trailing documents; `AUD-032`.
Embedded prompt identities	Exactly four report definitions bind the registry's prompt ID/version, embedded profile, `weatherreporter.data_package.v4` input schema, and matching generated-text output schema. Real offline Promptkit inspection succeeds for each.	Identity is coherent; common prose references nonexistent serialized paths in `AUD-030`.
Safety-sensitive prompt semantics	The shared prompt prioritizes risk, forbids invention, and asks regional discussion limitations to be preserved.	Its blanket assertion that all retained products are location matched contradicts SPC module semantics; `AUD-031`.
Embedded profiles and schemas	Exactly three profiles carry the intended backend/model/timeouts/reasoning/tier settings; tests reject unsafe/incidental profile settings and retired runtime strings. Embedded schema bytes are independently copied.	Matches the scoped identity and immutability contracts. Output-schema field meaning remains Stage 12.
Inspection and execution lifecycle	Dependency-neutral requests carry context and exact prompt/profile identity. Execution runs validation callbacks before provider work and distinguishes completed validation rejection from operational failure without a result.	Coherent and retained as `RET-022`; adapter realization remains Stage 11.
Safe errors, debug, and result isolation	All stable error categories are covered; safe errors preserve causes while omitting cause text; messages and invalid UTF-8 diagnostics are bounded; debug is opt-in; returned output/debug bytes and maps are copied.	Sufficient at the neutral contract boundary. Dependency diagnostics remain Stage 11.
Complexity and realistic input size	The highest scoped production path is stanza YAML marshaling, with two shallow loops over five fixed categories and the report's service-sized module list. Asset lookup and neutral result construction are constant or small linear work.	No Stage 10 performance finding; explicit grouping remains cheaper to reason about than generic reflection.
Test ownership	Prompt-input tests own construction, validation, grouping, ordering, category placement, and YAML round trips; prompt-assets tests own embedded inventories/identities and real inspection; prompt-exec tests own lifecycle, category, error, debug, bound, and copy semantics.	Mostly behavioral and nonduplicated. Missing provider-boundary warning/path/locality and serialization/load cases are attached to `AUD-029` through `AUD-033`.

Commands And Evidence

Used graph architecture, symbol and augmented-code search, snippets, inbound/outbound traces, data-flow traces, and complexity queries for Build, Validate, MarshalYAML, LoadYAML, stanza grouping/normalization, prompt asset lookup, execution request/result construction, and application preparation callers. Bounded text inspection covered embedded Markdown, YAML, and JSON assets and their focused assertions.
Compared implementation and tests with docs/internal/prompt-input.md, docs/internal/generatedtext.md, docs/internal/module.md, docs/integrations/promptkit.md, and the architecture, documentation, and testing policies. Every embedded prompt/profile/schema reference was inventoried and cross-checked against the report registry.
Ran a temporary focused malformed-package probe proving acceptance of missing metadata, orphan stanza values, unknown fields, and a trailing YAML document, then removed the probe without retaining test or product changes.
Ran go test -coverprofile=/tmp/weatherreporter-stage10-cover.out ./internal/promptinput ./internal/promptassets ./internal/promptexec; all focused packages passed. Coverage guided branch inspection but was not itself treated as a finding. Ran go test ./..., go vet ./..., and git diff --check; all passed.
Findings: AUD-029, AUD-030, AUD-031, AUD-032, and AUD-033.
Retained decisions: RET-021 and RET-022.
Open questions: the three leads recorded above are routed to their assigned later stages.

Stage 11: Audit Promptkit Adaptation And Secure Prompt Debugging

Status: Complete.
Scope reviewed: all production and focused-test code in internal/adapters/promptkit and internal/promptdebug; Promptkit integration and adapter internals; relevant operations, architecture, documentation, and testing rules; Promptkit v0.5.0's local public concurrency/prepared-execution contract; and immediate app/CLI consumers needed to trace credential checks, debug authorization, callback failure, and result projection.
Exclusions: Generated-text schema semantics remain Stage 12; application prompt inspection/preparation order remains Stage 14; comparison execution scheduling remains Stage 18; suite-wide test hygiene and cross-cutting cleanup remain Stages 19-23; documentation-wide coherence remains Stage 24; and broader adversarial diagnostics remain Stage 25.

Adapter And Debug-Security Accounting

Contract or risk	Adapter, filesystem, caller, and test evidence	Disposition
Dependency containment and configuration	Promptkit production imports occur only in its adapter. CLI-owned settings map to profile directory/file, local endpoint/capacity, and timeout; mutually exclusive sources and inactive local capacity fail construction.	Matches the architecture boundary. Profile resolution remains dependency-owned under `RET-023`.
Profile source precedence	Explicit in-memory definitions, configured file/directory, embedded fallback, and built-ins provide complete definitions in the documented order. Absence falls through; a malformed matching configured definition fails.	Coherent with offline focused tests and retained as part of `RET-023`.
Exact inspection and credential preflight	Prompt inspection returns exact ID/version/hash, one input, and output contract. Profile inspection returns only logical ID, backend/model, direct-key requirement, and environment-variable name; app checks direct keys and nonblank environment values before collection.	Safe values and missing-credential categories match. Environment names are identifiers, not secret values.
Prepared inline execution	The adapter copies the YAML bytes into one inline artifact, prepares once, invokes the callback before generation, and runs the same opaque one-use handle. Callback failure prevents the provider call and deferred discard clears unused private state.	Matches the integration contract with exact-provenance and callback tests.
Cancellation and concurrency	Preparation and execution receive caller context independently; canceled/deadline causes map before generic generation errors. Promptkit documents `Engine` as concurrency-safe with capacity owned per engine, and comparison uses one adapter concurrently without wrapper state.	Coherent; race-enabled adapter/app tests pass. No redundant application-wide limit or adapter mutex is warranted.
Error classification and normal redaction	Promptkit configuration, prompt/profile, credential, artifact/render, capacity, generation, validation, request, cancellation, and deadline errors map to bounded repository categories. Underlying causes remain discoverable but their content does not enter `Error()`, summaries, or logs.	Sufficient at this boundary; focused marker and category tests protect normal output.
Debug authorization and isolation	Empty root disables all filesystem access; an enabled root must be absolute and not `/`. Report/date/run segments reject separators and traversal, comparison derives distinct deterministic run segments, and content-rich values appear only when capture is requested.	Matches explicit opt-in and per-run isolation. Separate ownership retained as `RET-024`.
Debug credential projection	User information, fragments, known secret query keys, and known nested parameter keys are removed or redacted before preparation JSON is written.	The denylist misses common aliases, signed/path credentials, and arbitrary provider vocabulary; `AUD-034`.
Directory and symlink containment	Static symlinks in the root or any visible descendant component are rejected; directory modes are tightened to `0700`, and unsafe references fail before a file write.	Path checks are separated from later name-based creation/replacement and can be raced; `AUD-035`.
File collision, modes, and partial writes	JSON is marshaled before creation; same-name artifacts use a mode-`0600` temporary in the final directory and atomic rename; non-regular existing targets are rejected; distinct concurrent run directories and shared missing ancestors are tested.	Coherent for non-adversarial paths. A failed requested callback stops generation, and a failed execution write stops publication.
Complexity and test ownership	Adapter mapping/classification is straight-line or small linear copying. Debug recursion follows bounded JSON-compatible parameter trees; directory traversal is linear in path components; realistic artifact sizes are dominated by intentionally captured prompt/output content. Adapter tests own dependency translation; debug tests own filesystem/security behavior; app tests own callback consequences.	No Stage 11 efficiency or duplication finding. Redaction and race gaps are attached to their narrow owners rather than inferred from coverage.

Commands And Evidence

Used graph architecture, symbol and augmented-code search, snippets, inbound/data-flow traces, and hotspot inspection for adapter construction, exact inspection, preparation/execution, classification, debug writes, path validation, redaction, application callbacks, and CLI debug-root flow. Text inspection was limited to scoped documents, tests, string-based security policy, and the locally installed Promptkit v0.5.0 contract.
Confirmed Promptkit's public engine concurrency guarantee, one-use prepared handle state, independent preparation/execution contexts, credential-redacted details, and upstream concurrent engine contract test without contacting a provider.
Ran a temporary deterministic redaction probe using only synthetic markers; it proved that common endpoint-query and nested-parameter aliases survive serialization, then was removed without retaining source/test changes.
Ran go test -race -coverprofile=/tmp/weatherreporter-stage11-cover.out ./internal/adapters/promptkit ./internal/promptdebug ./internal/app; all focused packages passed with 90.0%, 73.6%, and 76.0% statement coverage respectively. Coverage guided branch inspection but was not itself a finding. Ran go test ./..., go vet ./..., and git diff --check; all passed.
Findings: AUD-034 and AUD-035.
Retained decisions: RET-023 and RET-024.
Open questions: the three leads recorded above are routed to their assigned later stages.

Stage 12: Audit Generated-Text Validation And Catalog Contracts

Status: Complete.
Scope reviewed: all production and focused validation/catalog tests in internal/generatedtext except render_context.go and its focused tests; all four embedded generated-text schemas and their promptassets owner; schema assertions currently placed in internal/reporttemplate; the generated-text and Promptkit integration contracts; and the immediate Promptkit/application path needed to establish schema validation, raw-output dispatch, and error propagation.
Exclusions: Render-context assembly, template/partial semantics, and Markdown rendering remain Stage 13; application preparation and preflight ordering remain Stage 14; publication consequences remain Stages 15-18; suite-wide durability and refactoring remain Stages 19-23 except for duplication explicitly assigned to this stage; documentation-wide coherence remains Stage 24; and repository-wide adversarial checks remain Stage 25.

Generated-Text Contract Accounting

Contract or risk	Schema, decoder, catalog, caller, and test evidence	Disposition
Raw output to typed value	Promptkit validates raw provider JSON against the report definition's embedded schema and reports passed/failed status. After a pass, app dispatches the same raw bytes through the prepared handler; the report validator strictly decodes shape, trims prose, removes blank day-style paragraphs, applies semantic required-field rules, and returns a typed value plus canonical JSON before context construction.	The path and ownership are explicit. Retain both validation layers under `RET-026`; their exact-name disagreement is `AUD-037`.
Required and empty fields	Every schema requires summary, forecast discussion, and precipitation timing and rejects additional properties. Go requires nonblank trimmed summary/discussion; day-style discussion retains one or more nonblank paragraphs; precipitation timing must be present and string-valued but may normalize to empty. Null and wrong structural types fail.	Coherent aside from case-insensitive aliases. The schema intentionally permits lexical blanks that repository semantic validation rejects.
JSON document strictness	Typed decoding rejects malformed JSON, unknown canonical additions, wrong field types, and multiple top-level values. It accepts surrounding whitespace. Duplicate names follow Go/parsed-JSON last-value semantics because no stronger canonical rule exists.	Sufficient for documented document shape, with exact-key enforcement missing in `AUD-037`. Duplicate policy is routed to Stage 25 remediation validation rather than declared retroactively.
Array and size behavior	Day-style arrays require one schema item and one nonblank normalized paragraph but have no item-count or aggregate bound. No schema or Go string/total-output bound exists, and decoder unknown-field errors quote arbitrary names.	Unbounded accepted prose and diagnostics are `AUD-038`.
Report-specific types and shared mechanics	Daily, Today, and Tomorrow are distinct types and validators over one private field projection and validation helper; Hourly deliberately uses a single discussion string. Typed context builders can therefore distinguish reports even when day-style fields match.	Appropriate separation retained as `RET-025`; tests duplicate rather than merely protect that choice in `AUD-039`.
Catalog compatibility	Four entries bind schema/template pairs to validators and builders; current registry iteration resolves all entries, schema/template lookup returns nonempty assets, and unknown IDs or mismatched known pairs fail.	Entries omit report identity, so a complete known pair can be assigned to the wrong report; `AUD-036`.
Asset ownership and immutability	`promptassets` embeds and returns independent copies of all four schema byte slices. `generatedtext.Handler.Schema` adds report context; `reporttemplate` production code owns templates and does not own schemas.	Production ownership and copy isolation are coherent. Schema tests placed in `reporttemplate` duplicate the asset owner's assertions; `AUD-039`.
Error safety	Semantic required-field errors and catalog errors contain stable report/schema/template identifiers. JSON library errors are wrapped with report kind and preserve causes.	Arbitrary unknown-field names are emitted without a diagnostic bound and can be wrapped into normal application errors; part of `AUD-038`. No raw value is otherwise deliberately included.
Complexity and realistic cost	Scoped validators are straight-line except for one pass over discussion paragraphs; catalog lookup scans four fixed entries. Normal work is linear in provider output and paragraph count.	Algorithms are proportionate, but absent input/array limits make their allocation and normalization cost attacker/provider-controlled; `AUD-038`.
Test ownership and durability	Focused tests cover all four dispatches, canonical normalization, malformed/type/multiple-value cases, required semantics, retired fields, catalog lookup, schema inventory/identity, and independent schema bytes.	Exact report pairing, schema/Go agreement, and bounds are unprotected. Day-style semantics and schema shapes are redundantly asserted across packages; `AUD-036` through `AUD-039`.

Commands And Evidence

Used graph architecture, symbol and augmented-code search, inbound/data-flow tracing, snippets, and complexity queries for catalog lookup, schema access, typed decoding/normalization, report validators, application execution, and their production/test callers. Bounded text inspection covered the four JSON schemas, scoped tests, generated-text/Promptkit documentation, and policy.
Compared each schema's exact required fields and property shapes with Daily, Today, Tomorrow, and Hourly structs and semantic validators. Traced schema validation status through Promptkit adaptation into app's handler dispatch and verified schema byte-copy isolation and fixed catalog scan cost.
Ran temporary offline probes showing that a Daily definition accepts the known Hourly pair, Go accepts case-varied summary/discussion keys while real embedded-schema validation rejects them, both layers accept a two-MiB valid summary, and a 64-KiB synthetic unknown key appears in full in the decoder error. The probes were removed without retaining source or test changes.
Ran go test -coverprofile=/tmp/weatherreporter-stage12-cover.out ./internal/generatedtext ./internal/promptassets ./internal/reporttemplate; all packages passed with 81.3%, 73.7%, and 86.2% statement coverage respectively. Coverage guided branch inspection but was not itself treated as a finding. Ran go test ./..., go vet ./..., and git diff --check; all passed.
Findings: AUD-036, AUD-037, AUD-038, and AUD-039.
Retained decisions: RET-025 and RET-026.
Open questions: the three leads recorded above are routed to their assigned later stages.

202 KiB Raw Blame History

Repository Audit Ledger

Executive Summary

Baseline Metadata

Scope And Inventory

Go Packages And Files

Fixtures

Embedded Assets

Canonical Documents And Maintained Examples

Baseline Validation

Stage Coverage

Risk-To-Test Coverage

Findings

AUD-001: Unused persistence helpers remain after the stateless redesign

AUD-002: Clock windows shift on daylight-saving transition days

AUD-003: Daily run-ID uniqueness lacks a focused contract test

AUD-004: Unsupported missing-source keys are silently accepted

AUD-005: Single-report notification identities may render blank

AUD-006: Constructed report overrides depend on inaccessible presence flags

AUD-007: Failed configuration loads can leave secrets applied

AUD-008: Process interrupts do not cancel active workflows

AUD-009: Generate validates report dates after constructing its executor

AUD-010: Assembled non-comparison CLI result paths lack durable tests

AUD-011: Unsupported Weather API URL schemes fail only at transport

AUD-012: Weather API failures expose upstream response bodies

AUD-013: The Weather API response limit silently truncates bodies

AUD-014: Required hourly periods can lack usable time bounds

AUD-015: Weather API warmup retries permanent HTTP failures

AUD-016: Metric fallback values lose their unit during daypart derivation

AUD-017: Overnight dayparts omit alerts that begin after midnight

AUD-018: Invalid precipitation percentages flow into derived summaries

AUD-019: Ordinary “icy” forecast text does not set the ice indicator

AUD-020: Pointer-shaped AFD options pass validation but fail construction

AUD-021: Empty weather-story data is published as available

AUD-022: Module snapshots accept unsupported schema versions

AUD-023: Apparent temperature is published as heat index

AUD-024: Normalized daypart keys can silently overwrite summaries

AUD-025: Planning applies configurable daypart identities inconsistently

AUD-026: Outdoor-window ranking ignores snow, ice, and fog

AUD-027: Subzero temperatures are rendered as positive zero-degree bands

AUD-028: Embedded official SPC category descriptions have drifted

AUD-029: Raw source warnings cross the curated prompt boundary

AUD-030: The shared prompt instructs nonexistent briefing paths

AUD-031: The shared prompt overstates SPC product locality

AUD-032: The exported YAML loader accepts malformed package shapes

AUD-033: Stanza serialization failures lack a focused contract test

AUD-034: Prompt-debug credential redaction misses common aliases and URL forms

AUD-035: Prompt-debug symlink checks can be raced before writes

AUD-036: The generated-text catalog accepts a known pair for the wrong report

AUD-037: Typed decoding accepts property names rejected by the schema

AUD-038: Generated prose and decoder diagnostics have no size boundary

AUD-039: Generated-text contract tests duplicate policy across owners

Retained Decisions

RET-001: Keep the application package as the explicit composition owner

RET-002: Keep external dependencies behind repository-owned contracts

RET-003: Keep publication mechanisms separate by artifact contract

RET-004: Keep collection as a narrow application-facing seam

RET-005: Keep report definitions explicit and independently reviewable

RET-006: Keep command and configuration report lookup policies separate

RET-007: Keep civil-day and rolling elapsed-time period policies distinct

RET-008: Keep configured output paths declarative during loading

RET-009: Keep inactive optional integrations free of active-field validation

RET-010: Keep Promptkit profile source precedence in its adapter boundary

RET-011: Keep command-specific parsers around one shared flag core

RET-012: Keep action summaries distinct and bounded by CLI ownership

RET-013: Keep source-specific normalization explicit

RET-014: Keep selected forecast periods structurally intact

RET-015: Keep fact projection shallow under immutable workflow ownership

RET-016: Keep module envelopes separate from briefing policy

RET-017: Keep rich module values and curated prompt exports distinct

RET-018: Keep checked-empty alert modules distinct from missing sources

RET-019: Keep Today planning richer than Daily and Tomorrow planning

RET-020: Keep SPC outlook records separate from selected briefing digests

RET-021: Keep prompt category grouping explicit and serialization normalized

RET-022: Keep neutral prompt execution lifecycle values dependency-owned

RET-023: Keep Promptkit source resolution and prepared handles in the adapter

RET-024: Keep explicit prompt-debug storage separate from normal publication

RET-025: Keep report-specific generated values over shared day-style mechanics

RET-026: Keep semantic typed validation after schema validation

Open Questions

202 KiB

Raw Blame History