yoi/tickets/file-ref-directory.md

Submit 時 FileRef でディレクトリを参照したときの挙動

背景

submit 時に Segment::FileRef { path } は crates/pod/src/fs_view.rs の PodFsView::resolve_file_ref でファイル本文として読まれ、[File: <path>] system message に展開される。内部では ScopedFs::read_bytes を経由するため、path が ディレクトリだった場合は ToolsError::IsDirectory で失敗し、Pod 側は AlertLevel::Warn を出してそのセグメントを丸ごと捨てる （crates/pod/src/pod.rs の resolve_file_refs）。

ユーザーから見ると @some-dir を添付しても LLM 側にはプレースホルダが残る だけで、ディレクトリ参照という意図が反映されない。TUI completion は ディレクトリも候補として出すので、実際の挙動とのギャップが大きい。

tickets/file-ref-symlink-diagnostics.md は symlink が canonicalize 後に ディレクトリ・scope 外だった場合の診断にフォーカスしており、通常ディレクトリの FileRef 解決をどう扱うかは扱っていない。

ゴール

submit 時に Segment::FileRef がディレクトリを指している場合の挙動を 仕様として確定し、ユーザーが添付の意図どおりの結果を LLM に届けられる ようにする。

要件

ディレクトリに対する FileRef の意味論を決め、実装する。少なくとも以下の 論点をチケット内で結論づけ、実装・テスト・ドキュメントを揃える:

• 採用する挙動: 浅い entry listing を [Dir: <path>] 等の label で返すか、 明示的に reject して read_file / glob の利用を促すか、それ以外か
• listing を返す場合の上限: entry 件数や本文 byte 数を、ファイル本文用の upload/attachment 上限と同じにするか別途持つか
• 隠しファイル・gitignore・scope 外 entry の扱い
• symlink entry の扱いは tickets/file-ref-symlink-diagnostics.md と矛盾 しないこと（重複する判定は共通化を検討する）
• TUI completion がディレクトリ候補を出す挙動と整合すること（候補に出る 以上、submit 時に黙って捨てるのは UX として不整合）

完了条件

• 通常ディレクトリの FileRef が、IsDirectory Warn で黙って捨てられる 現状の挙動を残していない
• 採用した挙動が PodFsView のテストで覆われている
• Segment::FileRef のドキュメント / コメントが新仕様に揃っている
• TUI completion とのギャップが解消されている（ディレクトリを候補から 外すのか、submit でも扱うのか、いずれかに寄せる）

範囲外

• 再帰的なディレクトリ走査、glob 展開、tree 風の深い表現
• ディレクトリ内ファイルの自動 read 集約（auto-read / fs view 側の責務）
• symlink 経由のディレクトリ判定の刷新 （tickets/file-ref-symlink-diagnostics.md 側で扱う）
• upload / attachment 上限の manifest 化（tickets/manifest-output-upload-limits.md）

参照

• crates/pod/src/fs_view.rs resolve_file_ref / list_file_completions
• crates/pod/src/pod.rs resolve_file_refs
• crates/tools/src/scoped_fs.rs read_bytes
• tickets/file-ref-symlink-diagnostics.md
• tickets/manifest-output-upload-limits.md