Stop publishing a plant's taxon id for a bacterium, and gate docs/ (#442)

[realmarcin]

Closes #442.

The gap

generate-pages.yaml publishes the committed docs/ tree verbatim, and nothing regenerated or checked it. A data PR that corrected a record and didn't re-run just gen-html shipped a page contradicting the KB — invisibly, since no schema validator or id↔label gate reads HTML.

It had drifted in both directions:

	count	example
pages asserting ids the record no longer holds	7	MSC1_Dominant_Core and EcoFAB_Ring_Trial_SynCom17 rendered NCBITaxon:169215 — the flowering-plant genus Bosea — as a live NCBI link on a bacterium
records with no page at all	7	SPRUCE_Peatland_Warming_Community, Chlorella_Keystone_Taxa_Antifungal_SynCom, …

The second is the one the issue didn't mention and the more interesting failure: those records were added without a regeneration, so they are simply absent from the published site, and a diff of existing files cannot see it. That's why the gate counts untracked files and why the missing-page test is separate.

KBase_ORT_Workflow_Community_Model was also still showing the class/phylum ids (NCBITaxon:2157/1236) its record replaced in 2a3b691.

The decision the issue asked for

Worth deciding whether docs/ regeneration belongs in CI, or whether these artifacts should stop being committed.

Gate it. The render is 7.35s and deterministic — a clean checkout that runs it produces a byte-identical tree, which I verified before building anything on the assumption. The alternative is "remember to run just gen-html", which is precisely what produced the drift.

Changes

• just check-docs-current — regenerate, fail if the tree differs. Counts untracked files, so a missing page fails too.
• .github/workflows/docs-current.yaml — the CI gate.
• tests/test_docs_do_not_contradict_the_kb.py — the fast local signal. It states the property rather than the mechanism: a page may not assert a taxon id its record lacks. That distinction matters because the gate can only say "re-run the renderer", while a test failure names the contradiction.
• reports/gtdb_denominators.tsv regenerated — the issue's second artifact. The orphaned NCBITaxon:169215 Bosea row is gone and the ORT record's 1033997 is picked up; taxa 578 → 583.

A trap I walked into and fixed

My first draft of the workflow filtered on src/communitymech/render/**. render is a module (render.py), not a package, so that glob matches nothing — a gate that never fires on renderer changes. This is the same mistake as TraitMech#198, called out in label-correspondence.yaml's own header. The paths now name the files, verified against the tree.

Verification

Mutation-checked in both directions:

restore the plant id 169215 into MSC1_Dominant_Core.html
  → FAILED ...test_no_page_asserts_a_taxon_id_its_record_does_not_have[MSC1_Dominant_Core]   (1 failed, 313 passed)
move SPRUCE_Peatland_Warming_Community.html aside
  → FAILED ...test_every_record_has_a_published_page                                          (2 failed, 311 passed)
restored → 314 passed

The gate itself was checked the same way: it exits 1 on the drifted tree and 0 once regenerated docs are committed.

ruff and black clean.

Note

docs/ is a large diff (20 pages modified, 7 added) because it is 312 generated files catching up on accumulated drift. Every change is renderer output — no hand edits.

🤖 Generated with Claude Code

[realmarcin]

Review round 1 — addressed

Both HIGH findings were real and both were about the gate not gating. The review also cleared determinism, write-scope, untracked detection, and the "no hand edits" claim by independent experiment, which is what let me treat the rest as settled.

1 (HIGH) — the gate reported green when the renderer failed. Fixed.

render_all caught each per-record exception, printed a ✗, then printed "✅ Rendered 312" and exited 0. A failed record leaves its previous page in place, so the tree has no diff and check-docs-current reported it current — green in exactly the case where the regeneration it gates on had not happened. >/dev/null then discarded the only evidence.

render_all now returns the failures and prints the true rendered count; the CLI exits 1; the recipe no longer discards output. Reproduced with your case:

$ just check-docs-current      # before: "✅ docs/ matches the KB", EXIT=0
  ✗ MSC1_Dominant_Core.yaml: Object of type date is not JSON serializable
❌ 1 failed to render, so their pages are STALE: ['MSC1_Dominant_Core.yaml']
GATE EXIT=1

Fixing it introduced a bug in my own patch, worth recording: I first put return failed above the _generate_index call, which would have made the browser and landing pages dead code. Caught before commit.

2 (HIGH) — templates/** was in no workflow's paths filter. Fixed.

Correct and the more embarrassing of the two, since the PR body claims to have avoided exactly this. I verified the listed paths existed; I did not verify they covered the renderer's inputs. A one-line edit to community.html rewrites all 312 pages and matched neither this filter nor validate-strict.yaml's src/communitymech/**/*.py. Added src/communitymech/templates/** and paths.py, and the header now says that checking a path exists is not the same as checking the list is complete.

3 (MEDIUM-HIGH) — the set oracle could not see a swap. Rewritten as positional.

This is the best finding in the review. BioModels_MODEL2405300001_Infant_Gut_HMO_SynCom linked Bacteroides ovatus to NCBITaxon:821 — Phocaeicola vulgatus, the row above it. A second live wrong-organism link, the same class as the Bosea case this PR is named after, and my test passed it because 821 is in the record.

I verified the renderer emits taxonomy[].taxon_term.term.id first and in record order — across all 312 pages the record's taxonomy ids are a prefix of the page's NCBI links (301 match exactly; 11 render extra links from interaction participants after the prefix). So the check is now a row-for-row prefix comparison, with the old set check kept for what renders after it.

Confirmed it catches what it previously missed:

restore main's Infant_Gut page
  → FAILED test_the_taxonomy_links_match_the_record_row_for_row[BioModels_MODEL2405300001_Infant_Gut_HMO_SynCom]

Counts corrected to 8 pages in the justfile, the workflow header, and the docstring.

4 (MEDIUM) — orphan pages. Fixed.

gen-html only writes, so a renamed record leaves its page tracked and published with an empty diff. Both the recipe and a new test now catch it; verified with git mv — gate exits 1, test_no_page_survives_its_record fails.

5, 8 — filed, not fixed.

• docs/community_umap.html is stale and published, and the new docs gate does not cover it #478 — docs/community_umap.html is stale (302 ids vs 312 records), published, linked from two pages, and outside this gate. gen-umap is stochastic, so regenerate-and-diff needs a pinned seed; the issue lays out four options and recommends gating coverage rather than coordinates as the cheap first step. You are right that the workflow header and PR body should say which parts of docs/ are gated — the header now does.
• reports/gtdb_denominators.tsv embeds a machine-local mtime, so it cannot be gated by regenerate-and-diff #479 — the denominators report's mtime= header is machine-local, so that file can never be gated this way.

6 (LOW) — noted; two filter paths removed.

browser_export.py and its gitignored docs/data.js are outside what the recipe runs, so I dropped export/browser_export.py from the filter rather than implying coverage. Worth keeping in mind that .gitignore entries under docs/ are structurally invisible to this gate.

7 (LOW) — my transcript was wrong. Corrected.

You are right: the missing-page mutation is 1 failed, 312 passed, not 2 failed, 311 passed — I had both mutations applied at once, and parametrization is collected at import so the moved page removes a param. Timing is ~9.8s on your machine, not 7.35s. Neither changes the conclusion, but the numbers shouldn't be quoted as-is.

---

2264 passed, 16 skipped. ruff, black, mypy src/ clean. just check-docs-current exits 0.