Proposed work: consolidate read-only GitHub CLI helper for 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/claim_inventory.py
• scripts/proposed_work_triage.py

Problem

Several read-only maintenance scripts still implement their own GitHub CLI subprocess wrappers for JSON loading, timeout handling, command-failure formatting, and missing-gh behavior. The project has already accepted multiple narrow cleanup PRs in this area, which suggests the repeated wrapper logic is still a maintenance hotspot.

That duplication makes future fixes slower and easier to miss. When one script gets a better gh error path or Windows-safe decoding behavior, the same improvement often still has to be repeated in other scripts by hand.

Evidence

Current duplicated gh/subprocess handling appears across multiple scripts, including:

• 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/claim_inventory.py
• scripts/proposed_work_triage.py

There is also recent bounty history showing repeated narrowly-scoped fixes around the same theme, for example missing-gh handling and related live-mode CLI robustness work in bounty #936.

Proposed work

Introduce a shared helper for read-only GitHub CLI execution used by maintenance scripts.

Useful scope could include:

• one shared helper for gh JSON commands with timeout, UTF-8 decoding, and consistent failure messages
• optional support for read-only non-JSON commands where needed
• migration of a small set of existing scripts to the helper
• regression coverage proving shared behavior stays consistent

The goal is not a broad rewrite. The smallest useful version is a reusable helper plus a few representative adopters.

Expected value

This would reduce repeated maintenance work, make future CLI-hardening fixes land once instead of many times, and lower the chance that one live script keeps older error behavior after another script has already been fixed.

It should also make review easier because maintainers can reason about one shared read-only gh execution path instead of many near-duplicates.

Reference tier

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

Possible acceptance criteria

• a shared helper exists for read-only GitHub CLI execution
• at least some current duplicated maintenance scripts adopt it
• timeout, missing-gh, nonzero-exit, and JSON-parse behavior are covered by focused regression tests
• no public API, ledger, wallet, treasury, payout, or bounty-lifecycle behavior changes
• script outputs remain intentionally compatible or are explicitly documented where changed

Evidence or tests required

• focused tests for the shared helper behavior
• before/after explanation naming the scripts deduplicated
• command output for the affected test files
• clean diff checks for touched files

Duplicate search

I checked the current open proposed-work issues list and did not find an open proposal specifically for extracting a shared read-only GitHub CLI helper across maintenance scripts.

Related but different open issues include:

• #1104 proposed running live bounty closing-reference checks in PR readiness
• #1111 proposed template text smoke checks
• #1107 proposed PR wording guardrails

Those are separate workflow or validation proposals, not a shared CLI-helper consolidation proposal.

Out of scope

• broad rewrites of all scripts at once
• changes to payout, treasury, wallet, ledger, or public API semantics
• private tokens, secrets, or admin-only execution paths
• speculative pricing, liquidity, bridge, exchange, or cash-out claims