Proposed work: standardize public API response-shape validation across maintenance scripts

[SueJianjian]

Related bounty or source issue

Bounty #932

Related current sources:

• scripts/check_bounty_issue_states.py
• scripts/check_live_bounty_closing_refs.py
• scripts/claim_inventory.py
• scripts/submission_quality_gate.py
• scripts/proposed_work_triage.py

Problem

Maintenance scripts that read the public MergeWork API do not currently validate response JSON shapes in a consistent way.

Some paths explicitly fail when a response is not the expected top-level list shape, while other paths accept partial structures, silently skip unexpected sections, or rely on downstream checks after decoding. That makes live operational tooling harder to reason about and can hide API-shape regressions differently depending on which script is running.

Evidence

Current examples in the repo:

• scripts/check_bounty_issue_states.py
  • _load_public_bounties() raises expected a JSON list
• scripts/check_live_bounty_closing_refs.py
  • _load_public_bounties() also raises expected a JSON list
• scripts/claim_inventory.py
  • load_public_api_state() accepts partial shapes and only keeps fields when they happen to match the expected structure
• scripts/submission_quality_gate.py
  • loads public API bounty data in live context with separate shape assumptions
• scripts/proposed_work_triage.py
  • uses HTTP JSON reads for live proposal collection, with its own validation path

This means 鈥減ublic API shape problems鈥?are not handled under one clear policy across the scripts that depend on public data.

Proposed work

Define and implement a consistent shape-validation policy for public MergeWork API responses used by maintenance scripts.

Useful scope could include:

• deciding which endpoints must fail fast on wrong top-level shape
• documenting when partial acceptance is allowed vs not allowed
• aligning a small set of scripts to use the same policy
• adding focused regression tests for malformed API response shapes

The goal is not to rewrite the public API. The goal is to make maintenance scripts react consistently to malformed or surprising response shapes.

Expected value

This would make live tooling more predictable, reduce silent partial-data behavior where it is unsafe, and make future public API hardening work easier to apply consistently across scripts.

Reference tier

100-500 MRWK: useful issue, test, docs page, small bugfix

Possible acceptance criteria

• maintainers can point to one clear rule for public API shape validation in maintenance scripts
• at least some affected scripts align to that rule
• malformed response shape handling is covered by focused regression tests
• no public API, ledger, wallet, treasury, payout, or bounty-lifecycle behavior changes

Evidence or tests required

• links to the affected scripts
• before/after explanation of the chosen shape-validation policy
• focused malformed-response regression tests
• clean diff checks for touched files

Duplicate search

I checked the current open proposed-work issues and did not find one specifically about standardizing public API JSON shape validation across maintenance scripts.

Related but different proposals include:

• #1140 shared read-only GitHub CLI helper for maintenance scripts
• #1141 live GitHub collection safety-cap policy alignment
• #1142 decoded gh JSON shape validation across live maintenance scripts

Those focus on GitHub CLI and live collection behavior, not public API response-shape consistency.

Out of scope

• public API redesign
• broad rewrites of all maintenance scripts
• changes to payout, treasury, wallet, ledger, or user-facing semantics
• speculative price, liquidity, bridge, exchange, or cash-out claims