古い版の NDF が新しい版で足した .ndf/project.json の項目を「知らない項目」として拒み、プラグインを更新するまで手順 0 が止まる #1706

何を見つけたか

.ndf/project.json に新しい版で足した項目が入ると、それより古い版の NDF は宣言全体を「形に合わない」として止める。 宣言の形は pydantic のモデルが知らない項目を拒む（plugins/ndf/scripts/lib/schema.py の 68 行。extra="forbid"）。版をまたいだ読み取りの扱いが無いため、リポジトリの宣言を新しい版の形へ進めた時点で、古い版のプラグインを読み込んだままのセッションの project-decl.py check が stopped を返す。

実測（2026-10-03、/work/ai-plugins の宣言に対して）:

ci_jobs・ci_exempt は 10.17.58 で足した項目で、宣言へ足したのは #464 の実装のコミット 0564c98（PR 1697 → PR 1701 で develop へ）である。

どこで見つけたか

スプリント m464（PR #1701 ）の後、10.17.58 のリリースまでの間。10.17.57 を読み込んだセッションで手順 0（宣言の確認）が終了コード 3 で止まり、プラグインを 10.17.58 へ更新するまで先へ進めなかった。

なぜこの変更の範囲外なのか

#464 の受け入れ条件は宣言へ ci_jobs・ci_exempt を足して cross-refactoring が読むことであり、宣言の形を版をまたいで読む規則（古い版が新しい項目をどう扱うか）は含まない。宣言の契約全体に関わり、即時修正の 4 条件の 2 つ目（契約に触れない）を満たさない。

直さないと何が起きるか

• 宣言に項目を足すたびに、開発版や古い正式版を使っている利用者・セッションの手順 0 が止まる。このリポジトリでは毎スプリント起こり得る（宣言を足す実装が develop へ入ってから、本番を読み込むまでの間）
• チームの一部だけがプラグインを更新したリポジトリでは、更新していない人の工程がすべて止まる

直し方の候補

• 宣言に形の版を持たせ、読む側の版より新しい形なら「プラグインを更新する」と案内して止める（理由が分かる止まり方にする）
• 知らない項目は警告にして読み飛ばし、必須の項目と型の誤りだけで止める（extra="ignore" 相当。綴りの誤りを拾えなくなる得失がある）

受け入れ条件（案）

• 古い版の NDF が新しい版の項目を持つ宣言を読んだとき、何をすればよいか（更新か、項目の無視か）が出力から分かる
• 綴りを誤った項目は、今と同じく検査で拾える

直す場所

• 現象レイヤー: 古い版の NDF の手順 0（project-decl.py check）が stopped で止まる
• 修正レイヤー: plugins/ndf/scripts/lib/schema.py の Shape（65 行）と load_shape（106 行）。.ndf の宣言すべてが共有する読み取りの規則と、宣言の形の版（plugins/ndf/skills/development-workflow/schemas/project.schema.json の version は const: 1 で、形の版を持たない）
• 修正方針: 統合。Shape は .ndf/project.json のほか、.ndf/supervise.json （supervise_lib/decl.py ）・.ndf/release.json （release-steps.py ）・.ndf/estimate.json （lib/estimate_records.py ）・.ndf/mvv.json （lib/project_mvv_decl.py ）の読み取りも継ぐため、新しい版の項目を古い版が読む規則を load_shape / Shape の 1 か所で決め、すべての宣言を同じ形で直す。上の「直し方の候補」の 2 つからの選択は残す

関連

• .ndf/ の定義ファイルに作成・更新の定義が無く、チーム単位と個人単位の区別と .gitignore による分離も無い #1512（.ndf/ の定義ファイルに作成・更新の定義が無い）
• cross-refactoring のテストの宣言が整形・静的解析を含まず、違反が継続的統合まで残る #464（ci_jobs・ci_exempt を足した変更）

由来

PR #1701（スプリント m464。issue #464 #1692）の振り返りで確認した。