feat!: Squad Naming System Phase (feature branch)

[shabaraba]

Summary

Feature branch for Squad Naming System Phase 1, preserved for future development.

This PR tracks the Squad implementation separately from main while development is paused.

Changes from main

This branch restores the full Squad Naming System Phase 1 implementation that was reverted in #315:

Core Features

• Squad Naming: Automatic NATO phonetic alphabet names (Alpha-Zulu)
• Role Detection: Commander vs Squad based on worktree path
• Squad Headers: Response headers with squad identification ("## Assistant ")
• Persistence: Squad names stored in chat frontmatter
• Registry: In-memory tracking of active squads
• Cleanup: Automatic cleanup on buffer close

MCP Tools

• nvim_get_squad_info(bufnr) - Get squad metadata
• nvim_list_squads() - List all active squads
• nvim_find_squad_buffer(squad_name) - Find squad by name

Squad Awareness

• Agent SDK includes squad_name in system prompt
• Claude recognizes its own squad identity
• Foundation for multi-agent coordination

Architecture

• Domain Layer: Value objects, entities, services
• Infrastructure Layer: Registry, persistence
• Presentation Layer: Headers, UI integration

Documentation

• docs/SQUAD_NAMING_GUIDE.md - Navigation guide
• docs/adr/003-squad-naming-system-phase1.md - Architecture decisions
• docs/features/squad-naming-system.md - Feature guide
• docs/specs/squad-naming-system.md - Technical specifications

Related Issues

Implemented:

• Closes feat: Auto-assign NATO phonetic alphabet names to chat buffers #305 - Auto-assign NATO phonetic alphabet names

Related (pending):

• Bug: Squad identity confusion - getCurrentSquadName uses wrong buffer context #313 - Squad identity confusion bug
• Bug: E484 file not found error in nvim_list_squads and nvim_reply_to_mention #312 - E484 file not found error
• Enhancement: Improve mention system UX and documentation #314 - Mention system UX improvements
• feat: Mention-based interruption in canUseTool hook #306 - Mention-based interruption feature

Related PRs:

• feat: implement Squad Naming System Phase 1 for multi-agent coordination #310 - Original implementation (merged, then reverted)
• revert: Squad Naming System Phase 1 #315 - Revert PR (merged)
• feat: Mention-based interruption in canUseTool hook #311 - Mention-based interruption (open)

Status

🚧 Draft PR - NOT for merging into main

This PR remains open to:

1. Track squad-related issues and enhancements
2. Preserve implementation for future reference
3. Serve as base branch when development resumes

Future Work

When Squad development resumes:

• Review and update implementation
• Consider thread-based design (see deleted docs/design/thread-based-squad-communication.md)
• Address open issues (Bug: Squad identity confusion - getCurrentSquadName uses wrong buffer context #313, Bug: E484 file not found error in nvim_list_squads and nvim_reply_to_mention #312, Enhancement: Improve mention system UX and documentation #314, feat: Mention-based interruption in canUseTool hook #306)
• Enhance inter-squad messaging

Refs

ref #293
ref #311

🤖 Generated with Claude Code

Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

PR #316 レビュー: Squad Naming System Phase 1

概要

Squad Naming Systemの実装は全体的に非常に高品質です。Domain-Driven Designの原則に従った3層アーキテクチャ、充実したドキュメント、そして後方互換性への配慮が素晴らしいです。

---

✅ 優れている点

1. アーキテクチャ設計

Clean Architectureの徹底

Domain Layer (ビジネスロジック)
  ↓
Infrastructure Layer (永続化)
  ↓
Presentation Layer (UI)

• ✅ 関心の分離が明確
• ✅ 各層の責務が適切に定義されている
• ✅ 依存関係の方向が一貫している（下向き）
• ✅ テスタビリティが高い

2. Value Objectパターンの適切な使用

squad_name.luaとsquad_role.lua:

• ✅ イミュータブルな設計
• ✅ バリデーションロジックがカプセル化されている
• ✅ ビジネスルールが型で表現されている
• ✅ NATO phonetic alphabetの完全性（26名）

3. ドキュメントの充実度

• ✅ ADR 003: 設計決定の詳細な記録
• ✅ Feature Guide: ユーザー向けドキュメント
• ✅ Specification: 技術仕様
• ✅ SQUAD_NAMING_GUIDE.md: 包括的なナビゲーションガイド

これはエンタープライズグレードのドキュメントです。

4. 後方互換性への配慮

-- レガシーチャットの自動アップグレード
if not frontmatter.squad_name then
  self:assign_squad_name()
end

• ✅ 既存チャットファイルが壊れない
• ✅ 段階的な移行が可能
• ✅ ユーザーの手動作業が不要

5. エラーハンドリング

Registry.luaの自動クリーンアップ:

if not vim.api.nvim_buf_is_valid(bufnr) then
  M._active_squads[name] = nil
  return true
end

• ✅ 無効なバッファの自動削除
• ✅ メモリリークの防止
• ✅ ステートの整合性維持

---

⚠️ 改善が必要な点

1. 🔴 CRITICAL: Role判定ロジックの脆弱性

squad_role.lua:31:

local is_worktree = cwd:match("/.worktrees/") ~= nil

問題:

• このパターンは/.worktrees/を含むあらゆるパスにマッチします
• 例: /home/user/.worktrees/backup/project → Squad判定されてしまう
• 例: /projects/my.worktrees/test → Squad判定されてしまう

推奨修正（シンプル版）:

-- vibing.nvimの慣例に従い、プロジェクトルート直下の.worktrees/を判定
local is_worktree = cwd:match("/%.worktrees/[^/]+/?") ~= nil

または、Gitコマンドを使った厳密な判定も検討可能です。

2. ⚠️ MEDIUM: Registryの並行性問題

**registry.lua**はグローバルステート(M._active_squads)を使用していますが、並行アクセスに対する保護がありません。

推奨修正: NamingServiceで使用時に再チェック:

function M.assign_squad_name(context, registry)
  local squad_name = M._find_available_name(registry)
  -- 登録前に再度チェック（TOCTOU回避）
  if not registry.is_available(squad_name) then
    squad_name = M._find_available_name(registry)
  end
  registry.register(squad_name, context.bufnr)
end

3. ⚠️ MEDIUM: エラーメッセージの国際化対応

vibing.nvimは多言語対応(language: ja)をサポートしていますが、ドメイン層のエラーメッセージは英語のみです。将来的に国際化の検討を推奨します。

4. ⚠️ LOW: テストカバレッジの不足

追加推奨テスト:

• 26個全て使い切った場合
• Role判定のエッジケース（シンボリックリンク、相対パスなど）
• 無効なバッファの自動クリーンアップ
• frontmatterのシリアライズ/デシリアライズのエッジケース

5. ⚠️ LOW: MCP Toolsのバリデーション不足

推奨: 引数の型バリデーションを追加

if (args?.bufnr \!== undefined && typeof args.bufnr \!== 'number') {
  throw new Error(`Invalid bufnr: expected number, got ${typeof args.bufnr}`);
}

---

🔍 セキュリティレビュー

✅ 問題なし

1. インジェクション攻撃: Squad名はNATOアルファベットに制限されており、ユーザー入力は検証済み
2. パストラバーサル: Frontmatterの読み書きは既存の安全な機構を使用
3. メモリリーク: 無効バッファの自動クリーンアップで対策済み

---

📊 パフォーマンス

✅ 良好

1. O(1) Registry操作: ハッシュテーブルベース
2. O(26) 名前検索: NATO_ALPHABET配列の線形探索（26要素のみなので問題なし）
3. 最小限のファイルI/O: Frontmatterへの書き込みのみ

---

🎯 総合評価

カテゴリ	評価	コメント
アーキテクチャ	⭐⭐⭐⭐⭐	Clean Architecture完璧
コード品質	⭐⭐⭐⭐☆	Role判定の脆弱性を除き優秀
ドキュメント	⭐⭐⭐⭐⭐	エンタープライズグレード
テスト	⭐⭐⭐☆☆	基本カバレッジあり、エッジケース不足
セキュリティ	⭐⭐⭐⭐☆	大きな問題なし
後方互換性	⭐⭐⭐⭐⭐	完璧に配慮されている

総合スコア: 92/100 🎉

---

✅ マージ推奨事項

このPRは高品質であり、以下の条件でマージを推奨します:

必須修正（マージ前）:

1. ✅ Role判定ロジックの修正（CRITICAL）
   • squad_role.lua:31のパターンマッチングを厳密化

推奨修正（マージ後でも可）:

2. ⚠️ Registry並行性の改善
3. ⚠️ エラーメッセージの国際化
4. ⚠️ テストカバレッジの拡充
5. ⚠️ MCP Toolsの型バリデーション

---

💬 最終コメント

このPRはvibing.nvimの品質基準を大きく向上させる素晴らしい実装です。

特に評価できる点:

• Domain-Driven Designの教科書的な実装
• 詳細なドキュメントとADR
• 将来の拡張性（Phase 2/3）への配慮
• 既存コードへの影響を最小限に抑えた設計

Squad Naming Systemは将来のマルチエージェント協調の基盤として、非常に価値のある機能です。

Critical issueの修正後、自信を持ってマージできます 🚀

---

Reviewed by: Claude Sonnet 4.5
Review Date: 2025-01-17