[bot] Add upstream-api-check workflow for AGR API changes

[kltm]

[bot] Opened by a Claude Code agent on behalf of @kltm.

What

Adds a repeatable procedure for checking whether an announced upstream API change affects go-fastapi, and corrects a docstring that had frozen an out-of-date picture of how the Alliance (AGR) communicates those changes.

Three files:

• .claude/skills/upstream-api-check/SKILL.md (new) — an invocable skill that walks the verification: find the announcement, establish which releases are in play, re-inventory our AGR call sites, diff live response key paths between www and the staged next release, run our real parser against that staged release, check the OpenAPI spec for endpoint removals, and confirm the live tests are green.
• AGENTS.md — a new "Upstream API dependencies" section naming what we depend on, where AGR announcements live, and when to run the skill.
• app/utils/mygene_utils.py — docstring correction only, no behavior change.

Why

AGR restructured GET /api/gene/{id} in May 2026 with no warning, which silently broke gene_to_uniprot_from_alliance and surfaced only as CI failures (#159, fixed by #168). Following GO feedback, AGR now pre-announces API changes and stages the next release publicly, so that class of change is catchable before it reaches production — but only if someone knows where to look, which is what this PR writes down.

The docstring added in #168 states that AGR restructured the endpoint "with no public API versioning or deprecation notice (no /api/swagger.json)". Both halves are now misleading. AGR publishes an OpenAPI spec at https://www.alliancegenome.org/openapi?format=json — the /api/swagger.json path we probed simply isn't where it lives — and publishes advance release notes ahead of a release. Leaving that claim in place tells the next person an early-warning system doesn't exist when it does.

The check this encodes, run against AGR 9.1.0

Applying the procedure to the currently-staged release, as a working test of it:

• stage.alliancegenome.org serves 9.1.0 while www serves 9.0.0, so 9.1.0 was diffable today.
• 9.1.0 does not affect go-fastapi. Its API changes are confined to the disease-annotation and phenotype endpoints (pubmedPubModIDs → pubmedPublications, retyped Set<String> → Set<CrossReference>) and to download files. We call neither.
• A full recursive key-path diff of /api/gene/{id} between the two releases is purely additive apart from taxon.species.assembly_curie, which we do not read. The two fields we do read — gene.crossReferences[].referencedCurie and gene.gcrpCrossReference.referencedCurie — are untouched.
• gene_to_uniprot_from_alliance run against the staged release resolves every gene tested, including the load-bearing HGNC:12139 / TRAV39 GCRP-only case from Live-data QC test failures: GOlr annotation_class drift (17) + mygene/Alliance HGNC:12139 lookup (3) #159.

Notably, none of that was derivable from the release notes alone — the #159 reshape was never mentioned in them either, which is why the skill leads with "do not conclude from the notes."

Testing

• tests/unit/test_mygene_utils.py — 25 passed against live AGR and mygene.info.
• ruff check app/utils/mygene_utils.py — clean.
• codespell on all three files — clean.
• Every URL cited in the new docs returns 200.

No test changes: this is documentation plus a docstring, and the existing live tests already cover the code path.

Note for reviewers

A related exposure turned up in another repo while doing this and is tracked separately at geneontology/gopreprocess#78 — that pipeline consumes AGR orthology download files, which are on a different change track and do need action. Out of scope here.

— Posted by Claude Code agent on behalf of @kltm.

🤖 Generated with Claude Code

[kltm]

[bot] Comment by a Claude Code agent on behalf of @kltm.

The red build (3.11) check is pre-existing on main, not caused by this PR

Run 30405216903 reports 7 failed, 142 passed, 1 skipped. I verified these are live-data drift already present on main rather than anything introduced here.

Evidence 1 — the diff contains no executable code. Three files: a new skill markdown, a new AGENTS.md section, and app/utils/mygene_utils.py, where the change is confined to the Note: block of a docstring. git diff main...HEAD -- app/utils/mygene_utils.py touches no statement, no import, and no signature.

Evidence 2 — unmodified main fails the same tests. I checked out main at 9ae1363 into a clean worktree, installed dependencies fresh, and ran the failing files:

FAILED tests/unit/test_bioentity_endpoints.py::TestBioentityEndpoints::test_bioentity_gene_endpoints
FAILED tests/unit/test_bioentity_endpoints.py::TestBioentityEndpoints::test_bioentity_id_endpoints
FAILED tests/unit/test_models_endpoints.py::TestApp::test_bioenty_id_endpoints
FAILED tests/unit/test_slimmer_endpoints.py::TestSlimmerEndpoint::test_slimmer_endpoint_fgf8a
FAILED tests/unit/test_ribbon.py::TestOntologyAPI::test_fly_ribbon

Same set CI flagged on this branch. The failure signatures are data-shaped, not code-shaped: AssertionError: 404 != 200 on live GOlr lookups, and AssertionError: 2 not greater than or equal to 4 on a test_fly_ribbon annotation count.

Evidence 3 — the file this PR actually touches is green. tests/unit/test_mygene_utils.py is 25 passed against live AGR and mygene.info, both locally and in the CI run above.

This is the recurring live-data pattern

Same class as #152 / #153 (GOlr data release), and as #159, which is still open. Note the failing set has shifted since #159 was written — the annotation_class KeyErrors it lists are gone (cleared by #167), replaced by these 404s and a count threshold. So this is a fresh instance of the same recurring problem rather than the exact failures #159 catalogues, and re-baselining it is its own piece of work, separate from this PR.

Worth noting the shape of it: test_bioentity_* and test_slimmer_endpoint_fgf8a both route through gene_to_uniprot_from_mygene, and #138 ("Some HGNC identifiers do not resolve in /bioentityset/slimmer/function route") is open on adjacent ground — so the 404s may be the same underlying identifier-resolution gap rather than pure threshold drift. I have not run that down.

This PR can be reviewed on its own; it cannot affect these results.

— Posted by Claude Code agent on behalf of @kltm.