From 6d2c09765799ec6fb0037d1f099d5cfdfe1fc8b8 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 12 Aug 2026 15:03:01 +0000 Subject: [PATCH] Establish the repository audit baseline --- docs/roadmap/audit.md | 229 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100644 docs/roadmap/audit.md diff --git a/docs/roadmap/audit.md b/docs/roadmap/audit.md new file mode 100644 index 0000000..c825083 --- /dev/null +++ b/docs/roadmap/audit.md @@ -0,0 +1,229 @@ +# Repository Audit Ledger + +Status: In progress; Stage 1 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. No audit +finding or retained decision was established during baseline collection. +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 | Pending | +| 3 | Audit report identity and time foundations | Pending | +| 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 | Pending | +| Report identity, periods, dates, and timezones | `internal/report`, `internal/timeutil` | 3 | Pending | +| 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 + +No findings were recorded in Stage 1. A passing baseline is not evidence that +later audit scopes have no findings. + +## Retained Decisions + +No retained decisions were recorded in Stage 1. + +## Open Questions + +No Stage 1 open questions or unexplained baseline failures remain. Later +stages may add scoped questions according to the audit plan. + +## 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.