cross-refactoring の --scope がファイル単位のため、issue と関係の無い既存の関数まで整理し、変わった範囲が issue から読めない

[takemi-ohama]

何を見つけたか

/ndf:cross-refactoring の --scope はファイル単位のため、issue が触った箇所と関係の無い既存の関数まで整理の対象になる。 マイルストーン v10.11.0 の実装 Pull Request 4 本で起きた。いずれも --scope は設計の「作るもの」のファイルに限っていた。

Pull Request	issue	コミット数	構造改善が及んだ既存の箇所（PR 本文の記載）
#591	#527	28	worktree-common.sh の _wt_tokenize / wt_extract_write_target の抽出、wt_base_branch と wt_production_branch の重複統合、WT_DECLARATION_FILE の定数化
#593	#565	26	workflow-common.sh の wf_state_dir・_wf_classify_stages・wf_report・_wf_missing_before_pr など。本文に「#565 の読み取りの変更とは別の箇所（実行証跡の案内）にも及んでいる」
#594	#499	25	AGENTS.md の分割に伴い版数の検査 check-doc-staleness.py とそのテストを範囲に入れ、検査全体へ現状固定テスト 10 件・構造改善 7 件を適用（期待出力を変えた 7 件は取り消し）
#609	#566	26	check-doc-staleness.py の check_version_examples の分割、RepositoryMetrics などの引数オブジェクト、POINT_VERSION_SPECS への正規表現の集約

振る舞いは現状固定テストで守られ、ndf v10.11.0 のリリース後テスト（開発版・本番とも）でも一致を確かめた。壊れたものは無い。 課題は、変わった範囲が issue の範囲から読めないことである。

同じ事象は他のリポジトリと後のまとまりでも起きている。

Pull Request	issue	構造改善が及んだ既存の箇所	扱い
devbasex/devbase#191	devbasex/devbase#189	--scope に変更したファイル（lib/devbase/commands/container.py ほか）を渡したところ、PR が触れていない既存の cmd_scale の extract_method（major）が採用された	要求仕様の「依頼範囲外のリファクタリングは行わない」に反するため適用を止め、devbasex/devbase#192 へ起票
#757（v10.15.0）	#657	--scope を実装の触るファイルより広く取ったため、課題と無関係な既存の関数への現状固定テストが 301 行入った	以後のまとまりの実装 PR では --scope を実行計画の「触るファイルと節」に絞った

どこで見つけたか

• plugins/ndf/skills/cross-refactoring/SKILL.md の --scope PATH...（「提案が無制限に広がらないよう必須」）
• 上の 4 本の Pull Request と、その改修計画のコメント
• 範囲の規約: refactoring の references/code-smells.md「手を付ける範囲」は、今回変更した関数の
  呼び出し元・呼び出し先と、同じファイル・同じモジュールの関連箇所までを直す範囲とする。
  development-workflow の references/stage-notes.md の構造改善の段落も同じ範囲を指す。
  4 本の広がりは、この規約どおりである

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

各 issue の受け入れ条件は検査や記録の不具合に閉じており、cross-refactoring の範囲の決め方は含まれない。

直さないと何が起きるか

• リリース後テストの対象が issue の受け入れ条件から決まらなくなる。 v10.11.0 では worktree のガードと控えの積み上げ・関門を、構造改善が及んだことを理由に重点の確認へ足した
• 並行する他の Pull Request と触る箇所が後から重なる。 parallel-work.md の下限 5（同じファイルを触るものを並行させない）は走らせる前に判断するが、構造改善が広げる範囲は走らせた後にしか分からない。Update: #526 design で表から導ける値を数え直し、値を足す設計で既存の規則を集める #587（設計文書で、同じ文書の表から導ける値を数え直さずに書いている #526）の構造改善で design/SKILL.md が大きく変わり、レビューで設計を変えても Pull Request の本文が古いまま残る #545 の実装は最新の develop から始め直した
• 1 本の差分が大きくなり、実装レビューの読む量が増える
• 同じファイルが別の issue の構造改善で続けて書き換わる。check-doc-staleness.py は #499 版数と配布の扱いを docs/versioning-and-distribution.md へ移し、AGENTS.md を定義へ戻す #594 と 検査 J に版の形の表と次の開発の例を例どうしで比べる規則を足す（#566） #609 で 2 回整理された

考えられる形（決めるのは設計の工程）

案	中身	気になる点
提案を差分の近傍へ絞る	Pull Request が変更したシンボルとその呼び出し元に限る選択肢を足す	変更した関数の外にある重複は拾えなくなる。「手を付ける範囲」の規約（同じファイル・同じモジュールまで）と衝突するため、規約の側も変える判断になる
範囲外の兆候は起票に回す	--scope の中でも、差分に触れないシンボルへの提案は採用せず out-of-scope へ回す	起票が増える
今のまま、記録を強める	差分に触れないシンボルへ及んだ項目を改修計画と PR 本文で分けて示し、リリース後テストの重点へ渡す	範囲は広がったまま
--scope を実行計画の「触るファイルと節」から与える	v10.15.0 の issue-plan-strategy/references/execution-plan.md は実行計画の行ごとに「触るファイルと節」の列を持つ。--scope をその列のファイルに限る。#757 の後の実装 PR はこの運用で回した	ファイル単位のままなので、同じファイルの別の関数への提案は残る。運用は cross-refactoring/SKILL.md にも development-workflow/references/stage-notes.md にも書かれていない

案と接する課題

案	接する課題
範囲外の兆候は起票に回す	起票は #851 の起票の部品（issue-file）を呼ぶ
--scope を実行計画の「触るファイルと節」から与える	#866 が issue-plan-strategy の実行計画の状態遷移をスクリプトにする。実行計画から --scope を組む処理はそのスクリプトの出力の読み手になる
どの案でも	#494（飛ばしてよい条件）と同じ「要らない改善を回さない」系統。ラウンドと所要を減らす

暫定の運用は先に切り出せる。 「--scope を実行計画の『触るファイルと節』に絞る」を
development-workflow/references/stage-notes.md の構造改善の段落へ書くだけなら、案の選択を待たない。

決めること

• 上の 4 案のどれを採るか
• 差分の近傍へ絞る案を採るなら、refactoring/references/code-smells.md の「手を付ける範囲」の規約を変えるか
• 暫定の運用を stage-notes.md へ先に書くか

由来

PR #617（ndf v10.11.0 の配布）の振り返り。devbasex/devbase#191（2026-09-17）と、v10.15.0 の振り返り（issue #550 のコメント、PR #757）で同じ事象を確認した。

関連

• cross-refactoring を飛ばしてよい条件が、どの Skill にも書かれていない #494 — cross-refactoring を飛ばしてよい条件（文書だけの Docs: README.md を規約の役割へ合わせ、Skill 執筆規約を AUTHORING.md へ改名する（#500） #612 は対象が無く中止した）
• cross-refactoring: テスト整備ラウンドが pytest の収集しないファイルへテストを足し、実行されないまま検証を通る #620 — テスト整備ラウンドが pytest の収集しないファイルへテストを足す
• cross-refactoring の --scope 関門が --baseline-test の「.」を起点にすると配下のテストを範囲外と誤判定する #589 — --scope の関門が . を起点にすると誤判定する
• issue-plan-strategy: multi-PR の足場づくりと実行計画の状態遷移をスクリプトにする #866 — issue-plan-strategy の実行計画の状態遷移のスクリプト化
• 基盤: 起票の部品（起票先の解決・重複の検索・骨格の検査つき起票・由来の付与） #851 — 起票の部品。範囲外の兆候を起票に回す案で使う

[takemi-ohama]

同じ事象を devbasex/devbase PR #191（issue #189）の作業中に確認した。--scope に変更したファイル（lib/devbase/commands/container.py ほか）を渡したところ、提案ラウンドで PR が触れていない既存の cmd_scale の extract_method（major）が採用され、要求仕様の「依頼範囲外のリファクタリングは行わない」に反するため適用を止めた（範囲外として devbasex/devbase#192 に起票）。

[takemi-ohama]

同じ事象を PR #757（#657 の中断と再開）の作業中に確認した。--scope を実装の触るファイルより広く取ったため、課題と無関係な既存の関数への現状固定テストが 301 行入った。以後のまとまりの実装 PR では --scope を計画ファイルの「触るファイルと節」に絞った。v10.15.0 の振り返り（issue #550）で拾った。

[takemi-ohama]

観測の追加（devbasex/devbase#252、ndf 10.17.0）。テスト整備ラウンドでも同じことが起きる。

• 差分は containers/base/Dockerfile の 2 か所（apt の一覧へ shellcheck を足す・版の確認へ shellcheck --version を足す）と、それを固定するテスト 1 本
• --scope containers/base/Dockerfile tests/containers で起動したところ、テスト整備ラウンド 1〜2 が採用 10 件のすべてを差分と関係しない既存の命令（Chrome/chromium の分岐・npm のグローバル・AWS CLI / session-manager-plugin / gcloud の arch の case・bao・agy の失敗の伝播）の現状固定テストへ向け、4 コミット・約 350 行を積んで push した
• Dockerfile は手元のテストでは静的な形しか見られず、続く提案ラウンドが同じ範囲を書き換えると建てるまで壊れたことが分からない。そのためテスト整備ラウンド 2 の途中でループごと止め、4 コミットを revert した

差分の行（hunk）で範囲を絞る手が入れば、テスト整備ラウンドの提案もそこへ寄せられる。