progress-record.sh が gh の失敗時に理由を出さず終了コード 0 で終わり、工程の記録が黙って抜ける #671

何を見つけたか

progress-record.sh は、gh issue view か gh issue edit が失敗すると、何も出力せず終了コード 0 で終わる。 issue の本文は更新されず、呼び出し側からは記録できなかったことが見えない。

progress-tracking の SKILL.md の「何もしない条件」は、「理由を 1 行出して終了コード 0 で終わる」と定めている。スクリプトはこの 1 行を出さない。

# plugins/ndf/scripts/progress-record.sh
gh issue view "$ISSUE" --repo "$REPO" --json body -q .body > "$BODY_FILE" 2>/dev/null || exit 0   # :131（--repo なしは :133）
gh issue edit "$ISSUE" --repo "$REPO" --body-file "$NEW_FILE" >/dev/null 2>&1 || exit 0           # :236（--repo なしは :238）

2026-09-15 に GitHub の GraphQL が graphql_rate_limit を返していた間、次の 5 工程を呼んだ。どれも出力 0 行・終了コード 0 で、issue #660 の「## 進行」は更新されていなかった。

• 完了判定
• Pull Request
• 後片付け
• 配布
• 体裁レビュー

制限が解けた後に同じコマンドを実行し直すと、#660 進行 = <工程> が出て本文に反映された。

develop（f19c7d258、ndf 10.17.70）でも同じである。標準エラーへ graphql_rate_limit を書いて 1 で終わる偽の gh を PATH の先頭に置き、progress-record.sh 660 完了判定 --repo devbasex/ai-plugins を実行すると、出力 0 行・終了コード 0 で終わる。外側の錠（:119-123）の NOTE: も、内側が 0 で終わるため出ない。

どこで見つけたか

• plugins/ndf/scripts/progress-record.sh:131-133 / :236-238
• issue note 記事「人間がやってた開発フローを全部Skill化した」を執筆する #660 の工程の記録（ndf 10.10.1、develop の現行版でも同じ行）

なぜこの変更の範囲外なのか

#660 は note 記事の執筆で、進行記録のスクリプトは受け入れ条件にも対象範囲にも含まれない。

直さないと何が起きるか

• GitHub の上限中に進めた工程が、issue のチェックリストに穴として残る。穴は「工程を飛ばした」ことと区別できない
• 呼び出し側は記録できたと読み、後から記録し直す契機が無い

直し方

• 理由の 1 行（stderr）はすぐ直す。 SKILL.md の「理由を 1 行出す」に合わせる
• 終了コードの意味（0 のままか、基盤: スクリプトの結果 JSON・終了コード・承認関門の提示を共通の契約にする #846 の契約に合わせるか）は決まっていない。 progress-record.sh は本文の節の差し替えを lib/gh_sections.py の replace_section へ寄せた（振り返りが本文末尾へ足す URL の 1 行を、progress-record.sh の節の差し替えが消す #659）が、取得と書き込みは今も gh issue view / gh issue edit（GraphQL）を直に呼ぶ。lib/gh_parts.py の部品（gh_rest は REST で読み書きし、上限なら GraphQL で代わる。上限の見分けは gh_quota）へ寄せれば、GraphQL の上限だけで記録が抜けることも減る。GitHub の呼び出しをどこへ集めるかは NDF のスクリプト全体をモデル・クラスの設計からやり直し、分割と重複の整理を 1 回で行う #1142 が決める

本文の書き換えより前に、ローカルの通過記録（wf_record_progress、:115。#725）を積む。gh が失敗しても通過記録は残るが、issue の「## 進行」の穴と、理由が出ないこと・終了コード 0 は残る（上の偽の gh で再現）。

関連

• 基盤: スクリプトの結果 JSON・終了コード・承認関門の提示を共通の契約にする #846（閉じた） — スクリプトの結果 JSON・終了コードの共通の契約。「読めなかったことを『一致』『0 件』と読ませない」と同じ向き
• 基盤: PR / issue の取得と本文の節の差し替えを共通の部品にする（pr-info・unresolved-threads・body-section） #849（閉じた） — PR / issue の本文の節の差し替えを共通の部品にする（body-section）

由来

issue #660

錠の仕組みとの関係

本文の読み書きは gh_parts.py body-lock の錠の中で走る（progress-record.sh:119-123、#1241）。外側は内側が 0 以外で終わったときだけ NOTE: を 1 行出し、自分は 0 で終わる。内側の gh issue view / gh issue edit の失敗を 0 以外で返せば、理由の 1 行と外側の終了コード 0 の両方を今の仕組みのまま満たせる。GraphQL の上限で抜ける根本（GitHub の読み書きが gh_parts の gh_rest / gh_quota を通らない）は #1142 の範囲である。

受け入れ条件

• 標準エラーへ graphql_rate_limit を書いて 1 で終わる偽の gh を PATH の先頭に置き、progress-record.sh 660 完了判定 --repo devbasex/ai-plugins を打つと → 標準エラーに理由（gh issue view が失敗したことと gh の出力の要点）を 1 行以上出し、結果を lib/README.md の「手順のスクリプトの結果」の形で ok 以外（stopped）として返す
• gh issue view は通り gh issue edit だけが失敗する偽の gh でも → 同じく理由を出し、ok 以外を返す。#660 進行 = 完了判定 は出さない
• 終了コードは「直し方」の未決の論点（0 のままか、基盤: スクリプトの結果 JSON・終了コード・承認関門の提示を共通の契約にする #846 の契約に合わせるか）を設計で決め、その値をテストで固定する。どちらに決めても、上の 2 つで理由と ok 以外の結果は出る
• 退行しない: gh が通るときは → 今と同じく #660 進行 = <工程> を出して本文の「## 進行」を書き換える。本文が変わらないときは gh issue edit を呼ばない。gh が失敗しても wf_record_progress の通過記録は 1 回だけ積まれる

修正レイヤー

親 #2227（全工程の結果を統一した JSON レポートにし、失敗・未収束・未記録を ok で返さない）。シェルのスクリプトが結果の共通形式（lib/README.md の「手順のスクリプトの結果」）を通らないことが根である。gh の失敗では stopped と理由を返す。偽の gh（標準エラーに graphql_rate_limit・終了コード 1）を PATH の先頭に置くと、progress-record.sh 660 完了判定 --repo devbasex/ai-plugins は今も出力 0 行・exit 0 で終わる。

進行

モード: — / 進め方: auto

• 要求と受け入れ条件
• 作業場所の用意 — 2026-10-31 03:59
• 設計
• 素材の収集と出典の確定
• ドキュメント再構成
• ドキュメントレビュー
• 計画 — 2026-10-31 03:58
• 実装 — 2026-10-31 05:46
• 構造改善 — 2026-10-31 07:37
• 実装レビュー — 2026-10-31 09:12
• 完了判定 — 2026-10-31 05:48
• Pull Request — 2026-10-31 06:00
• 確定仕様化 — 2026-10-31 10:59
• 後片付け — 2026-10-31 10:57
• 配布 — 2026-10-31 10:33
• 体裁レビュー
• リリース後テスト — 2026-10-31 10:56
• 振り返り — 2026-10-31 11:00
• 棚卸し — 2026-10-31 11:21

振り返り: #2282 (comment)