weatherreporter/docs/roadmap/audit.md

# Repository Audit Ledger

Status: In progress; Stages 1-3 complete.

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

## 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. 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 | Pending |
| 5 | Audit CLI parsing, wiring, and output contracts | Pending |
| 6 | Audit weather data acquisition and collection | Pending |
| 7 | Audit forecast and fact derivation | Pending |
| 8 | Audit module contracts, registry, and source-facing briefing modules | Pending |
| 9 | Audit derived, planning, formatting, and SPC briefing modules | Pending |
| 10 | Audit prompt inputs, assets, and neutral execution contracts | Pending |
| 11 | Audit Promptkit adaptation and secure prompt debugging | Pending |
| 12 | Audit generated-text validation and catalog contracts | Pending |
| 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` | 4 | Pending |
| CLI parsing, output, and exit behavior | `internal/cli` | 5 | Pending |
| Weather transport and normalized collection | `internal/adapters/weatherapi`, `internal/collect`, `internal/weatherdata` | 6 | Pending |
| Forecast and fact derivation | `internal/forecast`, `internal/facts` | 7 | Pending |
| Module and briefing contracts | `internal/module`, `internal/briefing` | 8-9 | Pending |
| Prompt inputs, embedded assets, and execution contracts | `internal/promptinput`, `internal/promptassets`, `internal/promptexec` | 10 | Pending |
| Promptkit boundary and sensitive debug output | `internal/adapters/promptkit`, `internal/promptdebug` | 11 | Pending |
| Generated-text validation | `internal/generatedtext` | 12 | Pending |
| 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

## 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.

## 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 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.