feat(snippet)

dev-reports/issue/168/issue-review/hypothesis-verification.md

@@ -0,0 +1,46 @@
+# 仮説検証レポート - Issue #168
+
+## 総合判定表
+
+| 仮説 | 判定 | 根拠 |
+|---|---|---|
+| 1. `issue --format llm` はパスのみ | ✅ Confirmed | issue.rs の format_llm がパスのみ出力 |
+| 2. `before-change` の snippet は null | ✅ Confirmed | BeforeChangeFinding に snippet フィールドなし |
+| 3. 先頭N文字をスニペットとして付与 | ⚠️ Partially Confirmed | snippet_helper 基盤は存在するが before-change に未適用 |
+| 4. has_design で採用方針/結論セクション優先抽出 | ❌ Unverifiable | セクション優先抽出ロジック未実装 |
+| 5. has_review で Executive Summary 優先抽出 | ❌ Unverifiable | セクション優先抽出ロジック未実装 |
+| 6. has_workplan で Phase一覧要約を抽出 | ❌ Unverifiable | セクション優先抽出ロジック未実装 |
+| 7. human/llm でインライン、json で snippet フィールド | ⚠️ Partially Confirmed | フォーマット分岐は存在するが snippet フィールド未定義 |
+
+## 詳細
+
+### 仮説1: issue --format llm はパスのみ (Confirmed)
+- `src/cli/issue.rs` の `format_llm()` はファイルパスのみ出力
+- `IssueDocumentEntry` は file_path, relation, doc_subtype のみ
+
+### 仮説2: before-change snippet は null (Confirmed)
+- `BeforeChangeFinding` (output/mod.rs) に snippet フィールドが存在しない
+- human/json/llm どのフォーマットでも snippet は出力されない
+
+### 仮説3: 先頭N文字スニペット (Partially Confirmed)
+- `src/cli/snippet_helper.rs` に `fetch_snippet()` が実装済み
+- impact コマンドや related 検索で既に使用されている
+- tantivy インデックスの body フィールドは STORED で保存済み
+- **ただし** before-change/issue コマンドではこのメカニズムが未適用
+
+### 仮説4-6: セクション優先抽出 (Unverifiable)
+- 現在のコードにはセクション指定抽出ロジックが存在しない
+- fetch_snippet() はパスベースで最初の非空ドキュメントを返すのみ
+- 将来の拡張として実装が必要
+
+### 仮説7: フォーマット別表示 (Partially Confirmed)
+- human/json/llm/path のフォーマット分岐は実装済み
+- snippet フィールド追加後は比較的容易に対応可能
+
+## 実装に必要な主要変更箇所
+
+1. **BeforeChangeFinding** に `snippet: Option<String>` 追加 (output/mod.rs)
+2. **IssueDocumentEntry** に `snippet: Option<String>` 追加
+3. **before-change** コマンドで snippet_helper を使用して snippet 付与
+4. **issue** コマンドで snippet 付与
+5. **各フォーマッタ** (human.rs, llm.rs, json.rs) で snippet 表示

dev-reports/issue/168/issue-review/original-issue.json

@@ -0,0 +1 @@
+{"body":"## 概要\n\n`issue --format llm` と `before-change --format llm` はファイルパスのリストのみを返す。「過去の判断を取り出す」というプロダクトコアを実現するには、各文書の**判断理由の要約（スニペット）**をインライン表示する必要がある。\n\n## 現状\n\n```bash\n# issue --format llm: パスのみ\ncommandindexdev issue 299 --format llm\n# → - dev-reports/design/issue-299-ipad-layout-fix-design-policy.md\n#   （中身は不明。読みに行く必要がある）\n\n# before-change --format json: snippet が NONE\ncommandindexdev before-change src/config/z-index.ts --format json\n# → findings[].snippet: null（全件）\n```\n\n## 期待される結果\n\n```markdown\n# Issue #299 関連ドキュメント\n\n## 設計\n- dev-reports/design/issue-299-ipad-layout-fix-design-policy.md\n  > z-index指定方式をinline style方式で統一。Z_INDEX定数を直接参照し、Tailwindのz-[60]を廃止。DRY違反を解消。\n\n## レビュー\n- dev-reports/review/2026-02-18-issue299-consistency-review-stage2.md\n  > Must Fix 1件: Toast.tsxがZ_INDEX.TOASTではなくz-50ハードコード。設計書の前提と不整合。\n```\n\n```bash\n# before-change --format llm: 判断理由がインライン\ncommandindexdev before-change src/config/z-index.ts --format llm\n# → - issue-299-ipad-layout-fix-design-policy.md (#299, has_design)\n#     > inline style方式で統一。Z_INDEX定数を直接参照。\n```\n\n## 対象バリュー\n\n- **判断再利用**: パスのリストでは判断を再利用できない。判断理由が直接読めて初めて「次の意思決定に接続」できる\n- **文脈先回り**: AIエージェントがbefore-changeの結果だけで設計制約を把握できる。各ファイルをfile.readする多段ステップが不要になる\n\n## 実装案\n\n- インデックス済みセクションの先頭N文字（150-200文字程度）をスニペットとして付与\n- `has_design`: 設計ポリシーの「採用方針」または「結論」セクションを優先抽出\n- `has_review`: summary-reportの「Executive Summary」セクションを優先抽出\n- `has_workplan`: Phase一覧の要約を抽出\n- `--format human`/`llm` でインライン表示、`--format json` で`snippet`フィールド\n\n## テスト環境\n\n- commandindex 0.1.0\n- CommandMateリポジトリ（2910ファイル、124690セクション）","title":"issue/before-changeの出力に判断理由のスニペットを付与する"}

dev-reports/issue/168/issue-review/stage1-review-context.json

@@ -0,0 +1,75 @@
+{
+  "must_fix": [
+    {
+      "id": "M1",
+      "title": "issue コマンドには tantivy IndexReader へのアクセスパスがない",
+      "description": "issue.rs の run() 関数は SymbolStore (SQLite) のみを使用しており、tantivy の IndexReaderWrapper を受け取っていない。snippet_helper::fetch_snippet() は IndexReaderWrapper を必要とする。issue コマンドに tantivy インデックスへのパスを渡す引数追加が必要であり、main.rs のサブコマンド呼び出し側にも変更が必要。",
+      "suggestion": "受け入れ基準に「issue コマンドが commandindex_dir から tantivy インデックスを開き、snippet_helper::fetch_snippet() を呼び出してスニペットを付与する」ことを明記する。run() の引数変更と main.rs 側の呼び出し変更を実装方針に含める。"
+    },
+    {
+      "id": "M2",
+      "title": "BeforeChangeFinding 型に snippet フィールドが不在",
+      "description": "現在の BeforeChangeFinding (output/mod.rs:318-325) には snippet フィールドが存在しない。before-change コマンドでスニペットを表示するには型定義の変更が必要。BeforeChangeFinding のコンストラクタ全箇所（5箇所）とテスト全箇所（7箇所）に影響する。",
+      "suggestion": "影響範囲として BeforeChangeFinding コンストラクタ全箇所（before_change.rs 内 5箇所）とテスト全箇所（7箇所）の変更を実装方針に明記する。snippet フィールドは Option<String> として追加し、デフォルト None で既存コードへの影響を最小化する。"
+    },
+    {
+      "id": "M3",
+      "title": "IssueDocumentEntry 型にも snippet フィールドが不在",
+      "description": "IssueDocumentEntry (knowledge.rs:178-183) には file_path, relation, doc_subtype のみ。issue コマンドでスニペット付き表示をするには snippet: Option<String> を追加する必要がある。テスト8箇所とフォーマッタ4関数に影響する。",
+      "suggestion": "IssueDocumentEntry に snippet: Option<String> フィールドを追加するか、IssueDocumentsResult レベルでスニペットを付与するパターン（enrich関数）を採用する。"
+    },
+    {
+      "id": "M4",
+      "title": "受け入れ基準が未定義",
+      "description": "テスト可能な受け入れ基準が定義されていない。文字数制限、空スニペット時の挙動、--format path 時の挙動等の境界条件が不明確。",
+      "suggestion": "受け入れ基準を追加：(1) issue --format human/llm でスニペット表示、(2) issue --format json で snippet フィールド、(3) before-change --format json で snippet フィールド、(4) --format path ではスニペット非出力、(5) 取得不可時は空/null、(6) 最大150-200文字。"
+    }
+  ],
+  "should_fix": [
+    {
+      "id": "S1",
+      "title": "セクション優先抽出ロジックの実現可能性と既存基盤との不整合",
+      "description": "fetch_snippet() は先頭N文字を返すだけで、特定セクション選択機能がない。セクション優先抽出には新関数か大幅なインターフェース変更が必要。",
+      "suggestion": "Phase 1 では fetch_snippet() の既存ロジックを利用し、セクション優先抽出は Phase 2 以降に分離する。"
+    },
+    {
+      "id": "S2",
+      "title": "before-change での tantivy IndexReader 追加が必要",
+      "description": "before_change.rs は SymbolStore と EmbeddingStore のみ使用。スニペット取得には IndexReaderWrapper が追加で必要。",
+      "suggestion": "run_before_change() の引数に IndexReaderWrapper を追加するか、commandindex_dir から遅延初期化する。findings数は少ないためパフォーマンス問題なし。"
+    },
+    {
+      "id": "S3",
+      "title": "issue コマンドの JSON 出力形式が breaking change",
+      "description": "format_json() は現在パスの配列を返す。スニペット追加で {path, snippet} オブジェクトに変更する必要があり、後方互換性が壊れる。",
+      "suggestion": "JSON出力形式の変更を明確に定義し、breaking change であることをIssueに明記する。"
+    },
+    {
+      "id": "S4",
+      "title": "snippet_helper パターンの一貫性",
+      "description": "既存コードでは enrich_*_with_snippets() パターンが確立されている。",
+      "suggestion": "snippet_helper.rs に enrich_issue_documents_with_snippets() と enrich_before_change_with_snippets() を追加。"
+    }
+  ],
+  "nice_to_have": [
+    {
+      "id": "N1",
+      "title": "スニペット文字数設定のハードコード回避",
+      "description": "Issueでは150-200文字だが、既存のSnippetConfigデフォルトはlines=2, chars=120。",
+      "suggestion": "issue/before-change用のデフォルトSnippetConfigを別途定義するか、CLIオプションを追加。"
+    },
+    {
+      "id": "N2",
+      "title": "tantivy未インデックスファイルのフォールバック",
+      "description": "dev-reports/ がインデックスされていない場合、スニペットが空になる。",
+      "suggestion": "取得できない場合は空文字列を返すことを受け入れ基準に含める。"
+    },
+    {
+      "id": "N3",
+      "title": "統合テストの網羅性",
+      "description": "スニペット付き出力の統合テストが必要。",
+      "suggestion": "テスト用tantivy インデックスを構築し、各フォーマットのスニペット出力を検証する統合テストを追加。"
+    }
+  ],
+  "summary": "Issue #168 はプロダクトコアに合致する重要な機能追加だが、(M1-M3) issue/before-change両コマンドで tantivy IndexReaderWrapper への新依存が必要なこと、(M4) テスト可能な受け入れ基準が未定義であることが主要課題。型変更の影響範囲（BeforeChangeFinding 5箇所、IssueDocumentEntry 8箇所）の明記、セクション優先抽出の段階的実装、JSON出力のbreaking change明示が必要。"
+}

dev-reports/issue/168/issue-review/stage2-apply-result.json

@@ -0,0 +1,16 @@
+{
+  "stage": 2,
+  "action": "apply_review",
+  "applied_items": [
+    "M1: issue コマンドの tantivy IndexReader 依存を実装方針に追加",
+    "M2: BeforeChangeFinding 型変更の影響範囲を明記",
+    "M3: IssueDocumentEntry 型変更の影響範囲を明記",
+    "M4: テスト可能な受け入れ基準を11項目追加",
+    "S1: セクション優先抽出をPhase 2（スコープ外）に分離",
+    "S2: before-change での IndexReader 追加方針を明記",
+    "S3: JSON出力のbreaking changeを明記",
+    "S4: snippet_helper パターンの一貫性（enrich関数追加）を明記"
+  ],
+  "issue_updated": true,
+  "url": "https://github.com/Kewton/CommandIndex/issues/168"
+}

dev-reports/issue/168/issue-review/stage3-review-context.json

@@ -0,0 +1,105 @@
+{
+  "must_fix": [
+    {
+      "id": "M1",
+      "title": "BeforeChangeFinding 全コンストラクタ更新（5箇所+テスト10箇所以上）",
+      "description": "snippet: Option<String> 追加で全コンストラクタがコンパイルエラーになる。",
+      "suggestion": "全コンストラクタで snippet: None を初期値設定。enrich 関数で後から上書き。"
+    },
+    {
+      "id": "M2",
+      "title": "IssueDocumentEntry 全コンストラクタ・テスト更新",
+      "description": "symbol_store.rs:909 の find_documents_by_issue() 内構造体生成、issue.rs テスト6箇所の更新が必要。",
+      "suggestion": "snippet: None を全箇所に追加。"
+    },
+    {
+      "id": "M3",
+      "title": "issue JSON出力 breaking change のテスト更新",
+      "description": "tests/e2e_issue.rs:94-99 のアサーションとユニットテストの全面更新が必要。",
+      "suggestion": "新スキーマ（オブジェクト配列）に合わせてテスト更新。"
+    },
+    {
+      "id": "M4",
+      "title": "before-change テスト内の構造体リテラル全更新",
+      "description": "before_change.rs テストモジュール内に10箇所以上のリテラルあり。",
+      "suggestion": "全リテラルに snippet: None を追加。"
+    },
+    {
+      "id": "M5",
+      "title": "run_before_change 関数に IndexReaderWrapper 追加",
+      "description": "main.rs:968-974 のコール箇所も更新必要。tantivy未存在時のフォールバック必要。",
+      "suggestion": "オプショナルパラメータとして追加、未存在時はスニペットなしでフォールバック。"
+    }
+  ],
+  "should_fix": [
+    {
+      "id": "S1",
+      "title": "issue コマンドに IndexReaderWrapper 導入",
+      "description": "commandindex_dir は既に受け取っているが tantivy 用 IndexReaderWrapper が未導入。",
+      "suggestion": "snippet_helper.rs に enrich_issue_documents_with_snippets() を追加。"
+    },
+    {
+      "id": "S2",
+      "title": "output フォーマッタ before-change スニペット表示対応（human/llm/json）",
+      "description": "3つのフォーマッタで snippet 表示ロジック追加が必要。",
+      "suggestion": "impact の実装パターンを参考に追加。"
+    },
+    {
+      "id": "S3",
+      "title": "output フォーマッタ issue スニペット表示対応（human/llm/json）",
+      "description": "4つの出力関数全てで snippet 表示対応が必要。format_json は大幅書き換え。",
+      "suggestion": "format_json をオブジェクト配列に変更。format_human/llm はインデント付き表示追加。"
+    },
+    {
+      "id": "S4",
+      "title": "snippet_helper.rs に enrich_before_change_with_snippets() 追加",
+      "description": "既存の enrich パターンに従い追加。",
+      "suggestion": "doc_path をキーに fetch_snippet() を呼ぶ。format=Path の場合はスキップ。"
+    },
+    {
+      "id": "S5",
+      "title": "tests/output_format.rs にスニペット出力テスト追加",
+      "description": "フォーマッタの単体テストにスニペット表示テストがない。",
+      "suggestion": "human/json/llm 各フォーマットのスニペット出力テストを追加。"
+    },
+    {
+      "id": "S6",
+      "title": "e2e テストの更新（e2e_before_change.rs, e2e_issue.rs）",
+      "description": "JSON出力テストで snippet フィールドの存在を検証すべき。",
+      "suggestion": "新スキーマに合わせてアサーション更新。"
+    }
+  ],
+  "nice_to_have": [
+    {
+      "id": "N1",
+      "title": "tantivy IndexReaderWrapper のオープンコスト: 問題なし",
+      "description": "コマンド実行ごとに1回のオープンで軽微。",
+      "suggestion": "tantivy 未存在時のフォールバック（snippet: None）は必須。"
+    },
+    {
+      "id": "N2",
+      "title": "fetch_snippet() 呼び出し回数: 最大20回程度で軽微",
+      "description": "TermQuery（完全一致）なので O(1) に近い。",
+      "suggestion": "enrich 関数は limit 適用後に呼ぶ設計を維持。"
+    },
+    {
+      "id": "N3",
+      "title": "help-llm 出力のスキーマ更新",
+      "description": "issue/before-change の出力フォーマット説明を更新。",
+      "suggestion": "snippet 関連の情報を help-llm に追加。"
+    },
+    {
+      "id": "N4",
+      "title": "--with-snippet フラグの追加検討",
+      "description": "他コマンド（impact/search）との一貫性のため検討。",
+      "suggestion": "issue/before-change にも --with-snippet を追加、デフォルトオフ。"
+    },
+    {
+      "id": "N5",
+      "title": "why コマンドへの波及: 今回スコープ外",
+      "description": "類似構造だが今回は変更不要。",
+      "suggestion": "将来のスニペット拡張時に同パターンを適用。"
+    }
+  ],
+  "summary": "変更の影響範囲: (1) BeforeChangeFinding/IssueDocumentEntry の型変更（構造体リテラル15箇所以上）、(2) snippet_helper.rs に enrich 関数2つ追加、(3) output フォーマッタ6関数更新、(4) main.rs の2コマンドハンドラ更新。issue JSON の breaking change が最大の影響。issue/before-change 以外への波及なし。パフォーマンス影響は軽微。"
+}

dev-reports/issue/168/issue-review/stage4-apply-result.json

@@ -0,0 +1,15 @@
+{
+  "stage": 4,
+  "action": "apply_review",
+  "applied_items": [
+    "M1-M5: 全コンストラクタ更新箇所の詳細を影響範囲テーブルに追加",
+    "S1: --with-snippet フラグ追加（他コマンドとの一貫性）",
+    "S2-S4: output フォーマッタ更新箇所を影響範囲テーブルに追加",
+    "S5-S6: テスト更新箇所を影響範囲テーブルに追加",
+    "N1: tantivy未存在時のフォールバックを受け入れ基準に追加",
+    "N3: help-llm 更新を実装方針に追加",
+    "N4: --with-snippet フラグを受け入れ基準に反映（デフォルトオフ→後方互換性維持）"
+  ],
+  "issue_updated": true,
+  "url": "https://github.com/Kewton/CommandIndex/issues/168"
+}