claude-code-swarm 0.0.1 → 0.3.3

package/references/opentasks/docs/PROVIDERS.md

@@ -0,0 +1,1412 @@
+# OpenTasks Providers
+
+This document defines the provider architecture for OpenTasks.
+
+See also:
+- [DESIGN.md](./DESIGN.md) — Design rationale and core concepts
+- [SCHEMA.md](./SCHEMA.md) — Data model and types
+- [PERSISTENCE.md](./PERSISTENCE.md) — Storage and sync
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — Location hierarchy and daemon
+- [INTERFACE.md](./INTERFACE.md) — API
+
+---
+
+## Overview
+
+OpenTasks uses a **federated graph model** where:
+
+- **OpenTasks owns the graph structure** — edges, relationships, and node references
+- **Providers own node content** — the actual context and task data
+- **Daemon coordinates access** — all provider operations go through the location daemon
+- **Location isolation** — each `.opentasks/` location has its own provider configuration
+
+This separation allows OpenTasks to integrate with existing tools (Beads, Taskmaster, Linear) without duplicating data or creating sync conflicts.
+
+### Integration Patterns
+
+OpenTasks supports multiple integration patterns depending on the external system:
+
+| Pattern | Direction | Use Case | Example |
+|---------|-----------|----------|---------|
+| **Provider** | Read-heavy | External system is source of truth | Beads, Jira (read-only) |
+| **Adapter** | Bidirectional | Full sync between systems | Linear ↔ OpenTasks |
+| **SyncTarget** | Write-heavy | OpenTasks is source of truth | Export to GitHub Issues |
+
+The Provider interface (described below) is the foundation. Adapters and SyncTargets extend it with additional capabilities.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│               OpenTasks Location (graph.jsonl)                   │
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────────┐ │
+│  │                    Native Nodes                             │ │
+│  │  Context (c-a2b3)    Task (t-x7k9)    Feedback (f-m4n5)      │ │
+│  └────────────────────────────────────────────────────────────┘ │
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────────┐ │
+│  │                  ExternalNodes (cached)                     │ │
+│  │  e-bd1: beads://./bd-123     (materialized)                │ │
+│  │  e-tm1: taskmaster://./prd-1 (materialized)                │ │
+│  │  e-jir: jira://PROJ-456      (phantom, not yet fetched)    │ │
+│  └────────────────────────────────────────────────────────────┘ │
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────────┐ │
+│  │                        Edges                                │ │
+│  │  t-x7k9 ──implements──▶ c-a2b3                             │ │
+│  │  t-x7k9 ──blocks──▶ beads://./bd-456                       │ │
+│  │  e-bd1 ──discovered-from──▶ e-tm1                          │ │
+│  └────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                        Daemon (IPC)
+                              │
+            ┌─────────────────┼─────────────────┐
+            ▼                 ▼                 ▼
+┌───────────────────┐ ┌───────────────┐ ┌───────────────────┐
+│  Task Providers  │ │ Context Providers│ │  Other Locations  │
+│                   │ │               │ │                   │
+│  • Beads CLI      │ │ • Taskmaster  │ │  opentasks://~    │
+│  • Linear API     │ │ • spec-kit    │ │  opentasks://../  │
+│  • Jira API       │ │               │ │                   │
+└───────────────────┘ └───────────────┘ └───────────────────┘
+```
+
+---
+
+## Design Principles
+
+### 1. Separation of Concerns
+
+| Component | Owner | Storage |
+|-----------|-------|---------|
+| **Graph Structure** | OpenTasks | `.opentasks/graph.jsonl` |
+| ↳ Edges/Relationships | OpenTasks | (in graph.jsonl) |
+| ↳ Native Nodes | OpenTasks | (in graph.jsonl) |
+| ↳ ExternalNodes (cache) | OpenTasks | (in graph.jsonl) |
+| ↳ Feedback | OpenTasks | (in graph.jsonl) |
+| **External Task Content** | Task Provider | Provider's storage |
+| **External Context Content** | Context Provider | Provider's storage |
+
+See [PERSISTENCE.md](./PERSISTENCE.md) for details on the unified graph storage.
+
+### 2. Provider Authority
+
+Providers are the **source of truth** for their content. OpenTasks:
+
+- **Reads** content from providers on demand
+- **Caches** metadata for display (title, status)
+- **Never duplicates** full content
+- **Delegates** CRUD operations to providers
+
+### 3. URI-Based References
+
+OpenTasks uses two URI schemes:
+
+**Provider URIs** — References to external system content:
+```
+beads://[workspace]/[id]        # Beads issue
+taskmaster://[project]/[id]     # Taskmaster PRD/task
+linear://[team]/[id]            # Linear issue
+jira://[project]/[key]          # Jira issue
+github://[owner]/[repo]/[num]   # GitHub issue
+```
+
+**OpenTasks URIs** — Cross-location references (see [ARCHITECTURE.md](./ARCHITECTURE.md)):
+```
+opentasks://~/.opentasks/c-a2b3              # User location
+opentasks://./t-x7k9                         # Current location
+opentasks://../.opentasks/c-c4d5             # Parent directory
+opentasks:///abs/path/.opentasks/t-e6f7      # Absolute path
+```
+
+**URI Resolution Priority:**
+1. Local ID lookup (if no scheme prefix, e.g., `c-a2b3`)
+2. OpenTasks URI resolution (for `opentasks://` scheme)
+3. Provider URI resolution (for provider schemes like `beads://`, `jira://`)
+
+### 4. Graceful Degradation & Phantom Nodes
+
+OpenTasks supports **progressive materialization** for external references:
+
+```
+URI Reference → Phantom Node → Materialized Node
+     │                │                │
+     │                │                └── Full data fetched, cached
+     │                └── ExternalNode exists, materialized=false
+     └── Just a string in an edge target
+```
+
+**Degradation chain:**
+1. **Provider available**: Fetch fresh data, cache it
+2. **Provider unavailable**: Use cached data (with `stale: true`)
+3. **No cache**: Return phantom node (just URI and type)
+4. **No ExternalNode**: Edge still valid, target resolves to URI string
+
+This aligns with the `ExternalNode` type in [SCHEMA.md](./SCHEMA.md):
+```typescript
+interface ExternalNode {
+  type: 'external'
+  uri: string                    // Canonical URI (e.g., "jira://PROJ-123")
+  source: string                 // Provider name
+  materialized: boolean          // Has data been fetched?
+  cached_at?: string             // When last fetched
+  stale?: boolean                // Needs refresh
+  external_data?: Record<string, unknown>
+}
+```
+
+---
+
+## Provider Interface
+
+### Base Provider
+
+```typescript
+/**
+ * Base interface for all content providers
+ */
+interface ContentProvider {
+  /** Unique provider identifier */
+  readonly name: string
+
+  /** URI scheme(s) this provider handles */
+  readonly schemes: string[]
+
+  /** Node types this provider manages */
+  readonly nodeTypes: ('context' | 'task')[]
+
+  /** Provider capabilities */
+  readonly capabilities: ProviderCapabilities
+
+  // === Lifecycle ===
+
+  /** Initialize provider (called once on startup) */
+  initialize?(config: ProviderConfig): Promise<void>
+
+  /** Check if provider is available/healthy */
+  healthCheck?(): Promise<HealthStatus>
+
+  // === Read Operations ===
+
+  /** Get a single node by ID */
+  get(id: string): Promise<ProviderNode | null>
+
+  /** List nodes with optional filtering */
+  list(filter?: ProviderFilter): Promise<ProviderNode[]>
+
+  /** Search nodes by query string */
+  search?(query: string): Promise<ProviderNode[]>
+
+  /** Get nodes ready for work (no blockers) */
+  ready?(): Promise<ProviderNode[]>
+
+  // === Write Operations (optional) ===
+
+  /** Create a new node */
+  create?(input: CreateNodeInput): Promise<ProviderNode>
+
+  /** Update an existing node */
+  update?(id: string, updates: UpdateNodeInput): Promise<ProviderNode>
+
+  /** Close/complete a node */
+  close?(id: string, reason?: string): Promise<ProviderNode>
+
+  /** Delete a node */
+  delete?(id: string): Promise<void>
+
+  // === Sync Operations (optional) ===
+
+  /** Watch for changes (real-time updates) */
+  watch?(callback: (event: ProviderEvent) => void): Unsubscribe
+
+  /** Pull changes since last sync */
+  pullChanges?(since?: string): Promise<ChangeSet>
+
+  // === Mapping ===
+
+  /** Convert provider-native format to OpenTasks node */
+  toOpenTasks(native: unknown): ProviderNode
+
+  /** Convert OpenTasks node to provider-native format */
+  fromOpenTasks(node: ProviderNode): unknown
+}
+
+interface ProviderCapabilities {
+  read: boolean
+  write: boolean
+  delete: boolean
+  search: boolean
+  watch: boolean
+  ready: boolean  // supports "ready" query
+}
+
+interface ProviderNode {
+  /** Provider-specific ID */
+  id: string
+
+  /** Full URI for this node */
+  uri: string
+
+  /** Node type */
+  type: 'context' | 'task'
+
+  /** Display title */
+  title: string
+
+  /** Full content (markdown) */
+  content?: string
+
+  /** Provider's status value */
+  status?: string
+
+  /** Priority (0-4) */
+  priority?: number
+
+  /** Tags/labels */
+  tags?: string[]
+
+  /** Assignment */
+  assignee?: string
+
+  /** Timestamps */
+  created_at: string
+  updated_at: string
+
+  /** Provider-specific data */
+  provider_data?: Record<string, unknown>
+}
+
+interface ProviderEvent {
+  type: 'created' | 'updated' | 'deleted'
+  uri: string
+  node?: ProviderNode
+  timestamp: string
+}
+
+type Unsubscribe = () => void
+```
+
+---
+
+## Daemon Integration
+
+All provider operations are coordinated through the location daemon. This ensures:
+- Consistent caching across clients
+- Proper lock management
+- Event propagation to watchers
+- Cross-location resolution
+
+### Provider Registration Flow
+
+```
+┌───────────────────────────────────────────────────────────────────┐
+│                      Daemon Startup                                │
+│                                                                    │
+│  1. Read .opentasks/config.json for provider config               │
+│  2. Initialize configured providers                                │
+│  3. Register providers in ProviderRegistry                        │
+│  4. Start watchers for providers with watch capability            │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+### Request Flow
+
+```typescript
+// Client makes request
+const node = await client.get('beads://./bd-x7k9')
+
+// Daemon handles:
+// 1. Parse URI to determine provider
+// 2. Check ExternalNode cache
+// 3. If stale or missing, delegate to provider
+// 4. Update ExternalNode with fetched data
+// 5. Return to client
+```
+
+### IPC Methods for Providers
+
+The daemon exposes these provider-related IPC methods:
+
+| Method | Description |
+|--------|-------------|
+| `provider.resolve` | Resolve URI to node (with caching) |
+| `provider.list` | List nodes from a provider |
+| `provider.search` | Search across providers |
+| `provider.ready` | Get ready items (with cross-provider blocking) |
+| `provider.create` | Create via provider (if writable) |
+| `provider.update` | Update via provider (if writable) |
+| `provider.refresh` | Force refresh from provider |
+
+### Cross-Location Provider Resolution
+
+When an edge references a node in another location:
+
+```typescript
+// Edge in ~/projects/app-a/.opentasks/
+{
+  from_id: "t-local",
+  to_id: "opentasks://~/projects/app-b/.opentasks/t-x7k9",
+  type: "blocks"
+}
+
+// Resolution:
+// 1. Parse opentasks:// URI
+// 2. Find daemon for ~/projects/app-b/.opentasks/
+// 3. Request node from that daemon
+// 4. That daemon may further resolve to a provider URI
+```
+
+This enables multi-hop resolution:
+```
+opentasks://location-b/e-ext1 → beads://./bd-123 → Beads CLI
+```
+
+---
+
+## Task Providers
+
+### Beads Provider
+
+[Beads](https://github.com/steveyegge/beads) is a distributed, git-backed issue tracker designed for AI agents.
+
+```typescript
+interface BeadsProvider extends ContentProvider {
+  name: 'beads'
+  schemes: ['beads']
+  nodeTypes: ['task']
+
+  capabilities: {
+    read: true,
+    write: true,
+    delete: true,
+    search: true,
+    watch: true,    // via file watcher on .beads/issues.jsonl
+    ready: true     // `bd ready` command
+  }
+}
+```
+
+#### URI Format
+
+```
+beads://[workspace]/[id]
+
+Examples:
+  beads://./bd-x7k9           # Current workspace
+  beads:///path/to/repo/bd-y8  # Absolute path
+  beads://bd-z9a1             # Implicit current workspace
+```
+
+#### Field Mapping
+
+| Beads Field | OpenTasks Field | Notes |
+|-------------|-----------------|-------|
+| `id` | `id` | Hash-based (bd-xxxx) |
+| `title` | `title` | Direct mapping |
+| `description` | `content` | Primary content |
+| `design`, `acceptance_criteria`, `notes` | `content` | Concatenated with separators |
+| `status` | `status` | open, in_progress, blocked, closed, etc. |
+| `priority` | `priority` | 0-4 (same semantics) |
+| `labels` | `tags` | Direct mapping |
+| `assignee` | `assignee` | Direct mapping |
+| `dependencies` | Edges | Converted to OpenTasks edges |
+| `comments` | Feedback nodes | Each comment becomes feedback |
+
+#### Dependency Mapping
+
+Beads dependencies map to OpenTasks edges:
+
+| Beads Dependency | OpenTasks Edge | Direction |
+|------------------|----------------|-----------|
+| `blocks` | `blocks` | from → to |
+| `parent-child` | `parent-of` | parent → child |
+| `related` | `related` | bidirectional |
+| `discovered-from` | `discovered-from` | from → to |
+
+#### Implementation
+
+```typescript
+class BeadsProvider implements ContentProvider {
+  private workspace: string
+
+  constructor(config: { workspace?: string }) {
+    this.workspace = config.workspace || process.cwd()
+  }
+
+  async get(id: string): Promise<ProviderNode | null> {
+    // Use `bd show <id> --json` or read directly from .beads/
+    const result = await exec(`bd show ${id} --json`, {
+      cwd: this.workspace
+    })
+    if (!result) return null
+    return this.toOpenTasks(JSON.parse(result))
+  }
+
+  async list(filter?: ProviderFilter): Promise<ProviderNode[]> {
+    // Use `bd list --json` with filters
+    const args = this.buildListArgs(filter)
+    const result = await exec(`bd list ${args} --json`, {
+      cwd: this.workspace
+    })
+    return JSON.parse(result).map(this.toOpenTasks)
+  }
+
+  async ready(): Promise<ProviderNode[]> {
+    // Use `bd ready --json`
+    const result = await exec('bd ready --json', {
+      cwd: this.workspace
+    })
+    return JSON.parse(result).map(this.toOpenTasks)
+  }
+
+  async create(input: CreateNodeInput): Promise<ProviderNode> {
+    // Use `bd new`
+    const result = await exec(
+      `bd new -t "${input.title}" -d "${input.content || ''}"`,
+      { cwd: this.workspace }
+    )
+    const id = this.parseCreatedId(result)
+    return this.get(id)
+  }
+
+  async update(id: string, updates: UpdateNodeInput): Promise<ProviderNode> {
+    // Use `bd update`
+    const args = this.buildUpdateArgs(updates)
+    await exec(`bd update ${id} ${args}`, { cwd: this.workspace })
+    return this.get(id)
+  }
+
+  watch(callback: (event: ProviderEvent) => void): Unsubscribe {
+    // Watch .beads/issues.jsonl for changes
+    const watcher = fs.watch(
+      path.join(this.workspace, '.beads', 'issues.jsonl'),
+      () => callback({ type: 'updated', uri: 'beads://*', timestamp: new Date().toISOString() })
+    )
+    return () => watcher.close()
+  }
+
+  toOpenTasks(bead: BeadsIssue): ProviderNode {
+    // Concatenate content fields
+    const contentParts = [
+      bead.description,
+      bead.design && `## Design\n\n${bead.design}`,
+      bead.acceptance_criteria && `## Acceptance Criteria\n\n${bead.acceptance_criteria}`,
+      bead.notes && `## Notes\n\n${bead.notes}`,
+    ].filter(Boolean)
+
+    return {
+      id: bead.id,
+      uri: `beads://${this.workspace}/${bead.id}`,
+      type: 'task',
+      title: bead.title,
+      content: contentParts.join('\n\n---\n\n'),
+      status: this.mapStatus(bead.status),
+      priority: bead.priority,
+      tags: bead.labels,
+      assignee: bead.assignee,
+      created_at: bead.created_at,
+      updated_at: bead.updated_at,
+      provider_data: {
+        issue_type: bead.issue_type,
+        estimated_minutes: bead.estimated_minutes,
+        dependencies: bead.dependencies,
+      }
+    }
+  }
+
+  private mapStatus(beadsStatus: string): string {
+    // Beads has more statuses; map to OpenTasks core set
+    const mapping: Record<string, string> = {
+      'open': 'open',
+      'in_progress': 'in_progress',
+      'blocked': 'blocked',
+      'deferred': 'blocked',
+      'closed': 'closed',
+      'tombstone': 'closed',
+      'pinned': 'open',
+      'hooked': 'blocked',
+    }
+    return mapping[beadsStatus] || beadsStatus
+  }
+}
+```
+
+#### Configuration
+
+```json
+// .opentasks/config.json
+{
+  "providers": {
+    "issues": {
+      "primary": "beads",
+      "beads": {
+        "workspace": ".",
+        "cli": "bd"
+      }
+    }
+  }
+}
+```
+
+---
+
+### Linear Provider
+
+[Linear](https://linear.app) is a project management tool with a GraphQL API.
+
+```typescript
+interface LinearProvider extends ContentProvider {
+  name: 'linear'
+  schemes: ['linear']
+  nodeTypes: ['task']
+
+  capabilities: {
+    read: true,
+    write: true,
+    delete: false,   // Linear doesn't support hard delete
+    search: true,
+    watch: true,     // via webhooks
+    ready: false     // no native "ready" concept
+  }
+}
+```
+
+#### URI Format
+
+```
+linear://[team]/[id]
+
+Examples:
+  linear://ENG/ENG-123
+  linear://PROD/PROD-456
+```
+
+#### Field Mapping
+
+| Linear Field | OpenTasks Field |
+|--------------|-----------------|
+| `id` | `id` |
+| `identifier` | URI path (`ENG-123`) |
+| `title` | `title` |
+| `description` | `content` |
+| `state.name` | `status` |
+| `priority` | `priority` (mapped 0-4) |
+| `labels` | `tags` |
+| `assignee.name` | `assignee` |
+
+---
+
+### Native Task Provider
+
+Fallback provider when no external task tracker is configured. Unlike external providers, native nodes are stored directly in `graph.jsonl` as `Task` type (not `ExternalNode`).
+
+```typescript
+interface NativeTaskProvider extends ContentProvider {
+  name: 'native'
+  schemes: ['native', 'opentasks']
+  nodeTypes: ['task']
+
+  capabilities: {
+    read: true,
+    write: true,
+    delete: true,
+    search: true,
+    watch: true,    // file watcher on graph.jsonl
+    ready: true     // computed from edges
+  }
+}
+```
+
+**Storage**: Native tasks use the `Task` type directly in `graph.jsonl`:
+```json
+{
+  "id": "t-x7k9",
+  "type": "task",
+  "title": "Implement feature",
+  "status": "open",
+  ...
+}
+```
+
+This is different from external providers, which create `ExternalNode` wrappers.
+
+---
+
+## Context Providers
+
+### Taskmaster Provider
+
+[Taskmaster](https://github.com/eyaltoledano/claude-task-master) manages PRDs and breaks them into subtasks.
+
+```typescript
+interface TaskmasterProvider extends ContentProvider {
+  name: 'taskmaster'
+  schemes: ['taskmaster', 'tm']
+  nodeTypes: ['context']
+
+  capabilities: {
+    read: true,
+    write: true,
+    delete: true,
+    search: true,
+    watch: true,    // file watcher on tasks/
+    ready: false
+  }
+}
+```
+
+#### URI Format
+
+```
+taskmaster://[project]/[id]
+
+Examples:
+  taskmaster://./prd            # Root PRD
+  taskmaster://./task-1         # Subtask
+  tm://task-1                   # Short form
+```
+
+#### Field Mapping
+
+| Taskmaster Field | OpenTasks Field |
+|------------------|-----------------|
+| `id` | `id` |
+| `title` | `title` |
+| `description` | `content` |
+| `status` | `status` |
+| `priority` | `priority` |
+| `dependencies` | Edges (`depends-on`) |
+| `subtasks` | Child specs via `parent-of` edges |
+
+#### Directory Structure
+
+```
+tasks/
+├── tasks.json          # Task definitions
+├── prd.txt            # Product requirements document
+└── complexity-report.json
+```
+
+---
+
+### Native Context Provider
+
+Fallback provider for context when no external context tool is configured. Like native tasks, these are stored directly as `Context` type in `graph.jsonl`.
+
+```typescript
+interface NativeContextProvider extends ContentProvider {
+  name: 'native'
+  schemes: ['native', 'opentasks']
+  nodeTypes: ['context']
+
+  capabilities: {
+    read: true,
+    write: true,
+    delete: true,
+    search: true,
+    watch: true,    // file watcher on graph.jsonl
+    ready: false
+  }
+}
+```
+
+**Storage**: Native context use the `Context` type directly in `graph.jsonl`:
+```json
+{
+  "id": "c-a2b3",
+  "type": "context",
+  "title": "Authentication requirements",
+  "content": "## Overview\n...",
+  ...
+}
+```
+
+---
+
+## Provider Registry
+
+The provider registry manages configured providers and routes operations.
+
+```typescript
+interface ProviderRegistry {
+  /** Register a provider */
+  register(provider: ContentProvider): void
+
+  /** Get provider for a URI */
+  getProvider(uri: string): ContentProvider | null
+
+  /** Get provider by name */
+  getByName(name: string): ContentProvider | null
+
+  /** Get primary provider for a node type */
+  getPrimary(nodeType: 'context' | 'task'): ContentProvider
+
+  /** Get fallback provider for a node type */
+  getFallback(nodeType: 'context' | 'task'): ContentProvider
+
+  /** Resolve a URI to a node (with caching) */
+  resolve(uri: string, options?: ResolveOptions): Promise<ProviderNode | null>
+
+  /** List all registered providers */
+  list(): ContentProvider[]
+}
+
+interface ResolveOptions {
+  /** Skip cache and fetch fresh */
+  fresh?: boolean
+
+  /** Return cached even if stale */
+  allowStale?: boolean
+
+  /** Timeout for fetch */
+  timeout?: number
+}
+```
+
+### Resolution Flow
+
+```typescript
+async function resolve(uri: string, options?: ResolveOptions): Promise<ProviderNode | null> {
+  // 1. Check cache (unless fresh requested)
+  if (!options?.fresh) {
+    const cached = await cache.get(uri)
+    if (cached && (!cached.stale || options?.allowStale)) {
+      return cached.node
+    }
+  }
+
+  // 2. Find provider for URI scheme
+  const provider = registry.getProvider(uri)
+  if (!provider) {
+    // Return cached if available, even without provider
+    return cache.get(uri)?.node || null
+  }
+
+  // 3. Fetch from provider
+  const id = parseIdFromUri(uri)
+  const node = await provider.get(id)
+
+  // 4. Update cache
+  if (node) {
+    await cache.set(uri, node)
+  }
+
+  return node
+}
+```
+
+---
+
+## Adapter Pattern
+
+Adapters extend Providers with bidirectional sync capabilities. Use adapters when:
+- Changes in OpenTasks should propagate to the external system
+- The external system and OpenTasks need to stay in sync
+
+### Adapter Interface
+
+```typescript
+/**
+ * Adapter extends Provider with write-back capabilities
+ */
+interface ContentAdapter extends ContentProvider {
+  /** Adapter-specific capabilities */
+  readonly adapterCapabilities: AdapterCapabilities
+
+  // === Sync Operations ===
+
+  /** Push local changes to external system */
+  push(changes: ChangeSet): Promise<PushResult>
+
+  /** Pull and merge external changes */
+  pull(): Promise<PullResult>
+
+  /** Resolve sync conflicts */
+  resolveConflict?(conflict: SyncConflict): Promise<Resolution>
+
+  /** Get sync status */
+  syncStatus(): Promise<SyncStatus>
+}
+
+interface AdapterCapabilities {
+  /** Can push changes to external system */
+  pushEnabled: boolean
+
+  /** Can handle conflicts */
+  conflictResolution: boolean
+
+  /** Supports incremental sync */
+  incrementalSync: boolean
+
+  /** Supports webhooks for real-time sync */
+  webhooks: boolean
+}
+
+interface SyncConflict {
+  uri: string
+  localVersion: ProviderNode
+  remoteVersion: ProviderNode
+  conflictType: 'update' | 'delete' | 'create'
+}
+
+interface Resolution {
+  winner: 'local' | 'remote' | 'merged'
+  mergedNode?: ProviderNode
+}
+
+interface SyncStatus {
+  lastSync: string
+  pendingPush: number
+  pendingPull: number
+  conflicts: SyncConflict[]
+}
+```
+
+### Conflict Resolution Strategies
+
+| Strategy | Description | Use Case |
+|----------|-------------|----------|
+| `local-wins` | Local changes overwrite remote | OpenTasks is authoritative |
+| `remote-wins` | Remote changes overwrite local | External system is authoritative |
+| `last-write-wins` | Most recent `updated_at` wins | Simple merge |
+| `manual` | Queue for user resolution | Critical data |
+| `content-hash` | Skip if content identical | Avoid false conflicts |
+
+### Example: Linear Adapter
+
+```typescript
+class LinearAdapter extends LinearProvider implements ContentAdapter {
+  readonly adapterCapabilities = {
+    pushEnabled: true,
+    conflictResolution: true,
+    incrementalSync: true,
+    webhooks: true
+  }
+
+  async push(changes: ChangeSet): Promise<PushResult> {
+    const results: PushResult = { success: [], failed: [] }
+
+    for (const change of changes.updates) {
+      try {
+        await this.linearClient.updateIssue(change.id, {
+          title: change.title,
+          description: change.content,
+          state: this.mapStatusToLinear(change.status)
+        })
+        results.success.push(change.uri)
+      } catch (err) {
+        results.failed.push({ uri: change.uri, error: err })
+      }
+    }
+
+    return results
+  }
+
+  async pull(): Promise<PullResult> {
+    const since = await this.getLastSyncTimestamp()
+    const remoteChanges = await this.linearClient.issues({
+      filter: { updatedAt: { gte: since } }
+    })
+
+    return {
+      changes: remoteChanges.map(this.toOpenTasks),
+      syncTimestamp: new Date().toISOString()
+    }
+  }
+}
+```
+
+---
+
+## SyncTarget Pattern
+
+SyncTargets are write-only integrations where OpenTasks is the source of truth.
+
+```typescript
+interface SyncTarget {
+  readonly name: string
+  readonly schemes: string[]
+
+  /** Export nodes to target system */
+  export(nodes: Node[]): Promise<ExportResult>
+
+  /** Map OpenTasks node to target format */
+  toTargetFormat(node: Node): unknown
+
+  /** Get export status */
+  exportStatus(): Promise<ExportStatus>
+}
+```
+
+Use SyncTargets for:
+- Exporting to read-only systems (static sites, docs)
+- One-way mirroring to backup systems
+- Publishing to external trackers
+
+---
+
+## Node Registry & ExternalNodes
+
+The node registry bridges provider URIs to the OpenTasks graph. When an edge references an external URI, the registry manages the corresponding `ExternalNode`.
+
+### Relationship to ExternalNode
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Edge                                      │
+│  { from_id: "t-local", to_id: "beads://./bd-123", type: "..." } │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Node Registry                                 │
+│  - Looks up or creates ExternalNode for "beads://./bd-123"      │
+│  - Manages materialization state                                 │
+│  - Coordinates with Provider for fetching                        │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    ExternalNode (in graph.jsonl)                 │
+│  {                                                               │
+│    "id": "e-p6q7",                                               │
+│    "type": "external",                                           │
+│    "uri": "beads://./bd-123",                                    │
+│    "source": "beads",                                            │
+│    "materialized": true,                                         │
+│    "title": "Fix login bug",  // cached from provider            │
+│    "external_data": { ... }   // provider-specific data          │
+│  }                                                               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Registry Interface
+
+```typescript
+interface NodeRegistry {
+  /** Get or create ExternalNode for a URI */
+  ensureNode(uri: string): Promise<ExternalNode>
+
+  /** Get ExternalNode by URI (returns null if not registered) */
+  get(uri: string): Promise<ExternalNode | null>
+
+  /** Materialize a phantom node (fetch from provider) */
+  materialize(uri: string, options?: MaterializeOptions): Promise<ExternalNode>
+
+  /** Mark node as stale (needs refresh) */
+  markStale(uri: string): Promise<void>
+
+  /** List all external nodes */
+  list(filter?: RegistryFilter): Promise<ExternalNode[]>
+
+  /** Remove ExternalNode (and its edges) */
+  remove(uri: string): Promise<void>
+}
+
+interface MaterializeOptions {
+  /** Force refresh even if cached */
+  force?: boolean
+
+  /** Timeout for provider fetch */
+  timeout?: number
+
+  /** Depth to follow nested references */
+  depth?: number
+}
+
+interface RegistryFilter {
+  /** Filter by provider */
+  provider?: string
+
+  /** Filter by materialization state */
+  materialized?: boolean
+
+  /** Filter by stale state */
+  stale?: boolean
+
+  /** Filter by source type */
+  source?: string
+}
+```
+
+### Storage
+
+ExternalNodes are stored in `graph.jsonl` alongside other node types (see [SCHEMA.md](./SCHEMA.md)):
+
+```jsonl
+{"id":"e-x7k9","uuid":"...","type":"external","title":"Implement auth","uri":"beads://./bd-x7k9","source":"beads","materialized":true,"cached_at":"2025-01-26T12:00:00Z","external_data":{"status":"in_progress"},"created_at":"2025-01-26T10:00:00Z","updated_at":"2025-01-26T12:00:00Z"}
+{"id":"e-prd1","uuid":"...","type":"external","title":"Authentication PRD","uri":"taskmaster://./prd-1","source":"taskmaster","materialized":true,"cached_at":"2025-01-26T12:00:00Z","created_at":"2025-01-26T10:00:00Z","updated_at":"2025-01-26T12:00:00Z"}
+{"id":"e-jira","uuid":"...","type":"external","title":"","uri":"jira://PROJ-123","source":"jira","materialized":false,"created_at":"2025-01-26T10:00:00Z","updated_at":"2025-01-26T10:00:00Z"}
+```
+
+**Key points:**
+- `materialized: false` indicates a phantom node (just the reference, no data)
+- `external_data` contains provider-specific fields
+- `cached_at` tracks freshness
+- Standard `id`, `uuid`, `created_at`, `updated_at` fields like other nodes
+
+---
+
+## Cache Strategy
+
+### Cache Layers
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      Application / Client                        │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     Daemon (coordinator)                         │
+│  - Routes requests to appropriate cache/provider                 │
+│  - Manages materialization                                       │
+│  - Handles cross-location resolution                             │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   ExternalNodes (in graph.jsonl)                 │
+│  - Persistent cache of external data                             │
+│  - Title, external_data for display                              │
+│  - Tracked materialization/stale state                           │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    SQLite Index (cache.db)                       │
+│  - Fast lookups and queries                                      │
+│  - Query indexes over graph.jsonl                                │
+│  - Gitignored (can be rebuilt)                                   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      Provider (source of truth)                  │
+│  - Beads: .beads/issues.jsonl                                    │
+│  - Taskmaster: tasks/tasks.json                                  │
+│  - Linear: GraphQL API                                           │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Important**: ExternalNodes in `graph.jsonl` are the persistent cache. The SQLite `cache.db` is an index/query accelerator that can be rebuilt from the JSONL files.
+
+### Cache Invalidation
+
+```typescript
+interface CacheConfig {
+  /** Default TTL for cached nodes (ms) */
+  defaultTtl: number  // default: 300000 (5 minutes)
+
+  /** TTL overrides per provider */
+  providerTtl?: Record<string, number>
+
+  /** Stale-while-revalidate window (ms) */
+  staleWhileRevalidate: number  // default: 60000 (1 minute)
+
+  /** Maximum cache size (entries) */
+  maxSize: number  // default: 10000
+}
+
+// Invalidation triggers:
+// 1. TTL expiry
+// 2. Provider watch event
+// 3. Manual invalidation (user request)
+// 4. Write operation to same node
+```
+
+### Watch-Based Invalidation
+
+When a provider supports `watch()`, OpenTasks subscribes to changes:
+
+```typescript
+// On startup, subscribe to provider changes
+for (const provider of registry.list()) {
+  if (provider.capabilities.watch && provider.watch) {
+    provider.watch((event) => {
+      // Invalidate cache for changed node
+      cache.markStale(event.uri)
+
+      // Optionally refresh immediately
+      if (config.eagerRefresh) {
+        registry.resolve(event.uri, { fresh: true })
+      }
+    })
+  }
+}
+```
+
+---
+
+## Configuration
+
+### Provider Configuration
+
+```json
+// .opentasks/config.json
+{
+  "version": "1.0",
+
+  "providers": {
+    "issues": {
+      "primary": "beads",
+      "fallback": "native",
+      "beads": {
+        "workspace": ".",
+        "cli": "bd"
+      },
+      "linear": {
+        "api_key": "${LINEAR_API_KEY}",
+        "team": "ENG"
+      }
+    },
+    "context": {
+      "primary": "taskmaster",
+      "fallback": "native",
+      "taskmaster": {
+        "project": "."
+      }
+    }
+  },
+
+  "cache": {
+    "default_ttl": 300000,
+    "stale_while_revalidate": 60000,
+    "max_size": 10000,
+    "provider_ttl": {
+      "linear": 60000,
+      "beads": 0
+    }
+  },
+
+  "sync": {
+    "watch": true,
+    "debounce": 1000
+  }
+}
+```
+
+### Environment Variables
+
+```bash
+# Provider API keys
+export LINEAR_API_KEY=lin_api_xxxxx
+export JIRA_API_TOKEN=xxxxx
+
+# Override primary providers
+export OPENTASKS_ISSUE_PROVIDER=linear
+export OPENTASKS_SPEC_PROVIDER=native
+
+# Disable caching (for debugging)
+export OPENTASKS_NO_CACHE=1
+```
+
+---
+
+## Cross-Provider Edges
+
+Edges can connect nodes from different providers:
+
+```typescript
+// Context from Taskmaster implements Task from Beads
+{
+  id: "x-abc123",
+  from_id: "beads://./bd-x7k9",
+  to_id: "taskmaster://./prd-1",
+  type: "implements"
+}
+
+// Native context blocks Beads issue
+{
+  id: "x-def456",
+  from_id: "native://c-local",
+  to_id: "beads://./bd-y8z9",
+  type: "blocks"
+}
+```
+
+### Cross-Provider Queries
+
+```typescript
+// Get all tasks implementing a context (across providers)
+async function getImplementingIssues(specUri: string): Promise<ProviderNode[]> {
+  // 1. Get edges from this context
+  const edges = await edgeStore.query({
+    to_id: specUri,
+    type: 'implements'
+  })
+
+  // 2. Resolve each source node (may be from different providers)
+  return Promise.all(
+    edges.map(edge => registry.resolve(edge.from_id))
+  )
+}
+
+// Get blockers for a task (may include context and tasks)
+async function getBlockers(issueUri: string): Promise<ProviderNode[]> {
+  const edges = await edgeStore.query({
+    to_id: issueUri,
+    type: 'blocks'
+  })
+
+  return Promise.all(
+    edges.map(edge => registry.resolve(edge.from_id))
+  )
+}
+```
+
+---
+
+## Ready Query
+
+The `ready()` query finds nodes that are ready to work on. This requires checking cross-provider blocking relationships.
+
+```typescript
+async function ready(): Promise<ProviderNode[]> {
+  // 1. Get all open tasks from primary provider
+  const provider = registry.getPrimary('task')
+  let candidates: ProviderNode[]
+
+  if (provider.capabilities.ready && provider.ready) {
+    // Provider has native ready support (e.g., Beads `bd ready`)
+    candidates = await provider.ready()
+  } else {
+    // Fall back to listing open tasks
+    candidates = await provider.list({ status: 'open' })
+  }
+
+  // 2. Filter by OpenTasks edges (cross-provider blockers)
+  const ready: ProviderNode[] = []
+
+  for (const candidate of candidates) {
+    const blockers = await edgeStore.query({
+      to_id: candidate.uri,
+      type: 'blocks'
+    })
+
+    // Check if all blockers are resolved
+    const unresolvedBlockers = await Promise.all(
+      blockers.map(async (edge) => {
+        const blocker = await registry.resolve(edge.from_id)
+        return blocker && blocker.status !== 'closed'
+      })
+    )
+
+    if (!unresolvedBlockers.some(Boolean)) {
+      ready.push(candidate)
+    }
+  }
+
+  return ready
+}
+```
+
+---
+
+## Adding a New Provider
+
+To add a new provider:
+
+1. **Implement the interface**
+
+```typescript
+class MyProvider implements ContentProvider {
+  name = 'myprovider'
+  schemes = ['myprovider', 'mp']
+  nodeTypes = ['task'] // or ['context'] or both
+
+  capabilities = {
+    read: true,
+    write: true,
+    delete: false,
+    search: true,
+    watch: false,
+    ready: false
+  }
+
+  async get(id: string): Promise<ProviderNode | null> {
+    // Implement fetching
+  }
+
+  async list(filter?: ProviderFilter): Promise<ProviderNode[]> {
+    // Implement listing
+  }
+
+  toOpenTasks(native: MyNativeFormat): ProviderNode {
+    // Implement mapping
+  }
+
+  fromOpenTasks(node: ProviderNode): MyNativeFormat {
+    // Implement reverse mapping
+  }
+}
+```
+
+2. **Register the provider**
+
+```typescript
+import { registry } from 'opentasks'
+
+registry.register(new MyProvider())
+```
+
+3. **Configure in config.json**
+
+```json
+{
+  "providers": {
+    "issues": {
+      "primary": "myprovider",
+      "myprovider": {
+        "api_key": "${MY_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Analogous Systems
+
+The federated graph model draws inspiration from:
+
+| System | Pattern | Similarity |
+|--------|---------|------------|
+| **RDF/Linked Data** | URIs reference external resources | Node URIs can point anywhere |
+| **GraphQL Federation** | Gateway stitches across services | OpenTasks stitches across providers |
+| **Git Object Model** | Trees (structure) separate from blobs (content) | Edges separate from node content |
+| **Neo4j + MongoDB** | Graph DB for relationships, doc DB for content | OpenTasks for graph, providers for content |
+| **Kubernetes + External Secrets** | K8s references, external systems own data | OpenTasks references, providers own data |
+
+---
+
+## Open Questions
+
+### Resolved
+- [x] **Provider discovery**: Providers configured in `.opentasks/config.json`; auto-detection is optional enhancement
+- [x] **Bidirectional edges**: Providers don't need to know about OpenTasks edges; edges are OpenTasks-owned
+
+### Open
+- [ ] **Multi-workspace**: How to handle multiple Beads workspaces in same project? Multiple provider instances?
+- [ ] **Conflict resolution**: When edge says "blocks" but provider says "closed"? Trust provider status, mark edge stale?
+- [ ] **Provider versioning**: How to handle provider schema changes? Migration scripts per provider?
+- [ ] **Adapter sync frequency**: How often should adapters sync? Event-driven vs polling vs manual?
+- [ ] **Cross-location providers**: Can a provider span multiple locations? Or one provider instance per location?
+- [ ] **Provider health checks**: Should daemon periodically verify provider availability?
+- [ ] **Materialization depth**: When materializing, how deep to follow nested external references?
+
+---
+
+## References
+
+### External
+- [Beads Documentation](https://github.com/steveyegge/beads)
+- [Taskmaster Documentation](https://github.com/eyaltoledano/claude-task-master)
+- [Linear API](https://developers.linear.app/docs)
+
+### Internal
+- [DESIGN.md](./DESIGN.md) — Design rationale and core concepts
+- [SCHEMA.md](./SCHEMA.md) — Data model (ExternalNode, edges)
+- [PERSISTENCE.md](./PERSISTENCE.md) — Storage layer and sync
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — Daemon, locations, URIs