before-changeのデフォルトlimitがIssue単位ではなくドキュメント単位で切られる

[Kewton]

概要

before-change コマンドのデフォルト --limit 10 がドキュメント単位で適用されるため、関連Issueが多いファイルでは重要なIssueの情報が切り捨てられる。

再現手順

cd commandindextest/retest5/mpc_p3

# デフォルト(limit=10): Issue #104(7件) + #112(3件) = 10件で打ち切り
commandindexdev before-change src/config/z-index.ts
# → 8 issue(s), 10 finding(s) — #299など後半のIssueが表示されない

# limit=50: 全8 Issue, 44件が返る
commandindexdev before-change src/config/z-index.ts --limit 50
# → 8 issue(s), 44 finding(s) — #104,#112,#113,#114,#225,#299,#99 全て表示

# whyコマンドとの比較: こちらは全Issue表示
commandindexdev why src/config/z-index.ts
# → Issue #104, #112, #113, #114, #225, #299, #99

期待される結果

デフォルトlimit=10でも、全8 Issueの少なくとも設計ポリシーまたは代表文書が表示される。

実際の結果

ドキュメント数でlimitされるため、最初のIssue #104が7件（設計1+レビュー5+workplan1）を消費し、2番目のIssue #112が3件でlimit到達。残りの6 Issue（#113, #114, #225, #299, #99）の情報が一切表示されない。

問題の影響

before-changeはAIエージェントが変更前に設計制約を確認するコマンド。whyで見えるIssue #299の設計判断がbefore-changeでは表示されないのは、AIの判断品質に直接影響する。

改善方針（推奨: 案1+案4の組み合わせ）

採用案: Issue単位のlimit + ドキュメント優先度ソート

具体的な変更内容

1. --limit のセマンティクス変更: ドキュメント数の上限 → Issue数の上限に変更（breaking change）
2. Issue単位グルーピング: before_change.rs のlimit適用前にIssue単位でグルーピングし、各Issueから代表ドキュメント（設計ポリシー1件 + workplan 1件）を優先選出
3. Issue間ソート: セマンティックランキング使用時はIssue内最大similarityでIssue間をソート。未使用時はissue_number降順（新しいIssue優先）
4. Issue内ドキュメントソート: relation_priority順（has_design > has_workplan > has_review > modifies）

不採用案と理由

• 案2（グルーピング+折りたたみ）: UIの複雑化に対して効果が限定的
• 案3（デフォルト引き上げ）: 根本解決にならない。ドキュメント数が多いリポジトリでは同じ問題が再発

受け入れ基準

1. --limit N が Issue数 の上限として機能すること
2. 各Issueから最低1件（設計ポリシー優先）、最大2件（設計ポリシー+workplan）のドキュメントが表示されること
3. limit到達時は、セマンティックランキング使用時はIssue内最大similarityでIssue間ソート、未使用時はissue_number降順
4. CLIヘルプの--limit説明が新セマンティクスを反映していること（main.rs, help_llm.rs, BEFORE_CHANGE_AFTER_HELP）
5. 既存のE2Eテスト（before_change_limit_respected）が新セマンティクスに対応して更新されていること
6. 複数Issueに跨がるlimit検証テストが追加されていること
7. relation_priority の順序が has_design=0 > has_workplan=1 > has_review=2 > modifies=3 であること

影響範囲

変更対象ファイル（変更はbefore-changeコマンド内部に閉じる。他サブコマンドへの影響なし）

ファイル	変更内容
src/cli/before_change.rs	limit適用ロジック変更（Issue単位グルーピング導入）、relation_priority修正、rank_by_max_similarityのIssue単位集約
src/main.rs	--limit ヘルプ文言更新（Maximum number of issues to show）
src/cli/help_llm.rs	LLM向けヘルプのlimit説明更新
src/output/mod.rs	BeforeChangeFinding / BeforeChangeResult 構造体の変更検討
src/output/human.rs	Issue単位グルーピング表示対応
src/output/json.rs	JSON出力のIssue単位対応（フラットfindings維持 + displayed_issues追加）
src/output/llm.rs	Issue単位グルーピング表示対応
src/output/path.rs	出力フォーマッタ対応
tests/e2e_before_change.rs	テスト更新・追加

セマンティックランキングとの相互作用

• rank_by_max_similarity(): ドキュメント単位 → Issue単位に集約（Issue内最大similarity）→ 二段階ソート
• findings_without_ranking(): フォールバックソートをissue_number降順に変更、relation_priority順序修正

後方互換性

• --limit のセマンティクスが「ドキュメント数」から「Issue数」に変更される breaking change
• JSON出力: フラットなfindings配列は維持しつつ displayed_issues を追加（最小限の変更）
• パフォーマンス影響: 軽微（O(n)のHashMap操作、n=数十件以下）

変更不要ファイル

• src/search/related.rs: 影響なし
• src/indexer/symbol_store.rs: 影響なし（find_knowledge_by_issueのSQL変更不要）
• src/cli/why.rs: 影響なし（参考実装として参照のみ）

テスト環境

• commandindex 0.1.0 (スキーマv4)
• CommandMateリポジトリ（2910ファイル、124690セクション）
• src/config/z-index.ts: 8 Issueに関連するファイル

[Kewton]

Closed via PR #183 merged to main.