bv

BV - Beads Viewer

Beads プロジェクト（.beads/beads.jsonl）向けのグラフ対応トリアージエンジンです。9 つのグラフ指標を計算し、実行計画を生成して、決定論的な推奨事項を提示します。人間が閲覧するための TUI と、AI エージェント向けのロボット用フラグを備えています。

BV と生の Beads の比較

機能	生の beads.jsonl	BV ロボットモード
クエリ	「すべての課題を一覧表示」	「リリースを妨げている上位 5 つのボトルネックを一覧表示」
コンテキストコスト	高い（課題数に比例）	低い（固定のサマリー構造体）
グラフロジック	エージェントが計算する必要があります	事前計算済み（PageRank、媒介中心性、サイクル）
安全性	エージェントがサイクルを見落とす可能性があります	サイクルが明示的に示されます

beads.jsonl を直接解析する代わりに BV を使用してください。グラフ指標を決定論的に計算します。

重要：エージェント向けのロボットモード

bv をオプションなしで実行しないでください。対話型 TUI が起動し、セッションがブロックされます。

必ず --robot-* フラグを使用してください。

bv --robot-triage        # THE MEGA-COMMAND: start here
bv --robot-next          # Minimal: just the single top pick
bv --robot-plan          # Parallel execution tracks
bv --robot-insights      # Full graph metrics

9 つのグラフ指標

BV は、プロジェクトに隠れた動向を明らかにするため、次の指標を計算します。

指標	測定対象	主な洞察
PageRank	再帰的な依存関係の重要度	基盤となるブロッカー
媒介中心性	最短経路の通過量	ボトルネックと橋渡しとなるノード
HITS	ハブとオーソリティの二面性	エピックとユーティリティ
クリティカルパス	最長の依存関係チェーン	余裕時間がゼロの要所
固有ベクトル中心性	隣接ノードを介した影響力	戦略的な依存関係
次数	直接接続数	直接のブロッカー／ブロック対象
密度	エッジとノードの比率	プロジェクトの結合度の健全性
サイクル	循環依存関係	構造上のエラー（必ず修正してください！）
トポロジカルソート	有効な実行順序	作業キューの基盤

2 段階分析

BV はタイムアウトを設定した非同期計算を使用します。

• フェーズ 1（即時）： 次数、トポロジカルソート、密度
• フェーズ 2（500ms タイムアウト）： PageRank、媒介中心性、HITS、固有ベクトル中心性、サイクル

出力の status フィールドを必ず確認してください。大規模なグラフ（500 ノード超）では、一部の指標が approx または skipped になることがあります。

ロボットコマンドリファレンス

トリアージと計画

bv --robot-triage              # Full triage: recommendations, quick_wins, blockers_to_clear
bv --robot-next                # Single top pick with claim command
bv --robot-plan                # Parallel execution tracks with unblocks lists
bv --robot-priority            # Priority misalignment detection

グラフ分析

bv --robot-insights            # Full metrics: PageRank, betweenness, HITS, cycles, etc.
bv --robot-label-health        # Per-label health: healthy|warning|critical
bv --robot-label-flow          # Cross-label dependency flow matrix
bv --robot-label-attention     # Attention-ranked labels

履歴と変更

bv --robot-history             # Bead-to-commit correlations
bv --robot-diff --diff-since <ref>  # Changes since ref

その他のコマンド

bv --robot-burndown <sprint>   # Sprint burndown, scope changes
bv --robot-forecast <id|all>   # ETA predictions
bv --robot-alerts              # Stale issues, blocking cascades
bv --robot-suggest             # Hygiene: duplicates, missing deps, cycle breaks
bv --robot-graph               # Dependency graph export (JSON, DOT, Mermaid)
bv --export-graph <file.html>  # Self-contained interactive HTML visualization

スコープ指定とフィルタリング

bv --robot-plan --label backend              # Scope to label's subgraph
bv --robot-insights --as-of HEAD~30          # Historical point-in-time
bv --recipe actionable --robot-plan          # Pre-filter: ready to work
bv --recipe high-impact --robot-triage       # Pre-filter: top PageRank
bv --robot-triage --robot-triage-by-track    # Group by parallel work streams
bv --robot-triage --robot-triage-by-label    # Group by domain

組み込みレシピ

レシピ	目的
default	優先度順に並べた、すべての未完了課題
actionable	作業可能な課題（ブロッカーなし）
high-impact	PageRank スコア上位
blocked	依存関係の解消待ち
stale	未完了のまま 30 日以上更新されていない課題
triage	計算されたトリアージスコア順
quick-wins	ブロッカーのない、簡単な P2/P3 項目
bottlenecks	媒介中心性の高いノード

ロボット出力の構造

すべてのロボット JSON には次の項目が含まれます。

• data_hash - beads.jsonl のフィンガープリント（一貫性の確認用）
• status - 指標ごとの状態：computed|approx|timeout|skipped
• as_of / as_of_commit - --as-of を使用した場合に表示されます

--robot-triage の出力

{
  "quick_ref": { "open": 45, "blocked": 12, "top_picks": [...] },
  "recommendations": [
    { "id": "br-123", "score": 0.85, "reason": "Unblocks 5 tasks", "unblock_info": {...} }
  ],
  "quick_wins": [...],
  "blockers_to_clear": [...],
  "project_health": { "distributions": {...}, "graph_metrics": {...} },
  "commands": { "claim": "br claim br-123", "view": "bv --bead br-123" }
}

--robot-insights の出力

{
  "bottlenecks": [{ "id": "br-123", "value": 0.45 }],
  "keystones": [{ "id": "br-456", "value": 12.0 }],
  "influencers": [...],
  "hubs": [...],
  "authorities": [...],
  "cycles": [["br-A", "br-B", "br-A"]],
  "clusterDensity": 0.045,
  "status": { "pagerank": "computed", "betweenness": "computed", ... }
}

jq クイックリファレンス

bv --robot-triage | jq '.quick_ref'                        # At-a-glance summary
bv --robot-triage | jq '.recommendations[0]'               # Top recommendation
bv --robot-plan | jq '.plan.summary.highest_impact'        # Best unblock target
bv --robot-insights | jq '.status'                         # Check metric readiness
bv --robot-insights | jq '.cycles'                         # Circular deps (must fix!)
bv --robot-label-health | jq '.results.labels[] | select(.health_level == "critical")'

エージェントのワークフローパターン

# 1. Start with triage
TRIAGE=$(bv --robot-triage)
NEXT_TASK=$(echo "$TRIAGE" | jq -r '.recommendations[0].id')

# 2. Check for cycles first (structural errors)
CYCLES=$(bv --robot-insights | jq '.cycles')
if [ "$CYCLES" != "[]" ]; then
  echo "Fix cycles first: $CYCLES"
fi

# 3. Claim the task
br claim "$NEXT_TASK"

# 4. Work on it...

# 5. Close when done
br close "$NEXT_TASK"

TUI ビュー（人間向け）

bv を対話形式で実行する場合（エージェント向けではありません）：

キー	ビュー
l	リストビュー（デフォルト）
b	カンバンボード
g	グラフビュー（依存関係 DAG）
E	ツリービュー（親子階層）
i	インサイトダッシュボード（6 パネルの指標）
h	履歴ビュー（Bead とコミットの相関）
a	実行可能な計画（並列トラック）
f	フローマトリクス（ラベルをまたぐ依存関係）
]	注意ビュー（ラベルの優先度ランキング）

br CLI との統合

BV は、br CLI によって作成された .beads/beads.jsonl を読み取ります。

br init                    # Initialize beads in project
br create "Task title"     # Create a bead
br list                    # List beads
br ready                   # Show actionable beads
br claim br-123            # Claim a bead
br close br-123            # Close a bead

Agent Mail との統合

連携には Bead ID をスレッド ID として使用します。

file_reservation_paths(..., reason="br-123")
send_message(..., thread_id="br-123", subject="[br-123] Starting...")

グラフのエクスポート形式

bv --robot-graph                              # JSON (default)
bv --robot-graph --graph-format=dot           # Graphviz DOT
bv --robot-graph --graph-format=mermaid       # Mermaid diagram
bv --robot-graph --graph-root=br-123 --graph-depth=3  # Subgraph
bv --export-graph report.html                 # Interactive HTML

タイムトラベル

過去の状態と比較します。

bv --as-of HEAD~10                    # 10 commits ago
bv --as-of v1.0.0                     # At tag
bv --as-of "2024-01-15"               # At date
bv --robot-diff --diff-since HEAD~30  # Changes in last 30 commits

よくある落とし穴

問題	解決方法
TUI がエージェントをブロックする	--robot-* フラグのみを使用します
メトリクスが古い	status フィールドを確認します。結果は data_hash によってキャッシュされます
サイクルが見つからない	--robot-insights を実行し、.cycles を確認します
推奨事項が適切でない	--recipe actionable を使用して、すぐに着手できる作業に絞り込みます

パフォーマンスに関する注意事項

• フェーズ 1 のメトリクス（degree、topo、density）：即時
• フェーズ 2 のメトリクス（PageRank、betweenness など）：タイムアウトは 500ms
• 結果は data_hash によってキャッシュされます
• 速度を重視する場合は、--robot-insights より --robot-plan を優先してください