fix(docs): stop advertising a superseded Flow release

[abrichr]

What was wrong

openadapt-flow 1.24.0 published at 2026-07-27T03:58Z. Five sentences live on docs.openadapt.ai — including one on the security-review page — still asserted that the live runner and compiler report "the published Flow 1.23.0 identity".

Verifying changed the fix

The obvious correction is 1.23.0 → 1.24.0. That would have been wrong. The managed runtime really is pinned to 1.23.0:

• openadapt-cloud runner/runtime-version.json records openadapt_flow: 1.23.0, wheel sha256 b5d10dfc294479866d6dddd4c1a6afc9164414f0634703173b7e440dc0133bec — the same digest the stale platform manifest carried.
• https://app.openadapt.ai/api/health/ready returns ready: true, mode: live, runner and compiler reachable.

So the number was right; the word "published" is what became false. Bumping to 1.24.0 would have replaced a stale claim with a fabricated one. The sentences now read "the pinned managed-runtime 1.23.0 identity".

Corrected at docs/concepts/deployment-matrix.md:104, docs/guides/hosted.md:35 and :61 (the reported location missed the second one), docs/guides/security-review.md:129, docs/get-started/what-works-today.md:69.

Changelog

docs/changelog.md had a v1.24.0 row whose only content was _This release is published under the MIT License._ — the boilerplate python-semantic-release puts at the top of every release body in every repository. summarize_body returned it as the summary and dropped the actual notes. It now skips that sentence, and the regenerated changelog carries the real change categories (flow v1.24.0 → Bug Fixes, launcher v1.9.0 → Chores, v1.8.0 → Build System, …). 20 rows gained real content.

Making recurrence impossible

docs/published-version-claims.json records every version number the docs state and what kind of claim it is:

kind	meaning	enforcement
pypi-latest	asserts the current published release	compared to PyPI daily
pinned-deployment	a version something is deliberately pinned to	must not be reworded into a publication claim
historical	the version a retained measurement was taken on	frozen forever

scripts/check_published_version_claims.py enforces it, stdlib only.

Offline half — every PR, via ci.yml: registered claims must still appear verbatim where recorded (a reword cannot quietly turn a pin into a publication claim); no authored page may contain a published X.Y.Z-shaped sentence that is not declared to track PyPI; the changelog parses.

Daily half — published-version-claims.yml: every tracking claim, and the newest vX.Y.Z entry in each tracked changelog section, is compared to PyPI. This drift originates in another repository, so no PR can catch it — only a schedule can.

Docs behind PyPI fail. Docs ahead (GitHub release published, PyPI upload not landed) warn, as does an unreachable index — a guard that goes red for reasons unrelated to its subject stops being read, which is exactly how the sibling manifest drift survived. A failed scheduled run files or updates an issue rather than leaving a red dot on a repo nobody has open.

Proof it fails when it should

tests/test_published_version_claims.py — 19 tests. It fails on a simulated future release (1.24.0 documented, 1.25.0 published), on the exact sentence that shipped, on four publication-claim phrasings, and on a registry that has detached from the docs; it passes the corrected pinned/historical wording and warns rather than fails on a not-yet-uploaded release.

Replayed against the pre-fix origin/main docs tree, the offline scan alone returns 5 errors:

docs/concepts/deployment-matrix.md:104: unregistered publication claim 'published Flow 1.23.0'
docs/get-started/what-works-today.md:69: unregistered publication claim 'current published 1.23.0'
docs/guides/hosted.md:35: unregistered publication claim 'published 1.23.0'
docs/guides/hosted.md:61: unregistered publication claim 'published 1.23.0'
docs/guides/security-review.md:128: unregistered publication claim 'published Flow 1.23.0'

Verification

pytest tests/ -q → 98 passed. validate_docs.py → Validation passed. mkdocs build --strict → clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NyCHrzA1psrKMFfroYbzaM