プランの参照: プランを作り直さずに版・記録の PR を流す直前の値で使い、承認時の値と食い違えば止まる（#2344） by takemi-ohama · Pull Request #2482 · devbasex/ai-plugins

takemi-ohama · 2026-11-04T08:55:16Z

Issue #2344 の要求・設計・設計判断の文書を追加し、用語集を設計の語にそろえました。設計の主題は、プランが参照する値を実行の直前に解決し、承認したときの値と照らし合わせることです。この PR は文書だけを変更します。

利用者向けの変化

無し

移行の手順

無し

変更の要点

要求と受け入れ条件を issues/issue-2344-requirements.md に置きました。対象は、プランの参照を実行の直前に解決して照合する仕組みです。
設計を issues/issue-2344-design.md に、設計の判断を issues/issue-2344-design-decisions.md に置きました。設計で決めたことは次のとおりです。
- 範囲は、版数・記録の PR・実行条件・流し直し・開発ループの版に絞りました。設定と予算の参照、形を決めた設定の照合は範囲に含めません。
- 終了コード、上位の欄の解決、版の決め直し、明示の版の経路を決めました。
- 版の決め直しの事前判定は、実行条件と設定の照合の後に置きます。また、耐久ワークフローの回復より先に判定します。
- 版を決め直したときは、キューを新しく開きます。耐久ワークフローの世代は接頭辞へ入れます。
- 版の決め直しの退避と、耐久ワークフローの世代は、設計文書の中で別の節に分けました。
用語集（ docs/glossary.md と docs/glossary/glossary.json ）を設計にそろえました。
- 「版の決め直し」は、解決の控えへ上書きする形で定義しました。
- 設計文書の語は、用語集の「エントリポイント」にそろえました。

テスト

supervise.py の run のステップの結果です。

ステップ	終了コード	結果
glossary	0	宣言と用語集が揃っている
requirements-check	0	issues/issue-2344-requirements.md は #2344 の本文と一致する

モード: standard / 通した工程: 設計 → 要求と受け入れ条件 → ドキュメント再構成 → ドキュメントレビュー

🤖 Generated with Claude Code

決めたこと

issues/issue-2344-design-decisions.md

決定 1: 新しい種類の値を同じ規則で解決できるよう、参照はプランの型の refs 欄に名前つきで宣言し、ステップからは {ref:<名前>} で指す
決定 2: プランが変わったのが人の編集か解決かを区別できるよう、解決した値はプランのファイルへ書き戻さず、メモリ上のステップにだけ入れる
決定 3: 流し直しでも同じ版を使えるよう、版の解決は状態ディレクトリの解決の控え（refs.json）に残し、version.json は移行関数で読む
決定 4: 範囲を起きた不具合に根拠のあるものに収めるよう、設定の値と予算は参照にせず組んだ時点の値で持ち、組んだ時点の設定とも照らさない
決定 5: 利用者が明示した版を AI が置き換えないよう、明示した版は版の参照の explicit に値のまま入れる
決定 6: 承認ゲート 2 で人が見た版と流す版を照らせるよう、承認資料に「承認した版」の行を足し、本番のエントリポイントはエントリポイントの契約の refs で参照の部品を通る
決定 7: 完了したプランの流し直しを中身の変更だけで判定できるよう、プランの同一性はプランの型で読んだ中身を正規化した JSON の sha256 で測る
決定 8: 飛ばすはずのプランが開始のステップで流れないよう、実行条件は参照の解決より先に、開始のステップによらず 1 回だけ評価する
決定 9: 前のプランの結果をキューの外からも同じに解決できるよう、前のプランの結果の参照は状態ディレクトリから読む
決定 10: 結果を読む側を壊さないよう、参照で止まったプランのキューの項目は unfilled: true を保つ
決定 11: 開発ループのスプリントが版の取り合いで止まらないよう、loop sprint の --dev を任意にし、省いたら版を渡さない

課題の本文の写しを issues/ に置き、要求で使う語（プランの参照・解決の記録・承認時の値）を用語集へ足した。 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

#2335 の柱 P5 の設計。プランは版・記録の PR・前のプランの結果・設定・予算を参照で持ち、参照の部品がステップの直前に解決して実行の記録へ残す。プランのファイルは書き換えない。解決できなければ stopped、承認時の値と食い違えば gate で返す。 - 本体 issues/issue-2344-design.md（434 行）と決定の記録 issues/issue-2344-design-decisions.md（決定 11 件） - 要求の未決 5 件のうち 4 件を決定 1・3・4・7 で決めた。残る 1 件（柱 P3・P6・P8 の設計が変わったときの読み直し）は「未確認のまま残ること」に置いた - 用語集に「解決の控え」「形を決めた設定」「プランのハッシュ」を足し、「版の記録」「版の差し込み」の意味を変えた Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

- 長い文を分け、列挙と対比を表・箇条書きへ移した - 処理の流れ・構成要素の章を小見出しで分けた - JSON のキーを指す「鍵」を、本文の他の箇所と同じ「キー」にそろえた Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

takemi-ohama

🤖 cross-review | round 1 | codex | APPROVE

指定されたドメインモデル節と用語集の差分に、critical / major に該当する修正指摘はありません。根拠: Value 3 / Value 8。

takemi-ohama

🤖 cross-review | round 1 | kiro | REQUEST_CHANGES

用語集の「版の決め直し」が旧い仕組み（差し込み前のプランの写し）のまま残っている。形を決めた設定の照合（I7）に対応するドメインイベントが無い。

差分の外を指す指摘

docs/glossary/glossary.json:4807 [major] [major / 用語の整合] 「版の決め直し」の意味が「差し込み前のプランの写しから埋め直す」のまま。この設計は、プランを書き換えないため version-plan.json（差し込み前のプランのコピー）を作らないと決め（データ構造の解決の控え）、決め直しは refs.json の rows.version を上書きして前の値を history に残すと決めた（I6）。同じ変更で意味を「解決の控えの版の行を次に空いている版へ上書きし、前の版と理由を history に残すこと」へ直す。docs/glossary.md の同じ行（329 行目）も glossary.py render で合わせる。
issues/issue-2344-design.md:68 [major] [major / 設計の食い違い] 不変条件 I7（形を決めた設定の照合）と I8 の前段（プランのハッシュの照合の位置）に対応するドメインイベントが無い。ドメインイベントの表は E3（記録）→E4（実行条件）→E5（解決）だけで、I7 の「最初のステップの前に pins を照らす」がどこで起こるか、実行条件の評価の前か後かを決めていない。I3 の順序（記録→実行条件→解決）にも I7 が入っていない。「形を決めた設定を照合した」イベントを足し、発生元・受け手（食い違えば stopped で実行条件・解決を行わない）と、E3/E4 との前後を決める。

設計はプランを書き換えず、差し込み前のプランのコピーを作らない。決め直しは解決の控えの版の行を上書きし、前の版と理由を履歴に残す。 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

takemi-ohama · 2026-11-04T09:00:17Z

🔧 /ndf:fix サマリ | round 1 | commit `de0f217`

対応件数: critical=0 / major=1 / minor=0（合計 1 件）
決着: 1 件 / 見送り: 1 件 / 却下: 0 件
基準外の見送り: 1 件
CI: PENDING

レビュー本文の指摘への返事:

対応しました。（de0f21740）
[major / 設計の食い違い] 不変条件 I7（形を決めた設定の照合）と I8 の前段（プランのハッシュの照合の位置）に対応するドメインイベントが無い。ドメインイベントの表は E3（記録）→E4（: 直しません。この指摘は、利用者が実際に使って困る不具合ではないためです（実装に影響しない文書の食い違い。レビューの重点（トークン・所要時間・処理の回数（CLI の起動・API の呼び出し・CI の実行）を増やす変更）にも当たりません）。使って困る場面が出たら、そのときに直します。根拠: Value 3（MVV 版 5）

takemi-ohama

🤖 cross-review | round 2 | claude | APPROVE

用語集の「版の決め直し」は設計（I6・解決の控えの rows.<名前>.history・プランを書き換えない方針）と一致しており、glossary.json と glossary.md も同じ文で揃っている。critical / major の指摘はない。根拠: Value 8。

takemi-ohama

🤖 cross-review | round 2 | kiro | APPROVE

指摘なし。

takemi-ohama · 2026-11-04T09:01:39Z

🔧 /ndf:fix サマリ | commit (なし)

対応件数: critical=0 / major=0 / minor=0（合計 0 件）
決着: 0 件 / 見送り: 0 件 / 却下: 0 件
CI: NONE

章の並びは設計文書のテンプレートの順のまま変えない。内容は足さない。 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

takemi-ohama

🤖 cross-review | round 3 | claude | REQUEST_CHANGES

承認時の値との食い違いと完了したプランの変更を gate・終了コード 3 で返す設計は、既存の結果の契約（gate は 10〜19）と #2335 の I1 に反する。終了コードを 10（EXIT_GATE）へ直す。

takemi-ohama

🤖 cross-review | round 3 | codex | REQUEST_CHANGES

修正指摘3件。根拠: Mission / Value 1 / Value 2 / Value 7 / Value 8。

- 承認時の値との食い違いと完了したプランの変更の gate を終了コード 10（EXIT_GATE）にそろえる - 作業場所と branch の参照を作業ツリーの前に resolve_head で解決し、I3 の順序に入れる - 版の決め直しで旧版のステップの記録を superseded へ退避し、新版の先頭から流す手順を決める - --version の明示の版を版の参照の explicit に入れ、既出の判定と承認した版の照合を通す Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

takemi-ohama · 2026-11-04T15:05:31Z

🔧 /ndf:fix サマリ | round 3 | commit `33d5e55`

対応件数: critical=0 / major=4 / minor=0（合計 4 件）
決着: 4 件 / 見送り: 0 件 / 却下: 0 件
CI: PENDING

takemi-ohama

🤖 cross-review | round 4 | codex | REQUEST_CHANGES

修正指摘1件。根拠: Mission / Value 1 / Value 7。

takemi-ohama

🤖 cross-review | round 4 | kiro | APPROVE

指摘なし。

決め直した世代は新しい耐久ワークフローとして先頭から始め、旧版の耐久ステップの記録を再利用しない。用語集の検査に合わせ、作業ツリーを worktree と書く。 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

takemi-ohama · 2026-11-04T15:11:06Z

🔧 /ndf:fix サマリ | round 4 | commit `d9f3fd8`

対応件数: critical=0 / major=1 / minor=0（合計 1 件）
決着: 1 件 / 見送り: 0 件 / 却下: 0 件
CI: PENDING

glossary-check: 設計文書の廃止語「作業ツリー」を worktree へ直した（d9f3fd8dd）

takemi-ohama

🤖 cross-review | round 5 | claude | REQUEST_CHANGES

決め直しの事前判定を耐久ワークフローの前へ出したことで、(1) キューの経路では接頭辞が耐久ステップの中で計算されるため旧世代の接頭辞が再生され、(2) 実行条件と形を決めた設定の照合より先に退避と控えの上書きが走る。2 点を直す。

takemi-ohama

🤖 cross-review | round 5 | kiro | APPROVE

指摘なし。

- 事前判定は実行条件の評価と形を決めた設定の照合を先に行い、飛ばす・食い違うプランでは版を照会せず退避もしない - キューの接頭辞は耐久ステップ admit_step の中で決まり再開で再生されるため、決め直したら launch_queue を fresh で開く Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

takemi-ohama · 2026-11-04T15:16:09Z

🔧 /ndf:fix サマリ | round 5 | commit `aa14143`

対応件数: critical=0 / major=2 / minor=0（合計 2 件）
決着: 2 件 / 見送り: 0 件 / 却下: 0 件
CI: PENDING

設計の承認ゲート 1 の利用者の指摘に合わせる。 - 要求: 予算と宣言の値を参照で持つ部分を外し、受け入れ条件 1 を版数と記録の PR に縮め、秘密の入力の受け入れ条件を消した（以降の番号を詰めた） - 決定 4 を「設定の値と予算は参照にせず、組んだ時点の設定とも照らさない」にした - 不変条件から形を決めた設定の照合（旧 I7）と秘密の設定（旧 I9）を消し、I3 と版の決め直しの事前判定から設定の照合の段を外した - 参照の種類から setting・budget を、構成要素から設定の契約を外し、差し込みを書く 7 ファイルを検索で数え直した - 用語集から「形を決めた設定」を消した Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

- 処理の流れの「流れの決まり」から、退避の手順と耐久ワークフローの世代の決まりを別の節へ分けた（119 行の章のうち、この部分は 26 行の 1 節だった）。節を指す参照を新しい節の名前へそろえた - 100 字を超える文 3 つと、決定の記録の長い文を分けた。内容は足していない - 「参照の段」を、参照の仕組みの Pull Request・参照の解決へ言い換えた Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

takemi-ohama

🤖 cross-review | round 6 | claude | REQUEST_CHANGES

キューの経路で、(1) プランの耐久ワークフローより前に動く worktrees_step が上位の欄の参照を解決しないまま worktree を作る、(2) 耐久ワークフローの接頭辞の中身鍵がファイルのバイト列のままで、I7・決定 7 のプランのハッシュと判定が食い違う。2 点を設計に書き足す。

takemi-ohama

🤖 cross-review | round 6 | codex | REQUEST_CHANGES

修正指摘2件。根拠: Mission / Vision / Value 2 / Value 3 / Value 5 / Value 7。

- キューがステージの前に worktree を作る耐久ステップは、上位の欄に参照を持つプランを作らない - 耐久ワークフローの接頭辞の中身鍵をプランのハッシュから取る - 本番のエントリポイントの契約に、承認した版と照らす版の参照を足す - 決め直しの事前判定の前に流し直しの判定を置き、流さない完了したプランを外す Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

takemi-ohama · 2026-11-05T01:04:34Z

🔧 /ndf:fix サマリ | round 6 | commit `e244568`

対応件数: critical=0 / major=4 / minor=0（合計 4 件）
決着: 4 件 / 見送り: 0 件 / 却下: 0 件
CI: NONE

takemi-ohama

🤖 cross-review | round 7 | codex | APPROVE

今回の差分に critical / major の修正指摘はありません。根拠: Mission / Value 3 / Value 7 / Value 8。

takemi-ohama

🤖 cross-review | round 7 | kiro | APPROVE

指摘なし。前ラウンド（round 6）の 4 件（worktrees_step が上位の欄の参照を解決せず worktree を作る、耐久ワークフローの接頭辞の中身鍵がファイルのバイト列、手動 --version に版の照合が無い、完了したプランへの不要な origin・PR 照会）が、構成要素の表・resolve_head の説明・流れの決まり・耐久ワークフローの世代・入出力の契約・テスト設計 4/6/7 で整合して反映されている。不変条件 I3・I5・I6・I7、ドメインイベント E9、データ構造の version/tip の種類の定義とも矛盾しない。実装者が違うものを作る食い違いは見当たらない。

takemi-ohama · 2026-11-05T01:07:32Z

MVV 判定（関門 1（設計の承認））

判定: follow（関門を省いた。利用者が承認した MVV を事前の許可として扱う）
根拠: Mission / Vision / Value 2 / Value 3 / Value 4 / Value 5 / Value 6 / Value 7 / Value 8 / C1 / C2 / C4 / P1（プロジェクト MVV: approved・版 5）
時刻: 2026-11-05T01:07:10+00:00
ログ: /home/ubuntu/.local/state/ndf/mvv-gate.jsonl の 2026-11-05T01:07:10+00:00 の行