230 lines
12 KiB
Markdown
230 lines
12 KiB
Markdown
# 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.
|