Every piece of this pipeline already existed -- generate_all_docs.sh,
generate_api_manifest.py, api_delta.py (with its --site-dir page resolver and its
--format gitea checklist), and the site's build_reference.py / build_library.py,
which already knew how to read this repo. Nothing chained them. So the site's
generated reference sat 26 engine commits behind, stamped verified_commit b6720f6,
and nothing noticed or could have noticed.
make docs regenerate man page, API reference, stubs, manifest
make stamp-snippets re-run the docs snippets; stamp what actually happened
make check-snippets CI gate: fail on a broken snippet or a stale stamp
make api-delta what changed, and which site pages that obligates
make release-docs all of it, for cutting a tag
release-docs deliberately does not commit and does not touch the hand-written
pages. It refreshes what is derived, proves the published samples still run,
rebuilds the site's generated half against this engine, and prints the checklist of
curated pages the API change obliges you to revisit. The judgment stays with a
human; only the mechanical parts are mechanical.
Two ref-shaped traps, both hit while building this:
* BASE_REF and RELEASE_REF are different refs and I had conflated them. The delta
is measured FROM the previous release; the site's source links are pinned TO the
tag being cut. One variable could not be both.
* api_delta now distinguishes "this ref predates the manifest" from "this ref is
broken". 0.2.8 is older than the manifest infra (54624b3), so it has no baseline
-- every object would read as "added", which is noise, not a delta. It says so
and exits clean. An unknown ref is still an error.
stamp_snippets --check compares only the CLAIMS a header makes (status, objects),
never `verified`. That field records the engine a snippet was last confirmed
against -- provenance, not a freshness assertion. Had --check demanded it equal
HEAD, every commit would have invalidated all 130 stamps and the gate would have
cried wolf until people stopped listening.
Running it regenerated all 52 reference pages against the current engine, which
cleared every stale UIGrid / compute_astar / gridstate mention the docs audit found
in the generated tree -- the engine's docstrings had been right for weeks; the site
had simply never been rebuilt.
John McCardle
50d6f1e5d2