Skip to content

Document fleetweather.py in ARCHITECTURE.md and TESTING.md - #254

Merged
dmccoystephenson merged 1 commit into
mainfrom
fix/fleetweather-doc-drift
Nov 12, 2026
Merged

dmccoystephenson merged 1 commit into
mainfrom
fix/fleetweather-doc-drift

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Summary

gardener/fleetweather.py and tests/test_fleetweather.py were added in #253, but neither doc that CLAUDE.md's "Documentation sources of truth" table holds to the module set was updated with them:

  • docs/ARCHITECTURE.md: the module tree, which that table says must list every file in gardener/, had no fleetweather.py entry. One has been added after fleetcity.py. The tests/ line's parenthetical list of test subjects had also fallen behind; it stopped at trace_client and left out parpt, reach, broken, doctor, heartbeat, hub, garden3d, fleetcity and fleetweather. It has been replaced with the rule it was trying to list ("every module but __init__.py and __main__.py"), which was checked against the current gardener/*.py and tests/test_*.py files and holds. A rule doesn't go stale every time a module is added, as the list did.
  • docs/TESTING.md: no paragraph described tests/test_fleetweather.py. One has been added after the Fleet City paragraph, written from the test module's actual assertions, class by class.

docs/HUB.md's "Weather (RFC 0032)" section was also checked against fleetweather.py: the env var names, the once-a-minute cache, the programs.json shapes and the failure-as-clear-sky behaviour all match. README.md's new section links to docs/HUB.md#weather-rfc-0032 and to two images that exist. Neither file needed a change.

These are documentation-only changes. No code, dispatch.py, dev_loop.py or prompt template is touched, so the manual dispatch verification doesn't apply, and no "Safety model impact" section is needed.

Test plan

  • Docs-only diff, so python3 -m compileall gardener is unaffected
  • CI (gh pr checks) on the PR head: unit and integration suites. CI is the result to trust here. The sandbox's local python3 is 3.8.10, below pyproject.toml's >=3.10 floor. Locally, 610 tests ran with 13 import errors that come from that interpreter, not from this docs-only diff.
  • Every module named in the new ARCHITECTURE wording was checked to have a matching tests/test_<module>.py

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code


drafted by Claude on behalf of Daniel Stephenson

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dmccoystephenson

Copy link
Copy Markdown
Member Author

Self-review: no blocking issues found.

The code-review skill was run at low effort on this diff. It found nothing, and it noted that it did not check the text against the source. That check was then done by hand:

  • docs/ARCHITECTURE.md — each claim in the new fleetweather.py entry was checked against gardener/fleetweather.py: the GET /api/metrics/window read with a reader credential (fetch_window), the once-a-minute cache (CACHE_SECONDS = 60, Forecaster.window), programs.json in the hub's data directory (load_program_map), one cell per building for /api/city and the still (cells_payload, drawing helpers), and off unless GARDENER_HUB_WEATHER is on (Config.problem). The cross-reference "Hub's 'Weather'" points at docs/HUB.md's ### Weather (RFC 0032) heading.
  • docs/ARCHITECTURE.md tests/ line — the rule "every module but __init__.py and __main__.py" was checked against the current file list. Every other gardener/*.py has a matching tests/test_*.py.
  • docs/TESTING.md — the new paragraph was written by going through tests/test_fleetweather.py one class at a time (TestClassify, TestForecast, TestProgramMap, TestTraceWindow, TestForecaster, TestParseSample, TestHubCityWeather, TestStillWeather). "Ten a second full intensity" matches test_the_mf_power_flood_is_full_intensity (600 a minute gives intensity 1.0). The skip condition for the render test matches its skipUnless(_strata_paths(), ...).

Phase 7 found no other drift from #253. docs/HUB.md's Weather section and README.md's new section and links match the code and the files on disk.

The diff touches no dispatch.py, MODE_SPECS, dev_loop.py or prompt template, so neither dispatch-safety invariant is affected and no manual dispatch verification is owed. CI is green on the PR head: test (3.10), test (3.x), city-still, fleetcity and garden3d.

This comment was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).


drafted by Claude on behalf of Daniel Stephenson

@dmccoystephenson
dmccoystephenson merged commit eef95eb into main Nov 12, 2026
5 checks passed
@dmccoystephenson
dmccoystephenson deleted the fix/fleetweather-doc-drift branch November 12, 2026 02:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant