Proposed work: standardize gh JSON shape validation across live 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/pr_queue_health.py
• scripts/review_bounty_candidates.py
• scripts/submission_quality_gate.py
• scripts/proposed_work_triage.py

Problem

Several live maintenance scripts already protect gh subprocess execution with timeout and nonzero-exit handling, but JSON shape validation is still inconsistent after json.loads(...).

Some scripts explicitly reject unexpected list/object shapes in certain paths, while other live readers appear to trust decoded JSON structures more directly. That means malformed or surprising gh output can still fail differently depending on which report script is being run.

Evidence

Current examples in the repo:

• scripts/proposed_work_triage.py
  • explicitly raises gh issue list returned non-list JSON
• scripts/check_bounty_issue_states.py
  • validates that public bounty API data is a JSON list
• scripts/check_live_bounty_closing_refs.py
  • validates public API list shape
• scripts/review_bounty_candidates.py
  • decodes gh pr list JSON but does not clearly centralize post-decode shape checks
• scripts/pr_queue_health.py
  • decodes gh JSON and then relies on downstream iteration
• scripts/submission_quality_gate.py
  • decodes multiple gh JSON responses in live context loading

This creates a maintenance gap: live scripts are converging on safer CLI handling, but object/list shape validation is not obviously standardized.

Proposed work

Add a consistent policy for validating decoded gh JSON shapes in live maintenance scripts.

Useful scope could include:

• documenting which commands must return lists vs objects
• adding shared shape checks or helper-level enforcement where practical
• aligning a small set of scripts to fail clearly when gh returns unexpected JSON structure
• adding focused regression tests for malformed decoded JSON

The goal is not to rewrite every script. The smallest useful fix is to make the shape-validation policy explicit and apply it to the current live-report hotspots.

Expected value

This would make live script behavior more predictable, reduce hidden trust in decoded JSON structures, and lower the chance that one script silently accepts malformed gh output while another fails safely.

It also gives maintainers a more consistent rule for future CLI-hardening work.

Reference tier

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

Possible acceptance criteria

• at least some current live scripts explicitly validate expected gh JSON shapes
• malformed object/list responses fail with concise, actionable errors
• regression coverage exists for the chosen scripts or shared helper
• 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 which JSON shapes are validated
• focused malformed-JSON-shape regression tests
• clean diff checks for touched files

Duplicate search

I checked current open proposed-work issues and did not find one specifically about standardizing decoded gh JSON shape validation across live maintenance scripts.

Related but different proposals include:

• #1104 live closing-reference checks in PR readiness
• #978 claim-inventory safety-cap guards
• #1141 live GitHub collection safety-cap policy alignment
• #1140 shared read-only GitHub CLI helper for maintenance scripts

Those are adjacent, but they do not specifically focus on decoded JSON shape validation after successful gh execution.

Out of scope

• broad rewrites of all maintenance scripts
• removal of existing safety caps or timeout handling
• changes to payout, treasury, wallet, ledger, or public API semantics
• speculative price, liquidity, bridge, exchange, or cash-out claims