上限と再試行の方針を 1 つの宣言に集め、同じ失敗の打ち直しを止める #2343

大方針 #2335（異常系・ログ・回復とデータ・入出力の形を 1 つの実行の核へ集める）の柱の 1 本。子の課題は、この柱の仕組みがそろえば解消する可能性があるものである。

具体例

2026-10-31 の本番の配布のプランで、release のステップが同じ CI の失敗（run 38353378585 の runtime-smoke (agy)）で落ち続けた。プランの判定役（judge）は 7 回とも「外部の待ちの揺れなので同じステップをもう一度」と返し、ステップの上限まで 366 秒、同じ失敗した run を読み直した（#1983）。打ち直しの回数は数えていたが、原因が前回と同じかは誰も見ていなかった。

2026-10-30 には、cross-refactoring の最終ゲートの CI の待ちが、上限 1154 秒のうち 112 秒を残して「結論を得られない」で終わった。同じコミットのチェックはすべて成功していた（#2224）。待ちの部品が、上限の時刻に最後の照会を打たずに止まるためである。

どちらも、上限と再試行の値と止め方が、それぞれの部品の中に書かれていることから起きる。この課題が終わると、上限と再試行の方針は 1 つの宣言から読まれ、同じ原因の打ち直しは決まった回数で止まり、止まった理由が結果に出る。

依頼（原文）

この課題の題と本文（「何をするか」「受け入れ条件」「進め方」）は、起票者（課題を書いた AI）が 2026-11-01 に #2335 の組み直しの記録として書いた文で、利用者の指示の原文として扱わない。利用者の指示の原文は、#2335 が引用した次の指摘である。

異常系処理とログ出力、異常時の回復処理が統一されていないから起こる不具合・課題が多い。1 件ずつ対処してもきりがない

内部データ構造と出力のフォーマットの不統一の影響も大きそう

NDF は Skill の Script 化から発展してきたため、内部データ構造や入出力契約がほぼ整理されていない

出力だけでなく入力もそろえるべき

（書き手: 利用者、日付: 2026-11-01。#2335 の「調べ方」の節が引用した指摘）

解釈: 利用者が求めているのは、異常時の回復処理を NDF 全体でそろえ、同じ型の不具合を 1 件ずつではなく型ごとに無くすことである。この課題はそのうち「待ちと上限」の型（#2335 の型 D）を受け持つ。上限と再試行の値の置き場を 1 つにし、回復の手段である再試行を 1 つの部品にそろえる。

起票者の推定

題・本文のうち、上の利用者の原文に無く、起票者と要求の工程が推して足した条件。S1〜S4 は課題の本文の起票者、S5〜S10 は要求の工程（2026-11-04）が人へ問わずに最も筋の通る案として選んだ。承認ゲート 1 で利用者が確かめるまで、利用者の決定として扱わない。

目的

• NDF のスクリプトが、上限の値と再試行の回数・間隔をそれぞれ自分で持たずに済む状態にする。値を変えるときに直す場所が 1 つになり、入口の契約から上限をたどれる
• 同じ原因の失敗を上限まで打ち直さない。打ち直しが結果を変えないと分かった時点で止まり、止まった理由（原因と回数）が結果に残るので、人へ戻ったときに追い直さずに済む
• 待ちが宣言した上限を使い切ってから止まる。上限より前に「結論を得られない」で止まらない

前提

• 前提 1: この柱は、異常系・ログ・回復とデータ・入出力の形を 1 つの実行の核へ集め、異常系の課題 103 件を型ごとにまとめて解く #2335 の柱 P1（結果の契約をそろえ、失敗・未収束・判定できないを ok で返す経路を無くす #2337 結果の契約と核のスケルトン）と P3（実行の持ち主と後片付けを核に持たせ、残骸と並行の衝突で止まらないようにする #2342 持ち主・後片付け・並行）が入った後に設計と実装を行う（異常系・ログ・回復とデータ・入出力の形を 1 つの実行の核へ集め、異常系の課題 103 件を型ごとにまとめて解く #2335 の設計の「柱の順序」）。2026-11-04 の時点で 入口・受け渡しのファイル・設定・環境変数の契約を 1 か所に宣言し、宣言の外を検査で落とす #2336（P0）は閉じ、結果の契約をそろえ、失敗・未収束・判定できないを ok で返す経路を無くす #2337・実行の持ち主と後片付けを核に持たせ、残骸と並行の衝突で止まらないようにする #2342 は開いている。リポジトリに実行の核（run_core）はまだ無い（ls plugins/ndf/scripts/lib に無い）

• 前提 2: 上限の宣言の置き場は plugins/ndf/contracts/limits.json、読み手は plugins/ndf/scripts/lib/limits.py とする（異常系・ログ・回復とデータ・入出力の形を 1 つの実行の核へ集め、異常系の課題 103 件を型ごとにまとめて解く #2335 の設計の決定 13）。limits.py が今持つ工程 × 担当の表と順序のチェック（無進捗の許容 < 監視の上限 < CLI の上限）は、宣言を読んで同じ判定をする

• 前提 3: 宣言の値を利用者が上書きする経路は、異常系・ログ・回復とデータ・入出力の形を 1 つの実行の核へ集め、異常系の課題 103 件を型ごとにまとめて解く #2335 の柱 P8（入口の引数・環境変数・設定の受け取り方を 1 つの読み込み部品にそろえる #2341 入力の契約）の解決の順（引数 → 環境変数 → 設定 → 既定値）に従う。宣言が持つのは既定値で、上書きの経路はこの柱で新しく作らない

• 前提 4: 直書きの検査の対象は、テスト（tests/ と test_*.py）と実験版（plugins/ndf/scripts/experimental/）を除く plugins/ndf/ の Python のコードとする。hook（plugins/ndf/scripts/hook_lib/ など）も対象に入る。hook は核を通らない（異常系・ログ・回復とデータ・入出力の形を 1 つの実行の核へ集め、異常系の課題 103 件を型ごとにまとめて解く #2335 の対象範囲の「含まない」）が、値は核を通さずに limits.py から読む

• 前提 5: 子の課題は次の 9 件とする。型 D の残り 4 件（conductor が出力ファイルを確かめる回数が移行後に 15 回から 1,185 回へ増え、conductor の費用の 12.7% を占める #1872・conductor が NDF のスクリプトをシェルでつないで待つと、hook が止めてプランと wait を案内する #1919・PR の pytest が 1 回 10〜13 分かかり、push のたびに古い実行も止まらず走り直す #2154・構造改善の持ち越し: 周回 l20261031-2（#2206 #2186 #2216）の範囲に cross-refactoring を通す #2251）は別のマイルストーン（31・32・29）にあり、この柱では扱わない

  課題	題の要旨	2026-11-04 の状態
  relay: ndf-next と同じ応答に書いた質問を待たずに会話を切り替える #1286	relay が ndf-next と同じ応答の質問を待たずに会話を切り替える	開いている
  cross-review: 修正担当（claude -p）がテストを背景で起動して通知を待ったまま終わり、結果ファイルを書かない #1734	cross-review の修正担当がテストを背景で起動し、通知を待ったまま結果ファイルを書かずに終わる	開いている
  test_external_ai_run の codex の成功ケースが CI でだけまれに落ちる #1735	test_external_ai_run の codex の成功ケースが CI でだけまれに落ちる	開いている
  本番の配布のプランで judge が同じ CI の失敗に打ち直しを 7 回返し、上限まで同じ run を読み直す → 同じ失敗が続いたら止めて人へ戻す #1983	本番の配布のプランで、判定役が同じ CI の失敗に打ち直しを 7 回返す	開いている
  test_usage_capture: 負荷が高いときだけ test_runtime_specific_usage_shapes が落ちる #2093	負荷が高いときだけ test_runtime_specific_usage_shapes が落ちる	開いている
  cross-refactoring: 着手前のテストが上限の近くで通ると、範囲テストの雛形の試走の残り時間が数秒になり init が止まる #2158	着手前のテストが上限の近くで通ると、範囲テストのテンプレートの試走の残りが数秒になり止まる	開いている
  cross-refactoring: 既定の予算を固定の分数でなく、テストの所要とコード量から決める #2202	cross-refactoring の既定の予算をテストの所要とコード量から決める	2026-11-03 に閉じた（not planned）
  cross-refactoring: 最終ゲートの CI の待ち（予算 30 分のうち 13.4 分）を想定最大時間の勘定から外し、別の上限で待つ #2203	cross-refactoring の最終ゲートの CI の待ちを想定最大時間の勘定から外す	2026-11-03 に閉じた（not planned）
  待ちの部品 wait_until が上限の時刻に最後の照会を打たず、上限の最大 2 分前に CI 待ちを打ち切る #2224	待ちの部品 wait_until が上限の時刻に最後の照会を打たず、最大 2 分前に打ち切る	開いている

• 前提 6: 「再試行の関数」は、失敗した同じ呼び出しを、同じプロセスの中で間隔を置いて打ち直す関数を指す。次は再試行の関数に当たらない

  • 名前に retry を含むが打ち直しのループを持たない関数: cross-review の _retry_unmatched_scope（次のラウンドへ進める出口）、cross-refactoring の push_with_retry_marker（次の起動で push をやり直すための印）。2026-11-04 に本文を読んで確かめた
  • 条件が揃うまで問い合わせる待ち（プロセスの終わり・ロックの取得・CI の結論・GitHub の上限の回復の時刻）。待ちは受け入れ条件 6 が扱う

• 前提 7: 2026-11-04 に同じ数え方（grep -rnE "timeout=[0-9]"、テストと実験版を除く、plugins/ndf/scripts と plugins/ndf/skills）で打ち直すと 20 か所あった。上限・再試行・待ちの間隔の名前を持つ定数に数字を入れた行（grep -rnE "^[A-Z_]*(TIMEOUT|RETRIES|RETRY|MAX_WAIT|INTERVAL|BUDGET)[A-Z_]* *(:[^=]*)?= *[0-9]"）は 40 か所あった。数は受け入れ条件の判定に使わない。判定は構造チェックが落とすかで行う

• 前提 8: シェルのスクリプトの上限の直書き（2026-11-04 に 4 か所。statusline.sh の timeout 1、progress-record.sh と workflow-common.sh の ${…:-<数字>}、wait-review.sh の説明）を検査に入れるかは設計で決める（未決 2）。statusline.sh は表示のたびに動くため、Python を起動して宣言を読むと表示が遅れる

対象範囲

含む:

• 上限の宣言（plugins/ndf/contracts/limits.json）を作り、limits.py の表と、各部品の上限・再試行の回数・待ちの間隔の既定値をそこへ移す
• 構造チェック（scripts/check-script-structure.py）に、上限・再試行の数字のリテラルの検査と、lib/waits.py の外の再試行のループの検査を足す
• 再試行のループを持つ関数（2026-11-04 の時点で supervise_lib/paths.py の _add_worktree_with_retry、lib/post_queue.py の retry など）を lib/waits.py の呼び出しへ置き換える
• 原因の鍵を作り、同じ原因の打ち直しを宣言の回数で止める仕組み。呼び出しの再試行（lib/waits.py）と、プランの判定役が返すステップの打ち直しの両方に当てる
• 待ちが上限の時刻に最後の照会を打ってから止まり、止まった理由を結果に出すこと
• 子の課題 9 件の再現の手順を通し、閉じるか理由つきで残すかを本文に記録すること

含まない:

• 上限の値そのものの見直し（例: cross-refactoring の予算の配分を変える cross-refactoring: 予算は選定だけに使い、打ち切らない（既定 60 分・実装時間だけを数える・優先度の順に採る・2 倍まで延長・実績を記録） #2457）。この柱は値の置き場と当て方をそろえ、値は今の既定値のまま移す
• 上書きの経路（引数・環境変数・設定）を新しく作ること。入口の引数・環境変数・設定の受け取り方を 1 つの読み込み部品にそろえる #2341（P8）が受け持つ
• 期限で打ち切った実行の持ち主の記録と後片付け。実行の持ち主と後片付けを核に持たせ、残骸と並行の衝突で止まらないようにする #2342（P3）が受け持つ
• 子の課題を 1 件ずつ直すこと。仕組みを入れた後に再現の手順を通して残ったものは、理由を書いて残す
• 型 D のうちマイルストーン 30 の外にある 4 件（conductor が出力ファイルを確かめる回数が移行後に 15 回から 1,185 回へ増え、conductor の費用の 12.7% を占める #1872・conductor が NDF のスクリプトをシェルでつないで待つと、hook が止めてプランと wait を案内する #1919・PR の pytest が 1 回 10〜13 分かかり、push のたびに古い実行も止まらず走り直す #2154・構造改善の持ち越し: 周回 l20261031-2（#2206 #2186 #2216）の範囲に cross-refactoring を通す #2251）

ドメインイベント

番号は #2335 の要求のドメインイベント E7・E8 を細かくしたもの。

用語

受け入れ条件

• 1. 上限（時間・予算・待ち）・再試行の回数・待ちの間隔の既定値は上限の宣言（plugins/ndf/contracts/limits.json）1 か所にあり、limits.py と各部品はそこから値を読む。宣言の値を 1 つ変えると、その方針の名前を使う部品の振る舞いが変わる（テストで、宣言を差し替えて部品の上限が変わることを見る）
• 2. テストと実験版を除く plugins/ndf/ の Python のコードに、timeout=<数字> の直書きと、上限・再試行の回数・待ちの間隔の定数への数字のリテラルがあると、構造チェック（python3 scripts/check-script-structure.py）が終了コード 1 で落とす。変更の後の develop では 0 で通る
• 3. 再試行のループは lib/waits.py だけにある。lib/waits.py の外で再試行のループを書くと構造チェックが落とす。tenacity を import するのは lib/waits.py だけである
• 4. 同じ原因の鍵の失敗が上限の宣言の回数に達すると、呼び出しの再試行は止まり、待ちの合計の上限まで回らない。原因の鍵が変わった失敗は別に数える（テストで、同じ理由の失敗を続けると宣言の回数で止まり、理由の文の数字だけが違う失敗も同じ原因として数えることを見る）
• 5. 止まったときの結果は stopped で、理由に原因の鍵の要旨と回数が出る（例: 「同じ原因（CI の失敗: runtime-smoke）で 3 回失敗した」）。ステップの打ち直しにも同じ上限が効き、本番の配布のプランで judge が同じ CI の失敗に打ち直しを 7 回返し、上限まで同じ run を読み直す → 同じ失敗が続いたら止めて人へ戻す #1983 の再現の手順（同じ CI の失敗が続く release のステップ）では、宣言の回数で止まって人へ戻る
• 6. 待ちは、次の眠りが上限を超えるとき、上限の時刻に最後の照会を 1 回打ってから止まる。上限で止まったときの結果は stopped で、理由に待った秒・照会の回数・上限の秒が出る（待ちの部品 wait_until が上限の時刻に最後の照会を打たず、上限の最大 2 分前に CI 待ちを打ち切る #2224 の再現の手順で確かめる）
• 7. 宣言が無い・壊れている・方針の名前が宣言に無いとき、部品は組み込みの値へ黙って戻らず、終了コード 1 と理由（宣言のパスと方針の名前）で止まる
• 8. 子の課題 9 件（前提 5）のそれぞれを、閉じた（再現の手順を通して解消を確かめた）か残した（理由つき）かに分けて、この課題の本文に記録する。閉じた課題には、通した手順と結果をコメントで残す
• 9. 退行しない: 既存の全体テスト（uv run --frozen --project . --all-extras pytest . -q -n 4）が通る。limits.py check の順序のチェック（無進捗の許容 < 監視の上限 < CLI の上限）は、宣言を読んで同じ組を判定する

非機能の条件

影響

検証手段

前提とする取り決め

境界

未決

進め方

子の課題は 1 件ずつ直さない。柱の仕組みを入れた後に、子の課題の再現の手順を 1 回ずつ通し、解消したものを理由を添えて閉じる。設計は #2335 の設計（マイルストーン「28 根本解決 1: 設計と契約の棚卸し」）の後に、この柱ごとに行う。

（柱の記号: P4。2026-11-01 の組み直しで作った）

進行

モード: —

• 要求と受け入れ条件 — 2026-11-04 08:06
• 作業場所の用意
• 設計
• 素材の収集と出典の確定
• ドキュメント再構成 — 2026-11-04 08:25
• ドキュメントレビュー
• 計画
• 実装
• 構造改善
• 実装レビュー
• 完了判定
• Pull Request
• 確定仕様化
• 後片付け
• 配布
• 体裁レビュー
• リリース後テスト
• 振り返り
• 棚卸し

人の判断待ち（開発ループ lroot3）

• 判定: unknown（承認ゲート 1）
• 理由: 設計の中身は MVV に沿っている。上限の値を 1 つの宣言にまとめ、同じ原因の打ち直しを決まった回数で止める。これは現象ごとに直さず共通の層で直す形で、Value 7「根本原因の場所で直す」と Value 3「やめる・縮めるを既定にする」に当たる。上限の数字の判定は構文木で行い、待ちと再試行は待ちの部品（lib/waits.py）にまとめる。これは Value 5「決まった手順はスクリプトに、判断と中身は AI に」に当たる。／実装は 3 本の Pull Request に分けて、1 回の承認で読み切れる差分に収める（決定 12）。子の課題 9 件は新しい Issue を起こさず、再現の手順で閉じるか理由をつけて残す。Value 2「人が判断できる量に収める」と Value 3 に反しない。／上限の値の上書きは、今ある環境変数と引数のまま受ける。宣言は配布物に置き、ai-plugins の形を既定に埋め込まない。Value 6「どのプロジェクトでも使える形を保つ」に反しない。／配布の前に取れる検査が止まったまま、原因が確かめられていない。Pull Request のテストの表では、要求の検査（requirements-check）が終了コード 2 で止まった。理由は、この Pull Request で追加した要求文書 issues/issue-2343-requirements.md を「見つからない」として読めなかったことで、原因は未確認と書かれている。要求文書が工程の検査を通る形かを、材料から判定できない。本文が未確認と正直に書いている点は Value 1「小さく出して使って確かめる」に沿う。ただし、通っていない検査を残したまま承認の関門を自動で省くと、確かめていないものを済んだ扱いにすることになる。このため人へ戻す。／この Pull Request は文書と用語集だけを変える。秘密・認証・利用者の設定（.ndf/）・指示書・配布物の取得元（C1〜C8・P1）には触れない。一方、後に続く実装の Pull Request は認証の部品（plugins/ndf/scripts/lib/auth.py）と google-workspace の Skill の下の数字を移す。設計文書の「未確認のまま残ること」も、どちらも .ndf/pace.json の境界の置き場に当たり、MVV の判定では通さず人が見ると書いている。これは今回の変更には含まれないので、承認が要る操作の欄には入れていない。
• 根拠の項目: Mission, Vision, Value 1, Value 2, Value 3, Value 5, Value 6, Value 7, C2, C7, P1
• 設計 Pull Request: NDF のスクリプト: 上限と再試行を 1 つの宣言から引き、同じ原因の打ち直しを決まった回数で止める（#2343） #2481
• 答え: approved
• 答え方: python3 /persistent/ai/.claude/plugins/cache/ai-plugins/ndf/10.27.16/scripts/sprint-state.py loop answer lroot3 2343 --approved|--rejected|--revise --note <指摘ファイル>