入口・受け渡しのファイル・設定・環境変数の契約を 1 か所に宣言し、宣言の外を検査で落とす #2336

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

依頼（原文）

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

何をするか

NDF の入口 91 本（plugins/ndf/scripts 直下 52・Skill の scripts 直下 39）と、入口の間で受け渡すファイル（名前 114 種類）・.ndf/ の設定 15 種類・環境変数 56 種類について、受け取るもの・返すもの・書く状態・終了コードを 1 か所の宣言（契約の一覧）に書き出す。今の振る舞いを写すだけで、変えない。あわせて、新しいコードが実行の核と契約を通らなければ構造の検査が落とす（今の外れは許可の一覧に載せ、一覧は減る方向にしか変えられない）。

同じ値を 2 か所が持つ宣言（例 本番のブランチ）、メインディレクトリと worktree のどちらから読むかの不一致、呼ばれない死んだコードもここで片付ける。

受け入れ条件

1. 入口 91 本と受け渡しのファイル・設定・環境変数すべてについて、入力・出力・書く状態・終了コードが 1 か所の宣言にある
2. 宣言に無い入口・ファイル・引数・環境変数・設定のキーを構造の検査が落とす。今の外れは許可の一覧にあり、一覧を増やす変更を検査が落とす
3. 1 つの値を持つ設定ファイルが 1 つだけになり、どこ（メインディレクトリか worktree か）から読むかが宣言に書かれる
4. 子の課題それぞれを、閉じた（解消を確かめた）か残した（理由つき）かに分けて本文に記録する

進め方

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

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

（書き手: 起票者、日付: 2026-11-01。大方針 #2335 の組み直しで AI が書いた本文で、利用者の指示の原文としては扱わない）

利用者の指示の原文は #2335 の「調べ方」に引用された次の 4 文である。

「異常系処理とログ出力、異常時の回復処理が統一されていないから起こる不具合・課題が多い。1 件ずつ対処してもきりがない」「内部データ構造と出力のフォーマットの不統一の影響も大きそう」「NDF は Skill の Script 化から発展してきたため、内部データ構造や入出力契約がほぼ整理されていない」「出力だけでなく入力もそろえるべき」

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

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

（書き手: AI の起動指示、日付: 2026-11-01。この要求の工程の進め方の指示で、要求の中身ではない）

起票者の推定

題・本文のうち、利用者の指示の原文（上の 4 文）に無く、起票者が推して足した条件。承認ゲート 1 で利用者が確かめるまで、利用者の決定として扱わない。

目的

• NDF のエントリポイントが受け取るもの・返すもの・書く状態・終了コードを、Skill の本文・README・docstring に散らさず 1 か所で読めるようにする。呼ぶ側（Skill の本文・プランの雛形・conductor）がエントリポイントごとの違いを覚えて書くことで起きる渡し忘れ・渡し違い・読み違い（異常系・ログ・回復とデータ・入出力の形を 1 つの実行の核へ集め、異常系の課題 103 件を型ごとにまとめて解く #2335 の型 A・E）の出所を断つ
• 契約の一覧の外へ新しい入力・出力が増えることを構造チェックで止め、異常系・ログ・回復とデータ・入出力の形を 1 つの実行の核へ集め、異常系の課題 103 件を型ごとにまとめて解く #2335 の柱 P1〜P8（マイルストーン 29・30）が正として使う契約の一覧を先に用意する

前提

• 前提 1: 「エントリポイント」は、plugins/ndf/scripts 直下と plugins/ndf/skills/*/scripts 直下にあり、テストと実験版（experimental/）を除くファイルのうち、if __name__ == "__main__": を最上位に持つ .py と、実行される .sh を指す。数え上げの規則は設計で 1 つに決め、検査とテストが同じ規則を使う。2026-11-01 の 91 本は参考値で、規則が拾った本数と食い違えば規則の本数を正とし、差を設計に記録する
• 前提 2: 「受け渡しのファイル」は、あるエントリポイントが書き、別のエントリポイントか Skill の手順が読むファイル（状態・記録・結果）を指す。1 つのエントリポイントの中だけで作って消す一時ファイルは含まない
• 前提 3: 振る舞いを変えてよいのは、受け入れ条件 5〜8 の片付け（同じ値を持つ設定の 1 か所化・読む場所の不一致の解消・死んだコードの削除）だけである。それ以外は今の振る舞いを契約の一覧へ写す
• 前提 4: 実行の核はまだ無い（マイルストーン 29 で作る）。この課題の構造チェックは「契約の一覧の外」を落とし、「核を通らない」ことは見ない
• 前提 5: 設計は 異常系・ログ・回復とデータ・入出力の形を 1 つの実行の核へ集め、異常系の課題 103 件を型ごとにまとめて解く #2335 の設計（データの型の書き方・実行の核の形）の後に行う。異常系・ログ・回復とデータ・入出力の形を 1 つの実行の核へ集め、異常系の課題 103 件を型ごとにまとめて解く #2335 の設計が契約の一覧の書き方（JSON・JSON Schema・Python の型など）を決めていれば従い、決めていなければこの課題の設計が決める
• 前提 6: 既存の利用者のリポジトリにある .ndf/ の設定は、利用者に書き換えを求めない。1 か所へ寄せた値の古い置き場は、読み込みの側で新しい置き場へ読み替えて受ける（古い置き場の値があり新しい置き場に無いとき、古い値を使う）。古い置き場を読むことは契約の一覧に「移行のための読み」として書く
• 前提 7: 構造チェックは既存の scripts/check-script-structure.py（CI のジョブとして走る）へ規則を足すか、同じ形（結果の 1 行 JSON・例外リストは 1 項目 1 ファイル）の別のチェックとして足す。どちらにするかは設計が決める
• 前提 8: 外部から呼ばれる形（エントリポイントのパス・副命令・引数の名前）は変えない。引数の名前をそろえる（--root への統一など）のは柱 P8（入口の引数・環境変数・設定の受け取り方を 1 つの読み込み部品にそろえる #2341）の範囲である

対象範囲

含む:

• 前提 1 のエントリポイントすべての契約（入力: 引数・環境変数・.ndf/ の設定のキー・標準入力。出力: 標準出力の形・書くファイル。書く状態。終了コードとその意味）を 1 か所の契約の一覧へ書くこと
• 受け渡しのファイル・.ndf/ の設定・環境変数それぞれの、書くエントリポイントと読むエントリポイント、置き場（メインディレクトリか worktree か、ほかの置き場か）を契約の一覧へ書くこと
• 契約の一覧の外にあるエントリポイント・受け渡しのファイル・引数・環境変数・設定のキーを落とす構造チェックと、今の外れを載せる例外リスト（増やす変更を落とす）
• 同じ値を 2 か所が持つ設定の 1 か所化（少なくとも本番のブランチ。release の雛形が本番のブランチを既定ブランチへ後退させず、worktree.json に production_branch が無いと本番のプランを組めない #2097）と、古い置き場からの読み替え
• 読む場所の不一致の解消（少なくとも 全体テストの CI 待ちが、PR で外したチェックをメインディレクトリの宣言から読んで待ち続ける #2317・cross-refactoring: 戦略の宣言をメインディレクトリから読み、Pull Request が変えた宣言（足した静的解析の suite）が検証に入らない #1709 で見つかったもの）
• 棚卸しで呼び手が無いと分かったエントリポイント・関数の削除
• 子の課題 17 件の再現の手順を通し、閉じたか残したかを理由とともに記録すること

含まない:

• 実行の核の作成と、核を通らないことの検査（異常系・ログ・回復とデータ・入出力の形を 1 つの実行の核へ集め、異常系の課題 103 件を型ごとにまとめて解く #2335 の受け入れ条件 1・マイルストーン 29）
• 結果の形（ok / gate / stopped）・記録とログ・データの型と名前の対応表・出力の 1 行 JSON 化・入力の読み込み部品（柱 P1・P2・P6・P7・P8。結果の契約をそろえ、失敗・未収束・判定できないを ok で返す経路を無くす #2337〜入口の引数・環境変数・設定の受け取り方を 1 つの読み込み部品にそろえる #2341）
• 引数の名前をそろえること・sys.argv を手で読むエントリポイントを argparse へ移すこと（柱 P8。入口の引数・環境変数・設定の受け取り方を 1 つの読み込み部品にそろえる #2341）
• 持ち主・上限・実行時点の解決（柱 P3・P4・P5。実行の持ち主と後片付けを核に持たせ、残骸と並行の衝突で止まらないようにする #2342〜プランは値でなく参照を持ち、実行の直前に解決して照合する #2344）
• plugins/ndf の外（playwright-kit・mcp-*・factory/）のスクリプトと、hook が直に呼ぶモジュールの契約
• 子の課題を 1 件ずつ直す Pull Request（再現しなくなったかを確かめるだけ。残ったものは理由を添えて残す）

ドメインイベント

用語

受け入れ条件

• 1. 前提 1 の数え上げの規則が拾うすべてのエントリポイントについて、入力（引数・環境変数・.ndf/ の設定のキー・標準入力を読むか）・出力（標準出力の形・書くファイル）・書く状態・終了コードとその意味が、契約の一覧の 1 項目にある。受け渡しのファイル・.ndf/ の設定・環境変数それぞれについて、書くエントリポイント・読むエントリポイント・置き場（メインディレクトリ / worktree / そのほか）が契約の一覧にある
• 2. 契約の一覧はリポジトリに 1 つだけで、同じ契約を別のファイル（README・Skill の本文・docstring）が写して持たない（指す）
• 3. 次のどれかを足す変更を、構造チェックが終了コード 0 以外で落とし、結果の items に該当のファイルとキーを出す: 契約の一覧に無いエントリポイント・契約に無い引数・契約に無い環境変数の読み・契約に無い .ndf/ の設定のキーの読み・契約に無い受け渡しのファイルの書き。今の外れは例外リストの項目として載り、例外リストに載った外れは落とさない
• 4. 例外リストへ項目を足す変更（足した項目が今の違反に当たっても）を構造チェックが落とす。例外リストの項目を消す変更と、違反に当たらなくなった項目を残す変更は、今の unused-allow と同じく区別できる（消すのは通り、残すのは落ちる）
• 5. 本番のブランチを持つ設定が 1 か所だけになる（worktree.json の production_branch と project.json の delivery のどちらか。どちらに寄せるかは設計が決める）。棚卸しで見つかったほかの「同じ値を 2 か所が持つ設定」も 1 か所になるか、残す理由とともに例外リストに載る
• 6. 1 か所へ寄せる前の古い置き場だけに値を持つ .ndf/ で、寄せた値を読むエントリポイントが寄せる前と同じ値を得る（前提 6。テストで確かめる）
• 7. 契約の一覧の各受け渡しのファイルと .ndf/ の設定について、読む場所（メインディレクトリか worktree か）が 1 つに決まって書かれ、エントリポイントがその場所から読む。全体テストの CI 待ちが、PR で外したチェックをメインディレクトリの宣言から読んで待ち続ける #2317（Pull Request で外したチェックをメインディレクトリの宣言から読む）と cross-refactoring: 戦略の宣言をメインディレクトリから読み、Pull Request が変えた宣言（足した静的解析の suite）が検証に入らない #1709（戦略の宣言をメインディレクトリから読む）の再現の手順で、worktree の側の値が使われる
• 8. 棚卸しで呼び手が 0 と分かったエントリポイントと最上位の関数が消えているか、残す理由（外部から呼ばれる・利用者が手で打つ など）とともに契約の一覧に載る。消した後に全体テストと参照切れのチェック（scripts/check-markdown-links.py・scripts/check-cross-skill-refs.py）が通る
• 9. 受け入れ条件 5〜8 の片付け以外で、エントリポイントの外から見える振る舞い（引数・出力・終了コード・書くファイル）が変わらない。全体テストが変更の前と同じく通る
• 10. 子の課題 17 件（実行する版を解決する層を 1 つにし、開発中の版と配布済みの版の食い違いを根本原因の場所で直す #715 NDF のスクリプト全体をモデル・クラスの設計からやり直し、分割と重複の整理を 1 回で行う #1142 .ndf/ の定義ファイルに作成・更新の定義が無く、チーム単位と個人単位の区別と .gitignore による分離も無い #1512 metrics.aggregate が本番から呼ばれず、#933 の後の cross-refactoring の状態ファイルの形とも合わない #1601 このリポジトリの runtime-plugin-validate.yml の 9 ジョブがテストの宣言に無く、cross-refactoring の項目が壊しても手元で拾えない #1694 cross-refactoring: 戦略の宣言をメインディレクトリから読み、Pull Request が変えた宣言（足した静的解析の suite）が検証に入らない #1709 release: plugin_dir と changed-plugins がプラグインの置き場を ndf・playwright-kit の名前で決め打ち、他のリポジトリで package-plugin の手順が止まる #1756 CI のチェックの結論を失敗と数える集合が lib/gh_checks.py と merged_lib/checks.py で別々にあり、取り消しと stale の扱いが食い違う #1774 merged / lib README: 基盤待ち（終了コード 75）と merge-when-green の引数が正本に無い #1787 宣言の無いリポジトリで指示書の既定が指示書のチェック（3 つ）と承認資料（2 つ）で食い違い、KIRO.md の変更が承認資料に載らない #1968 .ndf/project.json の計測値（ファイル数・テストの時間）が実行のたびに書き戻され、追跡ファイルを汚す → 宣言と計測値を分ける #2010 テストのコマンドを .ndf/supervise.json の test と .ndf/project.json の test.suites の 2 か所が持つ → 宣言の 1 か所にする #2011 サブモジュールのリポジトリでメインディレクトリを .git/modules の下と取り違え、project-decl.py check が宣言を「無い」と返す #2054 release の release-steps.md に、範囲の PR と notes --check-state（承認の材料）の打ち方が無い #2060 release の雛形が本番のブランチを既定ブランチへ後退させず、worktree.json に production_branch が無いと本番のプランを組めない #2097 require-groups の例外リストに残した 11 本へ依存の宣言を足す #2235 全体テストの CI 待ちが、PR で外したチェックをメインディレクトリの宣言から読んで待ち続ける #2317）それぞれについて、再現の手順を通した結果と、閉じた（解消を確かめた）か残した（理由つき）かが、この課題の本文の「子の課題の判定」の節に 1 行ずつある。閉じた課題には閉じた理由のコメントがある

非機能の条件

影響

検証手段

前提とする取り決め

境界

未決

子の課題の判定

（受け入れ条件 10 の記録の置き場。仕組みを入れた後に埋める）

進行

モード: — / 進め方: auto

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

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

• 判定: unknown（承認ゲート 1）
• 理由: 判定を読めない
• 根拠の項目: —
• 設計 Pull Request: NDF のエントリポイント: 入出力・設定・環境変数の契約を 1 か所で読み、宣言の外を構造チェックで止める（#2336） #2358
• 答え: approved
• 答え方: python3 /persistent/ai/.claude/plugins/cache/ai-plugins/ndf/10.27.6/scripts/sprint-state.py loop answer lroot 2336 --approved|--rejected

振り返り: #2367 (comment)