fix: gh が使えないとき運用レポートは劣化して出力される (#420)

[01rabbit]

Closes #420.

欠陥は 2 つあり、後者のほうが危険だった

1. 未捕捉の FileNotFoundError

gh 不在時、例外は subprocess.run の戻り値ではなく呼び出し自体から送出される。周囲の except ValueError は最初から到達できなかった。main の版で再現:

修正前: FileNotFoundError: [Errno 2] No such file or directory: 'gh'

2. 捕捉後、不在が健全として読まれていた

取得失敗で issues が空になり、open_issues が 0 件として扱われ、overall_state が freeze-ready に到達し得た。外部照会が落ちたことを理由に、レポートが最も強い判定へ昇格する経路である。

リポジトリにコミットされている docs/issues/bhusa-2026-vegas-readiness/15-status.md が現にこの出力を持っている（この PR では再生成していない。生成物の更新は操作者の行動であり、テスト実行の副作用として入れるべきものではない）:

-- GitHub open child issues: `0`          ← 照会は一度も成功していない
+- GitHub child issue state: `unavailable`
+- GitHub open child issues: `unknown`

決定

項目	内容
例外	GitHubUnavailable に一本化。ValueError（必須ローカル検査の失敗）とは別の型にする
理由の語彙	gh_not_installed / gh_not_executable / gh_timed_out / gh_not_authenticated / gh_rate_limited / gh_failed / gh_returned_unparseable_output
件数	未取得は 0 ではなく None、描画は unknown
freeze-ready	availability == "available" を要求
ok	必須のローカル検査の成否。任意 source の不在では false にしない
strict mode	--require-github のときのみ ok=false と終了コード 3（2 は「レポートを作れない」）
limitations[]	reason / detail / observed_at を残し text・markdown 双方に出す
timeout	gh 照会に 20 秒。timeout のない任意 source は任意ではない

理由を畳まないのは、操作者の次の行動が異なるためである。CLI の導入、認証情報の更新、rate limit の待機は別の作業であり、「gh が失敗した」だけのレポートは読み手に調べ直させる。

生存した変異と、その原因

W3（FileNotFoundError ハンドラの削除）が最初の走行で生存した。

OSError はその上位クラスであり、下の一般ハンドラが gh_failed として飲み込む。そしてわたくしのテストは、gh が入った runner でも通るよう理由の集合を緩く受け入れていた。結果として、CLI を持たない機械に「CLI の失敗を調査せよ」と告げる分岐が無防備に残っていた。

修正として、理由の固定は環境に問わず _run_command を差し替えて行うテストに分けた。周囲の環境に聞くテストは「何も漏れないか」だけを問い、それはどこで走っても真である。

変異	結果
W1 未取得を 0 件として数える	2 件失敗
W2 freeze-ready の availability 条件を外す	1 件失敗
W3 FileNotFoundError ハンドラ削除	初回生存 → テスト追加後 1 件失敗
W4 認証失敗を一般失敗に畳む	3 件失敗
W5 未取得でも ok=False（任意性の否定）	4 件失敗
W6 strict の終了コードを 2 に潰す	1 件失敗
W7 PermissionError ハンドラ削除	1 件失敗
W8 timeout を渡さない	1 件失敗
W9 非配列 JSON を空として通す	1 件失敗

副次的な結果

gh 不在が原因で main で失敗していた BHUSA 系 12 件が通るようになった。 bhusa-report が終了コード 2 を返していたためである。

main:      12 failed, 828 passed
この PR:   863 passed, 4 skipped, 70 subtests passed
compileall（CI と同じ静的検査）: OK

範囲外として記録する点

テスト実行が docs/issues/bhusa-2026-vegas-readiness/ 配下の生成物を書き換える（--write-status-doc の既定パスがリポジトリ内を指すため）。この PR では毎回 revert した。別の欠陥であり、この PR を広げない。

🤖 Generated with Claude Code

https://claude.ai/code/session_01SsboPSj6GyJju6mTXwHHjq

---

Generated by Claude Code