結果の契約をそろえ、失敗・未収束・判定できないを ok で返す経路を無くす #2337

大方針 #2335（異常系・ログ・回復とデータ・入出力の形を 1 つの実行の核へ集める）の柱 P1。実行の核のスケルトンを作り、すべてのエントリポイントの結果を ok / gate / stopped と決まった終了コードにそろえる。

依頼（原文）

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

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

（書き手: 利用者、日付: 2026-11-01。親の課題 #2335 の「調べ方」の節が引用した利用者の指摘のうち、この柱に当たるもの）

全ての工程で統一ルールに基づくレポートを JSON で出し、過程・判断・結果が分かるようにする

（書き手: 起票者、日付: 2026-10-31。利用者の方針を AI が要約して #2227 に記録した文で、利用者の発言の原文ではない）

この課題の初版の本文（「何をするか」「受け入れ条件 1〜4」「進め方」）は、起票者（AI）が 2026-11-01 の組み直しで書いた文で、利用者の指示の原文として扱わない。初版の内容は下の「起票者の推定」と受け入れ条件へ移した。

解釈: 利用者が求めているのは、異常が起きたときの扱いを NDF 全体で 1 つにし、同じ型の不具合を 1 件ずつでなく仕組みで無くすことである。この柱はそのうち「失敗の判定」（原因の型 A）を受け持つ。手段（実行の核・run_core.main・柱の分け方）は #2335 の設計（issues/issue-2335-design.md）が決めており、この要求はその範囲で書く。

起票者の推定

題・本文のうち、利用者の原文に無く起票者が推して足した条件。承認ゲート 1 で利用者が確かめるまで、利用者の決定として扱わない。#2335 の推定 S2・S8 は #2335 の承認ゲート 1 を通っている（#2335 の設計文書が develop にある）。

目的

• エントリポイントとステップが、終わり方（正常・例外・SIGTERM・時間切れ）にかかわらず、ok / gate / stopped と決まった終了コードで返る状態にする。欠け・例外・判定できない状態が ok で返る経路を、核と検査で塞ぐ
• worker・外部 CLI・課題を閉じる処理の結果を、自由文ではなく構造化した結果で受け取り、読み違いで先へ進む不具合（原因の型 A）を型ごとに無くす
• 達成したい状態: 新しいエントリポイントを足しても、核を通らなければ構造チェックが落とすため、同じ型の不具合が生まれない

前提

• 前提 1: 柱 P0（入口・受け渡しのファイル・設定・環境変数の契約を 1 か所に宣言し、宣言の外を検査で落とす #2336）は閉じており、契約の一覧（plugins/ndf/contracts/entrypoints/ の 77 項目。Python 50・シェル 27、2026-11-02 に数えた）を正として読む
• 前提 2: 核を通ったかの検査（構造チェックの種類 core-entry）は P0 では入っていない。grep -nE "core-entry|core_entry|run_core" scripts/check-script-structure.py scripts/check-ndf-contracts.py scripts/contracts_lib/*.py は 0 件（2026-11-02）。この柱が入れる
• 前提 3: 1 スプリントは「核の段の Pull Request」と「部品ごとにエントリポイントを移す Pull Request 3 本まで」で作る（異常系・ログ・回復とデータ・入出力の形を 1 つの実行の核へ集め、異常系の課題 103 件を型ごとにまとめて解く #2335 の設計）。全エントリポイントが 1 スプリントで移らなければ、残りは同じ柱の次のスプリントへ送り、この課題は開いたまま残る
• 前提 4: hook と、ランタイム（Claude Code・Codex）が直接起動して標準出力をそのまま使うエントリポイント（ステータスライン など）は核の対象から外す（異常系・ログ・回復とデータ・入出力の形を 1 つの実行の核へ集め、異常系の課題 103 件を型ごとにまとめて解く #2335 の対象範囲）。外す一覧は設計が契約の一覧に印として決める
• 前提 5: 標準出力を結果 JSON 以外（文・JSON の別の形・KEY=VALUE）で返すエントリポイント 46 本の標準出力の形は、この柱では変えない。形をそろえるのは柱 P7（機械が読む出力を 1 行 JSON にそろえ、Markdown と本文の見出しから判定しない #2340）である。この柱は終了コードと結果の状態だけをそろえる
• 前提 6: フェーズレポート（Markdown）・課題と PR の本文から値を読む箇所は柱 P7 が受け持つ。この柱が受け持つのは、worker・外部 CLI の報告とフェーズの結果から「完了・止まり」を判定する箇所である
• 前提 7: 外部 CLI の標準エラーの文から失敗の理由（利用上限など）を分類することは残してよい。外部 CLI は NDF の外にあり、構造化した理由を返さないためである。完了の判定にだけ使わない
• 前提 8: SIGKILL など後片付けのコードが動けない終わり方では、結果 JSON は出ない。呼ぶ側は結果 JSON が無いことを stopped と読む

対象範囲

含む:

• 実行の核のスケルトン（run_core.main(<エントリポイントの id>, <本体>) と、シェルの rc_enter）。終わり方ごとの結果への変換・欠けの確認・extras が無いときの扱い
• 契約の一覧のエントリポイント（前提 4 を除く）を核へ移すこと
• 構造チェックの種類 core-entry と、その例外リスト
• worker の報告・外部 CLI の報告・フェーズの結果から完了と止まりを判定する箇所
• 課題を閉じる処理（sprint-close.py）の結果の状態
• 子の課題 21 件の、閉じる・残すの仕分け

含まない:

• 実行の記録（JSON Lines）と実行の識別子の記録（柱 P2 1 回の実行を識別子 1 つで追える記録とログにそろえる #2338）。結果 JSON に任意の鍵 run_id を足すことは含む
• 持ち主の記録と後片付け・並行の排他（柱 P3 実行の持ち主と後片付けを核に持たせ、残骸と並行の衝突で止まらないようにする #2342）
• 上限と再試行の宣言（柱 P4 上限と再試行の方針を 1 つの宣言に集め、同じ失敗の打ち直しを止める #2343）
• データの型と版（柱 P6 内部データに型と版を持たせ、同じ意味の値を 1 つの名前にそろえる #2339）
• 標準出力の形と、Markdown・本文から値を読む箇所（柱 P7 機械が読む出力を 1 行 JSON にそろえ、Markdown と本文の見出しから判定しない #2340）
• 引数・環境変数・設定の読み込み部品（柱 P8 入口の引数・環境変数・設定の受け取り方を 1 つの読み込み部品にそろえる #2341）
• hook と、ランタイムが直接起動するエントリポイント（前提 4）
• 子の課題を 1 件ずつ直す Pull Request

ドメインイベント

洗い出しで移したもの: E5 の SIGKILL は前提 8 に、E6 の構造化した結果が無い場合は受け入れ条件 9 に、E8 の「振り返りを待つ」扱いは未決に置いた。

用語

受け入れ条件

核の結果の契約

• 1. 本体が結果を返す・例外を投げる・SIGTERM を受ける・時間切れになる、の 4 つの終わり方のそれぞれで、核の結果 JSON の status は ok / gate / stopped のどれかで、終了コードは step_result.code_matches を満たす
• 2. 例外・SIGTERM・時間切れで終わったとき、結果は stopped で、summary に理由があり、gaps に interrupted（SIGTERM）か timeout（時間切れ）が入る
• 3. 本体が gaps の空でない結果を ok で返すと、核は stopped・終了コード 6 を返す
• 4. 本体が結果の形でないもの（None・型の違う値）や、status と終了コードが食い違う結果を返すと、核は stopped・終了コード 1 を返す
• 5. 契約の一覧のすべてのエントリポイント（前提 4 を除く）を、欠けのある結果を返す本体と例外を投げる本体に差し替えて回すテストで、ok が 1 度も出ない
• 6. 前提 4 を除くすべての Python のエントリポイントの if __name__ == "__main__": の中身が run_core.main(...) の 1 文で、シェルのエントリポイントが先頭で rc_enter を呼ぶ。外れたエントリポイントを構造チェック（core-entry）が名前を出して落とす
• 7. core-entry の例外リストに行を足す変更を構造チェックが落とす。この課題を閉じる時点で core-entry の例外リストの行は 0 である
• 8. optional extras（pydantic・tenacity・dbos）が入っていない環境でエントリポイントを起動すると、例外の跡（traceback）を出さず、stopped・終了コード 69 と足りないグループの名前が返る

報告と結果の読み方

• 9. supervise は worker の完了を、worker が返す構造化した結果の status だけから決める。報告の文に「結果: 完了」「判断が要る」があるかで成否を決める箇所が無い。構造化した結果が無いか読めない worker は stopped になる
• 10. supervise.py run の終了コードは、フェーズの結果の status から決まる（今は報告の文に決まった語があるかで決める。plugins/ndf/scripts/supervise_lib/commands.py:308）
• 11. 外部 CLI（codex・agy・kiro・claude）の完了は、終了コードと結果ファイルの状態から決まる。結果ファイルが無い・読めないときは ok にならない。進捗ログの語（「止まった」など）から止まりを判定する箇所が無い（supervise_lib/state.py:30 の PROGRESS_STOP）
• 12. ほかのエントリポイントの結果 JSON を読んで次の手を決める箇所は、共通の読み手（lib/step_read.py）を通し、status が ok でない結果を成功と読まない
• 13. 契約の一覧の各エントリポイントの終了コードの表（exit）が step_result の終了コードの表と同じ意味で書かれ、違う意味の番号（handoff.py が終了コード 4・5 を共通の表と違う意味で返し、emit の検査も通らない #2241 の 4・5 など）を持つエントリポイントを検査が落とす

課題を閉じる処理

• 14. 課題を閉じる処理は、閉じる対象として集めた課題のうち閉じなかった課題（kept_open・closed_unverified・failed）が 1 件でもあれば ok を返さず、課題ごとの理由を結果に載せる。参照しているだけの課題（閉じる対象でないもの）は状態に影響しない
• 15. 課題を閉じる処理は、今と同じく、閉じる条件 2（リリース後テストの行）と条件 3（振り返りの記録）を満たさない課題を閉じない（退行しない）
  前提の確認: uv run --frozen --project . --all-extras pytest plugins/ndf/scripts/tests/test_sprint_close_final_stage.py plugins/ndf/scripts/tests/test_sprint_close_acceptance.py -q → 38 passed（2026-11-02、v10.27.10）。今は条件 3 を満たさない課題が kept_open・終了コード 0 で返る（test_an_issue_without_the_retro_record_is_kept_open）。受け入れ条件 14 はこの終了コードを変える

子の課題

• 16. 下の「子の課題」の 21 件それぞれについて、柱の仕組みのマージの後に再現の手順を 1 回通し、閉じた（解消を確かめた）か残した（理由つき）かをこの本文に記録する

起きてはいけないこと

• 17. 結果 JSON の既存の鍵（tool・status・summary・items・metrics ほか）を削らない。足すのは任意の鍵 run_id だけである
• 18. step_result の終了コードの表（0・1・2・3・4・6・10〜19・20〜29・69・75）の意味を変えない
• 19. Skill の本文・プランの雛形が書くエントリポイントの呼び方（コマンドと引数）が変わらない
• 20. 全体テスト uv run --frozen --project . --all-extras pytest . -q -n 4 が、この柱の各 Pull Request のマージの前後で通る

非機能の条件

影響

検証手段

前提とする取り決め

境界

子の課題

見込みは、どの受け入れ条件の仕組みで解消しうるかの推定で、閉じるかどうかは受け入れ条件 16 の再現で決める。

未決

進行

モード: —

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

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

• 判定: unknown（承認ゲート 1）
• 理由: 設計の中身は MVV に沿って読める。終わり方の扱いを実行の核 1 か所へ集める（Value 6）。結果の読みと検査をスクリプトへ寄せ、worker の成否を文で読まない（Value 4）。核はプロジェクトの設定を読まず、時間切れの秒は環境変数で受ける（Value 5）。各決定に理由と採らなかった案を残している（Value 7）。／一方で、設計の検査手順のうち要求のコピーの照合（requirements-check）が終了コード 2 で止まっている。issues/issue-2337-requirements.md と 結果の契約をそろえ、失敗・未収束・判定できないを ok で返す経路を無くす #2337 の要求の一致はまだ確かめられていない。原因も未確認のまま残っている。／Value 10 は、承認資料に載せる材料の正しさを効率による後回しの対象から外している。設計の前提である要求のコピーが正しいかが確かめられていないため、MVV に従うかを材料から決めきれない。／共通原則は、AI が自分で取れる行動を『進める』か『止めて人へ戻す』の 2 つに限り、決められないときは人へ戻すとしている。止まった検査を成功と同じに扱って関門を省くことは、欠けや失敗を ok と読まないというこの設計自身の趣旨にも反する。／この PR は設計文書と用語集の変更だけである。共通原則の C1〜C8 と固有の P1 に当たる操作は含まない。決定 5 で runtime の印を増やす場合は承認ゲートで人が見るとしており、その点に矛盾は無い。
• 根拠の項目: Mission, Vision, Value 2, Value 3, Value 4, Value 5, Value 6, Value 7, Value 10
• 設計 Pull Request: NDF のエントリポイント: どの終わり方でも ok / gate / stopped と決まった終了コードで返り、欠けと失敗を ok と読まない（#2337） #2412
• 答え: approved
• 答え方: python3 /persistent/ai/.claude/plugins/cache/ai-plugins/ndf/10.27.16/scripts/sprint-state.py loop answer lroot2 2337 --approved|--rejected|--revise --note <指摘ファイル>