プランは値でなく参照を持ち、実行の直前に解決して照合する #2344

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

依頼（原文）

この課題の題と本文は、起票者（課題を書いた AI）が 2026-11-01 に大方針 #2335 の組み直しの記録として書いた文で、利用者の指示の原文ではない。この柱の元になった利用者の指示は、#2335 の「依頼（原文）」が引用した次の文である。

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

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

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

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

（書き手: 利用者、日付: 2026-11-01。#2335 の本文 #2335 から引用した）

起票時の本文（書き手: 起票者、日付: 2026-11-01）:

プランは版・記録の PR・宣言・予算・触るファイル・承認時の先端などを参照で持ち、実行の核がステップの直前に解決して記録する。解決できない・承認した値と食い違うときは流さずに止まる。m26-3 の #2230（記録の PR）と #2164（版数）を最初の事例とし、その形を全体へ広げる。

1. プランは版・記録の PR・宣言の値を参照で持ち、核が実行の直前に解決する。解決できなければ流さずに止まる
2. 承認ゲートで見た値（先端・版）と実行時の値の食い違いを核が照合し、食い違えば止まって人へ戻す
3. 子の課題それぞれを、閉じた（解消を確かめた）か残した（理由つき）かに分けて本文に記録する

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

子の課題の結び付け（書き手: 起票者、日付: 2026-11-01。課題のコメント）:

子として #2349・#2354 を結び付けました（スプリント lroot-2 の棚卸し）。

この要求の整理の指示（書き手: AI の起動指示、日付: 2026-11-04）:

人へ問わずに進め、決められない点は前提か未決として課題の本文へ書く。

範囲の指示（書き手: 利用者、日付: 2026-11-05。設計の承認ゲート 1 の答え）:

範囲を、起きた不具合に根拠のあるものに絞る: 版数・リリース記録の PR の直前の解決（#2164）・実行条件を先に評価（#2349）・流し直しの判定（#2349）・開発ループの版（#2354）。
外すもの: 設定 11 キーと予算を同じ参照の仕組みに載せる部分と、形を決めた設定のハッシュ照合（受け入れ条件 1・11 も合わせて縮める）。

解釈: 利用者が求めているのは、プランを作った時点の値が流す時点で古くなって止まる型の不具合（大方針の原因の型 E「解決の時点」）のうち、起きた不具合に根拠のあるもの（版数・記録の PR・実行条件の評価・完了したプランの流し直し・開発ループの版）を、1 件ずつではなく仕組みで無くすことである。今は #2164 の版の差し込み（{release_version}）と #2230 の記録の PR の差し込み（{queue_record}）が、キューの中でそれぞれ別の手当てとして解決している。この柱は、その 2 つを実行の核の参照の部品（#2335 の設計の lib/refs.py）へ寄せ、同じキューの中で解決している前のプランの結果の差し込みと承認したコミットの照合も同じ形に載せる。設定の値と予算は参照にしない（利用者の範囲の指示）。

起票者の推定

題・本文のうち、上の利用者の原文に無く、起票者が推して足した条件。承認ゲート 1 で利用者が確かめるまで、利用者の決定として扱わない。S6〜S8 はこの要求の整理で足した。

目的

• プランを作ってから流すまでの間に版・記録の PR が変わっても、プランを作り直さずに流せる状態にする（今は スプリントのプランが作った時点の版数を配布と本番のプランへ書き込み、並行する別のスプリントがその版を先に出すとプランを作り直すまで止まる #2164 の 2 回の再発のように、conductor がプランを作り直すか版を書き換えた）
• 参照を解決できないとき・承認ゲートで人が見た値と食い違うときに、推定の値や古い値で黙って進まず、理由を添えて止まる状態にする
• 参照を解決する手当てを 1 か所にまとめ、新しい種類の値を足しても同じ規則で解決・記録・照合される状態にする（今は版・記録の PR・前のプランの結果が、キューの中で別々の関数として解決している）

前提

• 前提 1: この柱の設計と実装は、異常系・ログ・回復とデータ・入出力の形を 1 つの実行の核へ集め、異常系の課題 103 件を型ごとにまとめて解く #2335 の設計（issues/issue-2335-design.md・issues/issue-2335-design-decisions.md・issues/issue-2335-design-pillars.md）を正とする。参照の部品（lib/refs.py）・不変条件 I14・ドメインイベント E5 はそれに従う
• 前提 2: この柱の実装は、柱 P6（内部データに型と版を持たせ、同じ意味の値を 1 つの名前にそろえる #2339 データの契約。プランの型）・P8（入口の引数・環境変数・設定の受け取り方を 1 つの読み込み部品にそろえる #2341 入力の契約）・P3（実行の持ち主と後片付けを核に持たせ、残骸と並行の衝突で止まらないようにする #2342 持ち主の記録）のマージの後に始める（issues/issue-2335-design-pillars.md の順序）。2026-11-04 の時点で 3 本とも未完了で、plugins/ndf/scripts/lib/ に run_core.py・refs.py・lease.py は無い（ls plugins/ndf/scripts/lib/ の結果に 3 つの名前が出ないことで確かめた）。設計は 3 本の設計文書を正として先に書いてよい
• 前提 3: 寄せる元の実装は次の 4 つである。どれも 2026-11-04 の develop にあり、キューがステージを流す直前に解決している
  • 版の差し込み（{release_version}・{release_base}）と版の記録（supervise_lib/queue_fill.py の fill_release_version、lib/release_version.py）
  • 記録の PR の差し込み（{queue_record}。supervise_lib/queue_fill.py の _fill_record）
  • 前のプランの結果の差し込み（{queue_pr:<名>}・{queue_state:<名>}・{queue_prs:<名>}・{queue_approved:<名>}・QUEUE_PRS）
  • 承認したコミットと先端の比較（lib/approved_commit.py の compare_approved。release: 承認した時点のコミットを控えず、承認の後に開発版のチャネルへ入った変更が本番へ届きうる #815）
• 前提 4: 承認したコミットとの照合は、今の compare_approved と同じく「承認したコミットの後に、許したもの（この版の配布の Pull Request）だけが入っている」なら食い違いとみなさない
• 前提 5: 参照を持たない旧い形のプラン（この柱より前の版の NDF が作り、値を書き込んだプラン）は、書き込まれた値をそのまま使って流す。実行の記録にはその値の出所を「プランの値」と書く（異常系・ログ・回復とデータ・入出力の形を 1 つの実行の核へ集め、異常系の課題 103 件を型ごとにまとめて解く #2335 の移行性。旧い版が書いた状態ファイルを読む受け入れ条件 10b と同じ扱い）

対象範囲

含む:

• 参照の部品と、実行の核の参照の段（E4〜E7）
• 前提 3 の 4 つの実装を参照の部品へ寄せること（キューに残る差し込みの関数を消す）
• 実行条件を、--from で始めるときも含めてステップの直前に評価すること（queue の再開が、取り込み済み・完了済みの実装のプランを流し直し、差分なしの PR 作成で止まる #2349 の 1 つ目）
• 完了したプランの流し直しの判定を、解決の記録とプランの中身の照合で行うこと（queue の再開が、取り込み済み・完了済みの実装のプランを流し直し、差分なしの PR 作成で止まる #2349 の 2 つ目）
• 開発ループが組むスプリントの版を参照にすること（開発ループのスプリントが版を流す時点に決められず、並行するスプリントと版がぶつかると止まる #2354）
• 子の課題 4 件の再現の手順を通し、閉じるか残すかを本文に記録すること

含まない:

• 子の課題を 1 件ずつ直す Pull Request（即時修正の 4 条件を満たすものと本番を止めているものは除く）
• 触るファイルを参照にすること（起票者の推定 S5）
• 宣言の値（.ndf/ の設定）と予算を参照にすること、プランを組んだ時点の設定の値と流す時点の値を照らすこと（利用者の範囲の指示）。どちらも今と同じく、プランを組む時点の値で持つ
• 差分の無い実装のプランで pr が終了コード 1 になること（queue の再開が、取り込み済み・完了済みの実装のプランを流し直し、差分なしの PR 作成で止まる #2349 の 3 つ目）。値の解決の時点の問題でなく、結果の契約（柱 P1 結果の契約をそろえ、失敗・未収束・判定できないを ok で返す経路を無くす #2337）の問題である（受け入れ条件 11 で確かめて残す）
• 上限と再試行の値そのもの（柱 P4 上限と再試行の方針を 1 つの宣言に集め、同じ失敗の打ち直しを止める #2343）と、持ち主の記録の取り方（柱 P3 実行の持ち主と後片付けを核に持たせ、残骸と並行の衝突で止まらないようにする #2342）
• 版の規則（次に空いている版の決め方・決め直しの条件）を変えること。スプリントのプランが作った時点の版数を配布と本番のプランへ書き込み、並行する別のスプリントがその版を先に出すとプランを作り直すまで止まる #2164 の規則をそのまま使う
• factory/ のプラン

ドメインイベント

1 回のプランの実行のうち、参照の解決と照合に関わる部分を時間の順に並べる。右端の列は #2335 のドメインイベントの番号である。

洗い出しで移したもの: E1 で参照の形を決める型はプランの型（柱 P6）に置いた（前提 2）。E5 の「流し直しで前に解決した値を使い続けるか」は受け入れ条件 5 に置いた。E6 の「食い違いとみなさない差」は前提 4 に置いた。E9 の「プランの中身の同一性を何で測るか」は未決に置いた。

用語

受け入れ条件

• 1. supervise.py new sprint（版を明示しない）・new close・sprint-state.py loop sprint が組むプランのファイルは、版数と記録の PR の番号を値として持たず、参照で持つ。設定から読んだ値と予算の秒は、今と同じく組んだ時点の値で持つ。組んだプランのファイルを読むテストで確かめる
• 2. 参照は、ステップの直前（持ち主の記録を取った後）に実行の核が解決し、参照ごとの値と出所が実行の記録に残る。解決でプランのファイルは書き換わらない（流す前と後でファイルの sha256 が同じ）
• 3. 参照を解決できないとき（記録の PR が見つからない・origin の版かタグを読めない・前のプランの完了した結果が無い）は、ステップを流さず stopped で返り、結果 JSON に参照の名前と解決できなかった理由が出る。推定の値・空・0・unknown で埋めて流さない
• 4. 承認ゲート 2 の後に、承認したコミットの後へ許したもの以外のコミットが入った、または承認資料の版と解決した版が違うとき、本番のステップを流さず gate で返り、結果 JSON に承認時の値と実行時の値が並ぶ。承認したコミットの後に許したものだけが入ったときは流れる（前提 4）
• 5. 同じプランの同じステップを流し直すと、前の実行で解決した版を使う。ただし スプリントのプランが作った時点の版数を配布と本番のプランへ書き込み、並行する別のスプリントがその版を先に出すとプランを作り直すまで止まる #2164 の版の決め直し（自分の配布のマージより前に別のスプリントがその版を出した）に当たるときは、スプリントのプランが作った時点の版数を配布と本番のプランへ書き込み、並行する別のスプリントがその版を先に出すとプランを作り直すまで止まる #2164 の規則で決め直し、決め直した前の版と理由が解決の記録に残る
• 6. 実行条件を満たして飛ばすはずのプランを --from <プラン>=<ステップ> で始めても、そのプランは飛ばされ、結果に飛ばした旨が出る（queue の再開が、取り込み済み・完了済みの実装のプランを流し直し、差分なしの PR 作成で止まる #2349 の再現の手順で確かめる）
• 7. 完了したプランを含む done のファイルを --resume しても、完了したプランは流れない。完了の後にプランのファイルが変わっていたら、流さずに gate で返り、変わったことと流し直す手段を結果に出す（queue の再開が、取り込み済み・完了済みの実装のプランを流し直し、差分なしの PR 作成で止まる #2349 の再現の手順で確かめる）
• 8. sprint-state.py loop sprint は --dev を省いて起動でき、省いたとき組むスプリントのプランは版を参照で持つ。--dev を渡したときは今と同じく明示の版のプランになる（開発ループのスプリントが版を流す時点に決められず、並行するスプリントと版がぶつかると止まる #2354 の再現の手順で確かめる）
• 9. スプリントのプランが作った時点の版数を配布と本番のプランへ書き込み、並行する別のスプリントがその版を先に出すとプランを作り直すまで止まる #2164 の受け入れ条件 1〜10 と リリース記録の PR を、まとめのプランを組む時点でなく実行の時点で解決する #2230 の受け入れ条件のテストが、参照の部品へ寄せた後も通る。前提 3 の差し込みを解決する関数が、キュー（supervise_lib/queue_fill.py・supervise_lib/queue.py）に残らない
• 10. 前提 5 の旧い形のプラン（値を書き込んだプラン）を流すと、書き込まれた値で流れ、実行の記録に出所「プランの値」が残る
• 11. 子の課題 4 件（下の「子の課題」の表）それぞれについて、再現の手順を 1 回通した結果（コマンドと出力の要点）と、閉じた（解消を確かめた）か残した（理由つき）かを、この課題の本文の表に記録する。閉じた課題には、確かめた結果へのリンクを添える
• 12. 参照を持たない入口とプランの振る舞いが変わらない。全体テストが柱のマージの前後で通る

子の課題

受け入れ条件 11 で、柱の仕組みを入れた後に 1 件ずつ再現の手順を通す。「見込み」は要求の整理（2026-11-04）での見立てで、結論ではない。

非機能の条件

影響

検証手段

前提とする取り決め

境界

未決

進行

モード: — / 進め方: auto

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

設計の承認ゲート 1 での利用者の指摘（直して出し直す）

（書き手: 利用者の答えをオーガナイザーが写した、日付: 2026-11-05。出し直しの設計はこの節を満たすように直す。満たせない項目は理由を設計に書く。この節は上書きしない）

範囲を、起きた不具合に根拠のあるものに絞る: 版数・リリース記録の PR の直前の解決（#2164）・実行条件を先に評価（#2349）・流し直しの判定（#2349）・開発ループの版（#2354）。
外すもの: 設定 11 キーと予算を同じ参照の仕組みに載せる部分と、形を決めた設定のハッシュ照合（受け入れ条件 1・11 も合わせて縮める）。
あわせて: PR 本文の検査の記述を最新の結果（再検査 exit 0）に直す。
前回の指摘（.ndf/parallel/p3/notes/g2482.md）が反映されていない。同じ指摘で直す。直す箇所を名指しする:

1. 要求の「予算も参照で持つ」と、宣言の値・予算の秒を参照で持つ部分を消す。受け入れ条件 1 と 11 を、版数・リリース記録の PR の直前の解決（スプリントのプランが作った時点の版数を配布と本番のプランへ書き込み、並行する別のスプリントがその版を先に出すとプランを作り直すまで止まる #2164）・実行条件を先に評価（queue の再開が、取り込み済み・完了済みの実装のプランを流し直し、差分なしの PR 作成で止まる #2349）・流し直しの判定（queue の再開が、取り込み済み・完了済みの実装のプランを流し直し、差分なしの PR 作成で止まる #2349）・開発ループの版（開発ループのスプリントが版を流す時点に決められず、並行するスプリントと版がぶつかると止まる #2354）だけに縮める
2. 決定 4（設定 11 キーと予算を参照の仕組みに載せる）を「採らない」にする
3. 設計の不変条件 I3・I7（形を決めた設定のハッシュ照合で止める）と、それを前提に足した手当て（「設定の照合の後に置く」）を消す
4. PR 本文の検査の欄を最新の結果（要求の再検査 exit 0、ドキュメントレビューの結果）に、行数を今の値に直す

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

• 判定: follow（承認ゲート 1）
• 理由: Mission と Vision に沿う: 版と記録の PR を流す直前に解決し、解決できないときは stopped、承認したときの値と食い違うときは gate で人へ戻す。この形で、人が止まる所を判断の要る場面に絞り、プランの作り直しや完了済みプランの流し直しという手戻りを減らす／Value 7（根本原因の場所で直す）と Value 5（決まった手順はスクリプトに）に沿う: 種類ごとに 6 か所へ分かれていた差し込みの解決と書き戻しを、参照の部品（lib/refs.py）の 1 つの規則へ寄せる。照合の関数も approved_commit.py の 1 か所にまとめる／Value 3（やめる・縮めるを既定にする）と Value 4（外の利用で測って決める）に沿う: 範囲を、実際に起きた不具合（スプリントのプランが作った時点の版数を配布と本番のプランへ書き込み、並行する別のスプリントがその版を先に出すとプランを作り直すまで止まる #2164・リリース記録の PR を、まとめのプランを組む時点でなく実行の時点で解決する #2230・queue の再開が、取り込み済み・完了済みの実装のプランを流し直し、差分なしの PR 作成で止まる #2349・開発ループのスプリントが版を流す時点に決められず、並行するスプリントと版がぶつかると止まる #2354）に根拠のあるものに絞る。設定と予算を参照にする案は根拠が無いとして外し、承認資料が増えるのも抑えた（決定 4）／Value 6（どのプロジェクトでも使える形を保つ）と Value 8（判断の理由を残し、語をそろえる）に沿う: プラグインの名前やチャネルは参照の宣言の params で受け、ai-plugins の値を部品に埋め込まない。決定ごとに採らなかった案と理由を残し、用語集を設計の語にそろえている／必ず人の承認が要る操作には当たらない: この PR は文書と用語集だけを変える。設計でも版の規則（release_version.py と スプリントのプランが作った時点の版数を配布と本番のプランへ書き込み、並行する別のスプリントがその版を先に出すとプランを作り直すまで止まる #2164 の判定）は変えないため P1 に当たらない。承認の照合は強める方向で、秘密・認証・利用者のデータ・戻せない操作（C1〜C4）にも触れない。旧版の worktree とブランチは消さずに残す
• 根拠の項目: Mission, Vision, Value 2, Value 3, Value 4, Value 5, Value 6, Value 7, Value 8, C1, C2, C4, P1
• 設計 Pull Request: プランの参照: プランを作り直さずに版・記録の PR を流す直前の値で使い、承認時の値と食い違えば止まる（#2344） #2482
• 答え: approved
• 答え方: python3 /persistent/ai/.claude/plugins/cache/ai-plugins/ndf/10.27.18/scripts/sprint-state.py loop answer lroot3 2344 --approved|--rejected|--revise --note <指摘ファイル>