📦 deps(thirdparty): update snapshots

2026-05-29 08:33:53 +00:00
parent fdb52f1e96
commit 06e0d13d57
1615 changed files with 232858 additions and 0 deletions
@@ -0,0 +1,339 @@
+# Beads Integration
+
+Local issue tracking with dependency awareness. Complements remote platforms (GitHub, Linear) with project-scoped work items stored in `.beads/`.
+
+## Overview
+
+Beads provides:
+- Local-first issue tracking (no remote dependency)
+- Dependency graphs between issues
+- Status workflow (open → in_progress → blocked → closed)
+- Priority levels and type classification
+- Assignee tracking for team awareness
+
+**Key difference from Linear/GitHub**: Beads tracks work items at the project level, not org-wide. Data lives in `.beads/` directory.
+
+## Core Commands for Status Reporting
+
+### Stats Overview
+
+```bash
+bd stats
+```
+
+Returns project-level metrics:
+- Total issues, open/closed counts
+- In-progress and blocked counts
+- Ready items (unblocked, actionable)
+- Average lead time
+
+**Use for**: Top-level summary section, health indicators.
+
+### List Issues
+
+```bash
+bd list                           # All issues (default limit: 20)
+bd list --status=open             # Filter by status
+bd list --status=in_progress      # Active work
+bd list --status=blocked          # Stuck items
+bd list --priority=1              # Urgent only (1=urgent, 4=low)
+bd list --type=bug                # Filter by type
+bd list --assignee=alice          # Filter by assignee
+bd list --limit=10                # Pagination
+```
+
+**Statuses**: `open`, `in_progress`, `blocked`, `closed`
+**Types**: `bug`, `feature`, `task`, `epic`, `chore`
+**Priority**: 1 (urgent) → 4 (low), 0 (none)
+
+**Use for**: Recent activity, filtered views, assignee workload.
+
+### Ready Items
+
+```bash
+bd ready                          # Unblocked items ready for work
+bd ready --limit=5                # Top 5 actionable
+bd ready --priority=1             # Urgent and ready
+bd ready --assignee=alice         # Ready for specific person
+```
+
+Returns issues with zero blocking dependencies.
+
+**Use for**: "What to work on next" section, actionable items.
+
+### Blocked Items
+
+```bash
+bd blocked
+```
+
+Returns issues in blocked status with their blocking dependencies.
+
+**Use for**: Dependency visibility, bottleneck identification.
+
+### Issue Details
+
+```bash
+bd show <issue-id>                # Full details with dependencies
+```
+
+Returns:
+- Full description, design notes, acceptance criteria
+- Blocking/blocked-by relationships
+- Activity history
+
+**Use for**: Deep dive on specific blocked items.
+
+## Data Schema
+
+```typescript
+interface BeadsIssue {
+  id: string;                     // e.g., "AG-1", "BLZ-42"
+  title: string;
+  description?: string;
+  status: 'open' | 'in_progress' | 'blocked' | 'closed';
+  issue_type: 'bug' | 'feature' | 'task' | 'epic' | 'chore';
+  priority: 0 | 1 | 2 | 3 | 4;    // 1=urgent, 4=low, 0=unset
+  assignee?: string;
+  labels: string[];
+  created_at: string;             // ISO 8601
+  updated_at: string;             // ISO 8601
+  closed_at?: string;
+  dependency_count: number;       // Issues blocking this
+  dependent_count: number;        // Issues this blocks
+}
+
+interface BeadsStats {
+  total: number;
+  open: number;
+  in_progress: number;
+  blocked: number;
+  closed: number;
+  ready: number;                  // Unblocked and actionable
+  average_lead_time?: number;     // Days from open to close
+}
+```
+
+## Time Filtering
+
+Beads lacks native time-based filtering. Apply client-side filtering on `updated_at`:
+
+```typescript
+// Filter to issues updated within time range
+function filterByTime(issues: BeadsIssue[], hoursBack: number): BeadsIssue[] {
+  const cutoff = new Date();
+  cutoff.setHours(cutoff.getHours() - hoursBack);
+
+  return issues.filter(issue =>
+    new Date(issue.updated_at) >= cutoff
+  );
+}
+
+// Example: last 24 hours
+const recentIssues = filterByTime(allIssues, 24);
+```
+
+**Recommendation**: Fetch with higher limit, filter client-side, then present top N.
+
+## Gathering Pattern
+
+```typescript
+async function gatherBeadsData(timeHours: number = 24) {
+  // 1. Get overview stats
+  const stats = await bd.stats();
+
+  // 2. Get in-progress work
+  const inProgress = await bd.list({
+    status: 'in_progress',
+    limit: 10
+  });
+
+  // 3. Get ready items (actionable)
+  const ready = await bd.ready({ limit: 5 });
+
+  // 4. Get blocked items with dependencies
+  const blocked = await bd.blocked();
+
+  // 5. Get recently closed (for velocity)
+  const closed = await bd.list({
+    status: 'closed',
+    limit: 10
+  });
+  const recentlyClosed = filterByTime(closed, timeHours);
+
+  return { stats, inProgress, ready, blocked, recentlyClosed };
+}
+```
+
+## Presentation Template
+
+```
+📋 BEADS ISSUES
+{stats.total} total | {stats.open} open | {stats.in_progress} active | {stats.blocked} blocked
+
+Ready to Work:
+  {id}: {title} [{type}, {priority_label}]
+  ...
+
+In Progress:
+  {id}: {title}
+    Status: {status} | Updated: {relative_time} | Assignee: {assignee}
+  ...
+
+Blocked ({blocked.length}):
+  {id}: {title}
+    ⛔ Blocked by: {blocking_ids}
+  ...
+
+Recently Closed ({recentlyClosed.length}):
+  ✓ {id}: {title} — closed {relative_time}
+  ...
+```
+
+### Priority Labels
+
+| Priority | Label | Indicator |
+|----------|-------|-----------|
+| 1 | urgent | 🔴 |
+| 2 | high | 🟠 |
+| 3 | normal | 🟡 |
+| 4 | low | ⚪ |
+| 0 | unset | — |
+
+### Status Indicators
+
+| Status | Indicator |
+|--------|-----------|
+| open | ◯ |
+| in_progress | ◐ |
+| blocked | ⛔ |
+| closed | ✓ |
+
+## Cross-Referencing
+
+### With GitHub PRs
+
+Match beads issue IDs in PR titles/branches:
+- PR title: "AG-123: Implement feature" → links to beads AG-123
+- Branch: `ag-123-feature` → links to beads AG-123
+
+```typescript
+function linkPRToBeads(prTitle: string, beadsIssues: BeadsIssue[]) {
+  const match = prTitle.match(/^([A-Z]+-\d+):/);
+  if (match) {
+    return beadsIssues.find(i => i.id === match[1]);
+  }
+  return null;
+}
+```
+
+### With Linear Issues
+
+Beads `external_ref` field can store Linear issue URL:
+
+```bash
+bd update AG-123 --external-ref="https://linear.app/team/issue/TEAM-456"
+```
+
+Query: Check `external_ref` for Linear correlation.
+
+### With Graphite Stacks
+
+Match branch names to beads issues:
+- Branch: `ag-123-feature` → beads issue AG-123
+- Stack contains multiple branches → multiple linked issues
+
+## Context Detection
+
+Beads requires workspace context. Detect via:
+
+```bash
+# Check if beads initialized
+ls .beads/issues.db 2>/dev/null && echo "beads available"
+
+# Or via MCP
+bd where-am-i
+```
+
+**Auto-detection**: Include beads in sitrep when `.beads/` directory exists in project root.
+
+## MCP Tools Reference
+
+When using beads via MCP server:
+
+| Tool | Purpose |
+|------|---------|
+| `beads__stats` | Project metrics overview |
+| `beads__list` | Query issues with filters |
+| `beads__ready` | Unblocked, actionable items |
+| `beads__blocked` | Blocked items with dependencies |
+| `beads__show` | Single issue details |
+
+**Context**: Call `beads__set_context` with workspace root before other operations.
+
+## Error Handling
+
+```typescript
+// Handle uninitialized beads
+try {
+  const stats = await bd.stats();
+} catch (e) {
+  if (e.message.includes('not initialized')) {
+    // Skip beads section, note in output
+    return { available: false, reason: 'Beads not initialized' };
+  }
+  throw e;
+}
+```
+
+**Common errors**:
+- "Beads not initialized" → `.beads/` doesn't exist
+- "No context set" → call `set_context` first
+- "Issue not found" → invalid issue ID
+
+## Best Practices
+
+1. **Prioritize Ready Items**: Show unblocked work prominently — these are actionable now
+
+2. **Highlight Blockers**: Blocked items with their dependencies help identify bottlenecks
+
+3. **Time-Filter Thoughtfully**: Since filtering is client-side, fetch reasonable limits (20-50) then filter
+
+4. **Cross-Reference PRs**: Link beads issues to PRs/branches when ID patterns match
+
+5. **Show Velocity**: Recently closed items indicate progress, especially useful for standups
+
+6. **Respect Priority**: Sort by priority within each section (urgent first)
+
+7. **Assignee Context**: When user has assignee, highlight their work specifically
+
+## Integration Points
+
+| Source | Correlation | Use Case |
+|--------|-------------|----------|
+| GitHub PRs | Issue ID in title/branch | Link PRs to tracked work |
+| Graphite stacks | Branch naming | Show stack progress per issue |
+| Linear | external_ref field | Bridge local ↔ team tracking |
+
+## Troubleshooting
+
+**"Beads not initialized"**
+
+```bash
+bd init                           # Initialize in project root
+bd init --prefix=PROJ             # Custom prefix (e.g., PROJ-1)
+```
+
+**"No issues found"**
+- Check workspace context: `bd where-am-i`
+- Verify `.beads/` exists in expected location
+
+**"Wrong project context"**
+
+```bash
+bd set-context /path/to/project   # Set correct workspace
+```
+
+**Stale data**
+- Beads data is local — always fresh
+- No caching concerns unlike remote APIs