claude-code-swarm 0.3.4 → 0.3.6

package/references/opentasks/docs/TESTING.md

@@ -0,0 +1,1081 @@
+# OpenTasks Testing Strategy
+
+This document outlines the current state of testing in OpenTasks, identifies gaps, and proposes a tiered testing strategy for comprehensive coverage.
+
+## Current State
+
+### Test Coverage Summary
+
+| Layer | Test Files | Tests | Coverage Type |
+|-------|-----------|-------|---------------|
+| Core | 2 | 34 | Unit |
+| Schema | 1 | 24 | Unit |
+| Storage | 2 | 65 | Unit + File I/O |
+| Graph | 9 | 332 | Unit |
+| Daemon | 8 | 174 | Unit |
+| Tools | 3 | 59 | Unit |
+| Client | 1 | 23 | Unit |
+| Providers | 6 | 215 | Unit |
+| **Total** | **33** | **926** | **Primarily Unit** |
+
+### What's Tested
+
+**Well-tested with unit tests:**
+- ID generation and hashing (deterministic, collision-resistant)
+- Schema validation (Zod parsing, type guards)
+- JSONL and SQLite persistence (file operations, transactions)
+- Graph operations (CRUD, queries, validation, cycles)
+- **Federated Graph layer:**
+  - EdgeTypeRegistry (12 built-in types, inverse relationships, provider support)
+  - GraphologyAdapter (in-memory graph with Graphology library)
+  - FederatedGraph (traversal API: related, reachable, shortestPath, traverse)
+  - HydratingFederatedGraph (lazy hydration, caching, federated ready query)
+  - Provider-aware store (cross-provider resolution)
+  - Selector syntax (+uri, uri+, @uri) and introspection methods
+- Daemon lifecycle, IPC, file watching, flush management
+- Daemon method handlers (graph operations, tool operations)
+- 3-tool agent interface (link, query, annotate)
+- Client library (connection, method calls, error handling)
+- Provider interface (URI parsing, type conversion, CRUD)
+- **Provider traits:**
+  - RelationshipQueryable (queryEdges, supportedEdgeTypes)
+  - NativeProvider with full edge support
+  - BeadsProvider with relationship queries
+
+**File I/O tested with temp directories:**
+- JSONL persister writes to real temp files
+- SQLite persister uses in-memory databases
+- File watcher uses real file system events (with delays)
+
+### Testing Gaps
+
+#### Gap 1: Provider Integration Tests
+
+All provider tests use mocks. No tests verify actual integration with:
+
+| Provider | Mock Strategy | Integration Gap |
+|----------|---------------|-----------------|
+| **BeadsProvider** | Mocks `child_process.exec` | Never calls real `bd` CLI |
+| **ClaudeTasksProvider** | Uses in-memory store | Never interacts with Claude Code task system |
+| **NativeProvider** | Mocks GraphStore | N/A (no external system) |
+
+#### Gap 2: End-to-End Agent Workflows
+
+No tests verify complete agent workflows:
+- Agent creates context → links tasks → provides feedback
+- Multi-agent coordination with blocking dependencies
+- Full daemon lifecycle with real IPC communication
+
+#### Gap 3: Cross-System Integration
+
+No tests verify:
+- OpenTasks ↔ Beads bidirectional sync
+- OpenTasks ↔ Claude Code task materialization
+- Multi-location graph operations
+
+#### Gap 4: Performance and Stress Testing
+
+No tests for:
+- Large graph operations (10k+ nodes)
+- High-frequency flush operations
+- Concurrent multi-client access
+
+---
+
+## Tiered Testing Strategy
+
+### Test Flags
+
+Tests are gated by environment flags to control which tests run:
+
+| Flag | Purpose | When to Use |
+|------|---------|-------------|
+| (none) | Unit tests only | Every commit, CI default |
+| `RUN_SLOW_TESTS=1` | + Integration tests | Pre-merge, nightly CI |
+| `RUN_FULL_AGENT_TESTS=1` | + E2E agent tests | Release validation, manual |
+
+**Flag behavior:**
+- `RUN_SLOW_TESTS` enables storage durability, daemon IPC, and provider integration tests
+- `RUN_FULL_AGENT_TESTS` enables full agent workflow tests (implies `RUN_SLOW_TESTS`)
+- Tests check flags via `process.env` and skip with descriptive messages
+
+```typescript
+// Example usage in tests
+const SLOW_TESTS = process.env.RUN_SLOW_TESTS === '1'
+const AGENT_TESTS = process.env.RUN_FULL_AGENT_TESTS === '1'
+
+describe.skipIf(!SLOW_TESTS)('Storage Durability', () => {
+  // These tests take 10+ seconds each
+})
+
+describe.skipIf(!AGENT_TESTS)('Multi-Agent Coordination', () => {
+  // These tests require full system setup
+})
+```
+
+---
+
+### Tier 1: Unit Tests (Current)
+
+**Status:** ✅ Complete (723 tests)
+
+**Purpose:** Verify individual components work correctly in isolation.
+
+**Characteristics:**
+- Fast execution (<5 seconds total)
+- No external dependencies
+- Mocked collaborators
+- Run on every commit
+
+**Location:** `src/**/__tests__/*.test.ts`
+
+**Flag:** None (always run)
+
+### Tier 2: Integration Tests
+
+**Status:** ✅ Phases 1-4 Complete (127 tests)
+
+**Purpose:** Verify components work together with real I/O and external systems.
+
+**Characteristics:**
+- Slower execution (10-60 seconds per test)
+- Real file I/O, process spawning, IPC
+- Run before merge, nightly CI
+
+**Location:** `tests/integration/`
+
+**Flag:** `RUN_SLOW_TESTS=1`
+
+#### 2.1 Storage Integration Tests (Priority: High)
+
+**Purpose:** Verify persistence durability and performance under stress.
+
+**Requirements:**
+- File system access
+- Sufficient disk space for large tests
+
+**Test Cases:**
+```typescript
+// tests/integration/storage/jsonl-durability.integration.test.ts
+
+const SLOW_TESTS = process.env.RUN_SLOW_TESTS === '1'
+
+describe.skipIf(!SLOW_TESTS)('JSONL Durability', () => {
+  describe('crash recovery', () => {
+    it('should recover from incomplete write (simulated crash)', async () => {
+      // Write partial line, verify recovery on reload
+    })
+
+    it('should handle corrupted trailing entry', async () => {
+      // Append garbage, verify load skips bad entry
+    })
+  })
+
+  describe('compaction', () => {
+    it('should compact correctly with 1000+ entries', async () => {
+      // Create 1000 nodes, delete 500, compact, verify
+    })
+
+    it('should maintain data integrity during compaction', async () => {
+      // Verify no data loss during compaction
+    })
+  })
+
+  describe('concurrent access', () => {
+    it('should handle concurrent readers during write', async () => {
+      // Spawn multiple read processes while writing
+    })
+  })
+})
+```
+
+```typescript
+// tests/integration/storage/sqlite-durability.integration.test.ts
+
+describe.skipIf(!SLOW_TESTS)('SQLite Durability', () => {
+  describe('crash recovery', () => {
+    it('should survive simulated crash during transaction', async () => {
+      // Use WAL mode, kill process mid-transaction, verify recovery
+    })
+  })
+
+  describe('performance', () => {
+    it('should handle 10k+ nodes efficiently', async () => {
+      // Create 10k nodes, measure insert/query times
+      // Assert: bulk insert < 5s, query < 100ms
+    })
+
+    it('should handle complex graph queries', async () => {
+      // Create deep dependency chains, measure traversal
+    })
+  })
+
+  describe('WAL mode', () => {
+    it('should support concurrent readers and single writer', async () => {
+      // Spawn reader processes while writing
+    })
+  })
+})
+```
+
+#### 2.2 Daemon Integration Tests (Priority: High)
+
+**Purpose:** Verify daemon lifecycle and IPC with real processes.
+
+**Requirements:**
+- Ability to spawn child processes
+- IPC socket access
+- Process signal handling
+
+**Test Cases:**
+```typescript
+// tests/integration/daemon/lifecycle.integration.test.ts
+
+describe.skipIf(!SLOW_TESTS)('Daemon Lifecycle', () => {
+  let daemonProcess: ChildProcess
+
+  afterEach(async () => {
+    if (daemonProcess) {
+      daemonProcess.kill('SIGTERM')
+      await waitForExit(daemonProcess)
+    }
+  })
+
+  describe('startup', () => {
+    it('should start and create socket file', async () => {
+      daemonProcess = spawn('node', ['./dist/daemon.js', '--socket', socketPath])
+      await waitForSocket(socketPath, 5000)
+      expect(existsSync(socketPath)).toBe(true)
+    })
+
+    it('should detect existing daemon and refuse to start', async () => {
+      // Start first daemon
+      daemonProcess = spawn('node', ['./dist/daemon.js', '--socket', socketPath])
+      await waitForSocket(socketPath)
+
+      // Try to start second daemon
+      const second = spawn('node', ['./dist/daemon.js', '--socket', socketPath])
+      const exitCode = await waitForExit(second)
+      expect(exitCode).toBe(1)
+    })
+  })
+
+  describe('shutdown', () => {
+    it('should flush pending writes on SIGTERM', async () => {
+      daemonProcess = spawn('node', ['./dist/daemon.js'])
+      await waitForSocket(socketPath)
+
+      // Make some writes via IPC
+      const client = createIPCClient(socketPath)
+      await client.connect()
+      await client.createNode({ type: 'context', title: 'Test' })
+
+      // Send SIGTERM
+      daemonProcess.kill('SIGTERM')
+      await waitForExit(daemonProcess)
+
+      // Verify data persisted
+      const persister = createJSONLPersister(dataPath)
+      const data = await persister.load()
+      expect(data.nodes).toHaveLength(1)
+    })
+
+    it('should clean up socket file on exit', async () => {
+      daemonProcess = spawn('node', ['./dist/daemon.js', '--socket', socketPath])
+      await waitForSocket(socketPath)
+
+      daemonProcess.kill('SIGTERM')
+      await waitForExit(daemonProcess)
+
+      expect(existsSync(socketPath)).toBe(false)
+    })
+  })
+})
+```
+
+```typescript
+// tests/integration/daemon/ipc.integration.test.ts
+
+describe.skipIf(!SLOW_TESTS)('Daemon IPC', () => {
+  let daemon: ChildProcess
+  let client: IPCClient
+
+  beforeAll(async () => {
+    daemon = spawn('node', ['./dist/daemon.js', '--socket', socketPath])
+    await waitForSocket(socketPath, 5000)
+    client = createIPCClient(socketPath)
+    await client.connect()
+  })
+
+  afterAll(async () => {
+    await client.disconnect()
+    daemon.kill('SIGTERM')
+    await waitForExit(daemon)
+  })
+
+  describe('round-trip', () => {
+    it('should handle create → get → update → delete cycle', async () => {
+      const created = await client.createNode({ type: 'context', title: 'Test' })
+      expect(created.id).toMatch(/^s-/)
+
+      const fetched = await client.getNode(created.id)
+      expect(fetched?.title).toBe('Test')
+
+      const updated = await client.updateNode(created.id, { title: 'Updated' })
+      expect(updated.title).toBe('Updated')
+
+      await client.deleteNode(created.id)
+      const deleted = await client.getNode(created.id)
+      expect(deleted).toBeNull()
+    })
+  })
+
+  describe('concurrent clients', () => {
+    it('should handle 10 concurrent clients', async () => {
+      const clients = await Promise.all(
+        Array.from({ length: 10 }, async () => {
+          const c = createIPCClient(socketPath)
+          await c.connect()
+          return c
+        })
+      )
+
+      // All clients create nodes concurrently
+      const results = await Promise.all(
+        clients.map((c, i) => c.createNode({ type: 'task', title: `Issue ${i}` }))
+      )
+
+      expect(results).toHaveLength(10)
+      expect(new Set(results.map(r => r.id)).size).toBe(10) // All unique IDs
+
+      await Promise.all(clients.map(c => c.disconnect()))
+    })
+  })
+
+  describe('error handling', () => {
+    it('should return error for invalid node ID', async () => {
+      await expect(client.getNode('invalid-id')).rejects.toThrow()
+    })
+
+    it('should recover from client disconnect', async () => {
+      const tempClient = createIPCClient(socketPath)
+      await tempClient.connect()
+      await tempClient.createNode({ type: 'context', title: 'Before disconnect' })
+
+      // Abrupt disconnect (no graceful close)
+      tempClient.socket.destroy()
+
+      // Original client should still work
+      const result = await client.createNode({ type: 'context', title: 'After disconnect' })
+      expect(result.id).toBeDefined()
+    })
+  })
+})
+```
+
+#### 2.3 BeadsProvider Integration Tests (Priority: Medium)
+
+**Purpose:** Verify BeadsProvider works with real `bd` CLI.
+
+**Requirements:**
+- Beads (`bd`) CLI installed and configured
+- Test Beads directory with fixtures
+
+**Test Fixtures:**
+```
+tests/fixtures/beads/
+├── .beads/          # Beads database directory
+│   └── beads.db     # SQLite database
+├── bd-test1.md      # Test bead with known content
+├── bd-test2.md      # Test bead for update operations
+└── bd-temp.md       # For create/delete tests
+```
+
+**Test Cases:**
+
+```typescript
+// tests/integration/providers/beads.integration.test.ts
+
+const SLOW_TESTS = process.env.RUN_SLOW_TESTS === '1'
+
+// Additional check: skip if bd CLI not available
+async function checkBdAvailable(): Promise<boolean> {
+  try {
+    await exec('bd --version')
+    return true
+  } catch {
+    return false
+  }
+}
+
+describe.skipIf(!SLOW_TESTS)('BeadsProvider Integration', () => {
+  beforeAll(async () => {
+    if (!(await checkBdAvailable())) {
+      console.log('Skipping: bd CLI not installed')
+      return
+    }
+  })
+
+  describe('read operations', () => {
+    it('should read existing bead from real Beads directory')
+    it('should parse bead frontmatter correctly')
+    it('should handle bead with links')
+    it('should return null for non-existent bead')
+  })
+
+  describe('write operations', () => {
+    it('should create new bead via bd CLI')
+    it('should update existing bead')
+    it('should delete bead')
+  })
+
+  describe('search operations', () => {
+    it('should search beads by content')
+    it('should filter by type/tags')
+  })
+
+  describe('URI handling', () => {
+    it('should resolve relative beads:// URIs')
+    it('should handle workspace-relative paths')
+  })
+})
+```
+
+**Dev Dependencies:**
+- None required (uses system `bd` CLI)
+- CI skips if `bd` not available
+
+#### 2.4 ClaudeTasksProvider Integration Tests (Priority: Low)
+
+**Purpose:** Verify file-backed task store persistence.
+
+**Challenge:** Claude Code's task system is not directly accessible outside of Claude Code sessions. Integration tests focus on the file-backed store abstraction.
+
+**Test Cases:**
+```typescript
+// tests/integration/providers/claude-tasks.integration.test.ts
+
+const SLOW_TESTS = process.env.RUN_SLOW_TESTS === '1'
+
+describe.skipIf(!SLOW_TESTS)('ClaudeTasksProvider File Store', () => {
+  let tempDir: string
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'claude-tasks-'))
+  })
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true })
+  })
+
+  describe('persistence', () => {
+    it('should persist tasks to JSON file', async () => {
+      const store = createFileBackedTaskStore(join(tempDir, 'tasks.json'))
+      await store.create({ subject: 'Test', description: 'Desc' })
+
+      // Reload from file
+      const store2 = createFileBackedTaskStore(join(tempDir, 'tasks.json'))
+      const tasks = await store2.list()
+      expect(tasks).toHaveLength(1)
+    })
+
+    it('should handle concurrent access', async () => {
+      const path = join(tempDir, 'tasks.json')
+      const stores = Array.from({ length: 5 }, () => createFileBackedTaskStore(path))
+
+      // Concurrent writes
+      await Promise.all(
+        stores.map((s, i) => s.create({ subject: `Task ${i}`, description: '' }))
+      )
+
+      const finalStore = createFileBackedTaskStore(path)
+      const tasks = await finalStore.list()
+      expect(tasks.length).toBeGreaterThanOrEqual(1) // At least some should persist
+    })
+  })
+})
+```
+
+**Recommendation:** Full Claude Tasks integration best tested via E2E tests (Tier 3) running within actual Claude Code sessions.
+
+### Tier 3: End-to-End Tests (Proposed)
+
+**Purpose:** Verify complete workflows from agent perspective.
+
+**Characteristics:**
+- Slowest execution (minutes)
+- Requires full system setup (daemon, storage, providers)
+- Run before release, manual validation
+
+**Location:** `tests/e2e/`
+
+**Flag:** `RUN_FULL_AGENT_TESTS=1` (implies `RUN_SLOW_TESTS=1`)
+
+#### 3.1 Agent Workflow E2E Tests
+
+**Test Harness:**
+```typescript
+// tests/e2e/harness.ts
+
+interface TestAgent {
+  // Simulates an agent making tool calls
+  link(params: LinkParams): Promise<LinkResult>
+  query(params: QueryParams): Promise<QueryResult>
+  annotate(params: AnnotateParams): Promise<AnnotateResult>
+}
+
+function createTestAgent(client: OpenTasksClient): TestAgent
+```
+
+**Test Cases:**
+```typescript
+// tests/e2e/workflows/context-driven-development.e2e.test.ts
+
+const AGENT_TESTS = process.env.RUN_FULL_AGENT_TESTS === '1'
+
+describe.skipIf(!AGENT_TESTS)('Context-Driven Development Workflow', () => {
+  let agent: TestAgent
+
+  it('should complete full context→task→implementation cycle', async () => {
+    // 1. Create context
+    const contextResult = await agent.link({
+      action: 'create',
+      type: 'context',
+      title: 'Test Feature',
+      content: 'Feature requirements...',
+    })
+    expect(contextResult.id).toMatch(/^c-/)
+
+    // 2. Create implementing issue
+    const issueResult = await agent.link({
+      action: 'create',
+      type: 'task',
+      title: 'Implement Test Feature',
+      implements: specResult.id,
+    })
+
+    // 3. Query ready work
+    const readyResult = await agent.query({ type: 'ready' })
+    expect(readyResult.nodes).toContainEqual(
+      expect.objectContaining({ id: issueResult.id })
+    )
+
+    // 4. Provide feedback
+    await agent.annotate({
+      target_id: specResult.id,
+      feedback_type: 'comment',
+      content: 'Implementation complete',
+    })
+
+    // 5. Close issue
+    await agent.link({
+      action: 'update',
+      id: issueResult.id,
+      status: 'closed',
+    })
+
+    // 6. Verify issue no longer ready
+    const finalReady = await agent.query({ type: 'ready' })
+    expect(finalReady.nodes).not.toContainEqual(
+      expect.objectContaining({ id: issueResult.id })
+    )
+  })
+})
+```
+
+#### 3.2 Multi-Agent Coordination E2E Tests
+
+```typescript
+// tests/e2e/workflows/multi-agent.e2e.test.ts
+
+const AGENT_TESTS = process.env.RUN_FULL_AGENT_TESTS === '1'
+
+describe.skipIf(!AGENT_TESTS)('Multi-Agent Coordination', () => {
+  let agent1: TestAgent
+  let agent2: TestAgent
+
+  it('should coordinate via blocking dependencies', async () => {
+    // Agent 1 creates foundation issue
+    const foundationIssue = await agent1.link({
+      action: 'create',
+      type: 'task',
+      title: 'Foundation Work',
+    })
+
+    // Agent 1 creates dependent issue
+    const dependentIssue = await agent1.link({
+      action: 'create',
+      type: 'task',
+      title: 'Dependent Work',
+      blocked_by: [foundationIssue.id],
+    })
+
+    // Agent 2 sees only foundation as ready
+    const agent2Ready = await agent2.query({ type: 'ready' })
+    expect(agent2Ready.nodes).toHaveLength(1)
+    expect(agent2Ready.nodes[0].id).toBe(foundationIssue.id)
+
+    // Agent 1 completes foundation
+    await agent1.link({
+      action: 'update',
+      id: foundationIssue.id,
+      status: 'closed',
+    })
+
+    // Agent 2 now sees dependent as ready
+    const agent2ReadyAfter = await agent2.query({ type: 'ready' })
+    expect(agent2ReadyAfter.nodes[0].id).toBe(dependentIssue.id)
+  })
+})
+```
+
+#### 3.3 Provider Sync E2E Tests
+
+```typescript
+// tests/e2e/workflows/provider-sync.e2e.test.ts
+
+const AGENT_TESTS = process.env.RUN_FULL_AGENT_TESTS === '1'
+
+describe.skipIf(!AGENT_TESTS)('Provider Synchronization', () => {
+  describe('OpenTasks ↔ Beads', () => {
+    it('should materialize Beads reference on first access')
+    it('should refresh stale materialized nodes')
+    it('should sync changes back to Beads')
+  })
+
+  describe('OpenTasks ↔ Claude Tasks', () => {
+    it('should bridge Claude task to OpenTasks issue')
+    it('should update Claude task when issue closes')
+  })
+})
+```
+
+---
+
+## Test Infrastructure
+
+### Test Configuration
+
+```typescript
+// vitest.config.ts additions
+
+export default defineConfig({
+  test: {
+    // Unit tests (fast, no external deps)
+    include: ['src/**/__tests__/*.test.ts'],
+
+    // Integration tests (separate config)
+    // Run with: vitest --config vitest.integration.config.ts
+  },
+})
+```
+
+```typescript
+// vitest.integration.config.ts
+
+export default defineConfig({
+  test: {
+    include: ['tests/integration/**/*.test.ts'],
+    testTimeout: 30000, // 30 seconds for external calls
+    hookTimeout: 60000, // 60 seconds for setup/teardown
+  },
+})
+```
+
+```typescript
+// vitest.e2e.config.ts
+
+export default defineConfig({
+  test: {
+    include: ['tests/e2e/**/*.test.ts'],
+    testTimeout: 120000, // 2 minutes per test
+    hookTimeout: 300000, // 5 minutes for full setup
+    maxConcurrency: 1,   // Run sequentially
+  },
+})
+```
+
+### npm Scripts
+
+```json
+{
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:slow": "RUN_SLOW_TESTS=1 vitest run",
+    "test:slow:watch": "RUN_SLOW_TESTS=1 vitest",
+    "test:e2e": "RUN_FULL_AGENT_TESTS=1 vitest run",
+    "test:all": "RUN_FULL_AGENT_TESTS=1 vitest run"
+  }
+}
+```
+
+**Usage:**
+```bash
+# Fast unit tests only (CI default)
+npm test
+
+# Include integration tests (slower, real I/O)
+npm run test:slow
+
+# Full test suite including E2E (slowest)
+npm run test:e2e
+
+# Watch mode with integration tests
+npm run test:slow:watch
+```
+
+### CI Pipeline
+
+```yaml
+# .github/workflows/test.yml
+
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  unit:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm test
+
+  integration:
+    name: Integration Tests (RUN_SLOW_TESTS)
+    runs-on: ubuntu-latest
+    needs: unit
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build  # Need compiled daemon
+      - name: Run integration tests
+        run: npm run test:slow
+        env:
+          RUN_SLOW_TESTS: '1'
+
+  e2e:
+    name: E2E Tests (RUN_FULL_AGENT_TESTS)
+    runs-on: ubuntu-latest
+    needs: integration
+    if: github.ref == 'refs/heads/main' || github.event_name == 'release'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+      - name: Run E2E tests
+        run: npm run test:e2e
+        env:
+          RUN_FULL_AGENT_TESTS: '1'
+```
+
+**Note:** Beads integration tests will skip automatically if `bd` CLI is not installed. To run Beads tests in CI, add a step to install the CLI.
+
+---
+
+## Implementation Roadmap
+
+### Phase 1: Integration Test Infrastructure ✅ COMPLETE
+
+1. ✅ Create `tests/integration/` directory structure
+2. ✅ Add `vitest.integration.config.ts`
+3. ✅ Add npm scripts with flag support
+4. ✅ Create test helper utilities (process spawning, temp dirs, wait helpers)
+
+**Deliverables:**
+- ✅ `tests/integration/helpers/` - shared utilities (flags, process, wait, temp)
+- ✅ `vitest.integration.config.ts`
+- ✅ Updated `package.json` scripts
+
+### Phase 2: Storage Integration Tests (RUN_SLOW_TESTS) ✅ COMPLETE
+
+**Priority: High** - Foundation for all persistence
+
+1. ✅ Create JSONL durability tests (16 tests)
+   - Crash recovery (partial writes, corrupted entries)
+   - Compaction with 1000+ entries
+   - Concurrent readers
+   - Performance baselines
+2. ✅ Create SQLite durability tests (17 tests)
+   - Transaction crash recovery
+   - 10k+ node performance baselines (insert <1s, query <500ms)
+   - WAL mode concurrent access
+   - Complex graph queries
+3. ✅ Add performance assertions
+
+**Deliverables:**
+- ✅ `tests/integration/storage/jsonl-durability.integration.test.ts`
+- ✅ `tests/integration/storage/sqlite-durability.integration.test.ts`
+
+### Phase 3: Daemon Integration Tests (RUN_SLOW_TESTS) ✅ COMPLETE
+
+**Priority: High** - Foundation for client-server architecture
+
+1. ✅ Create daemon spawn/lifecycle helpers
+2. ✅ Write lifecycle tests (19 tests: startup, shutdown, lock, registry)
+3. ✅ Write IPC round-trip tests (21 tests: request/response, error handling)
+4. ✅ Write concurrent client tests
+5. ✅ Write connection tracking tests
+
+**Deliverables:**
+- ✅ `tests/integration/daemon/helpers.ts`
+- ✅ `tests/integration/daemon/lifecycle.integration.test.ts`
+- ✅ `tests/integration/daemon/ipc.integration.test.ts`
+
+### Phase 4: Provider & Graph Integration Tests (RUN_SLOW_TESTS) ✅ COMPLETE
+
+**Priority: Medium** - External system integration and federated graph
+
+1. ✅ BeadsProvider integration (17 tests)
+   - CRUD operations (create, get, list, update, delete)
+   - Search operations
+   - URI handling
+   - Error handling
+   - Concurrent operations (5 creates, 10 reads)
+   - Workspace isolation
+   - Uses temp directories with git init + bd init
+
+2. ✅ Federated Graph integration (26 tests)
+   - Schema migration (edge metadata columns)
+   - Edge type registry with inverse relationships
+   - Graphology adapter synchronization
+   - Traversal API (related, reachable, shortestPath, traverse)
+   - Provider hydration with TTL caching
+   - Federated ready query with external blockers
+   - Cross-provider edge resolution
+   - Cache staleness detection
+   - Cycle handling
+
+3. ClaudeTasksProvider file store
+   - File-backed persistence tests (future work)
+
+**Deliverables:**
+- ✅ `tests/integration/providers/beads.integration.test.ts`
+- ✅ `tests/integration/graph/federated-graph.integration.test.ts`
+- `tests/integration/providers/claude-tasks.integration.test.ts` (future)
+
+**Provider Fixes Made:**
+- Fixed shell escaping for arguments with spaces
+- Fixed "not found" detection to handle bd error messages
+- Fixed bd show/update returning arrays instead of single objects
+
+### Phase 5: E2E Test Infrastructure (RUN_FULL_AGENT_TESTS) ✅ COMPLETE
+
+1. ✅ Create `tests/e2e/` directory structure
+2. ✅ Add `vitest.e2e.config.ts`
+3. ✅ Create TestAgent harness wrapping client
+4. ✅ Create full system setup/teardown helpers
+
+**Deliverables:**
+- ✅ `tests/e2e/helpers/system-setup.ts` - Full system setup (IPC server, SQLite storage, graph store, tool handlers, provider registry)
+- ✅ `tests/e2e/helpers/test-agent.ts` - TestAgent wrapper with 3-tool interface + provider operations + convenience methods
+- ✅ `tests/e2e/helpers/assertions.ts` - Assertion helpers (expectReady, expectNotReady, expectBlocks, expectBlockers, expectFeedback)
+- ✅ `tests/e2e/helpers/fixtures.ts` - Fixture helpers (createTestContext, createTestTask, createBlockingChain, createDiamondDependency)
+- ✅ `tests/e2e/helpers/index.ts` - Exports
+- ✅ `tests/e2e/infrastructure.e2e.test.ts` - 39 infrastructure tests
+- ✅ `vitest.e2e.config.ts` - E2E-specific configuration
+
+**Infrastructure Features:**
+- `setupE2ESystem()` / `withE2ESystem()` - Create isolated test environment with storage, IPC, client, and provider registry
+- `createTestAgent()` - Wrap client with named agent, logging, and provider operations (createContext, createTask, updateNode, closeTask, getNode)
+- `createMultiAgents()` - Create multiple agents for coordination tests
+- Assertion helpers for common test patterns
+- Fixture helpers for creating test data structures (chains, diamonds, context+tasks)
+- Automatic cleanup on teardown
+
+### Phase 6: Agent Workflow E2E Tests (RUN_FULL_AGENT_TESTS) ✅ COMPLETE
+
+**Priority: High** - Core value proposition validation
+
+1. ✅ Context-driven development workflow (10 tests)
+   - Full context→task→close cycle
+   - Multiple tasks implementing one context
+   - Task status filtering (open vs in_progress vs closed)
+   - Priority storage and retrieval
+   - Context content preservation and updates
+
+2. ✅ Multi-agent coordination (9 tests)
+   - Sequential blocking between agents
+   - Cross-agent blocking relationships
+   - Diamond dependency resolution
+   - Concurrent issue creation
+   - Transitive blocking queries (blockers/blocking with transitive option)
+   - Agent isolation with shared state
+
+3. ✅ Feedback loop tests (10 tests)
+   - Basic feedback operations (add, query, types)
+   - Feedback with issue context (from_id)
+   - Resolve/reopen feedback lifecycle
+   - Dismiss and filter feedback
+   - Filter by type
+   - Anchored feedback
+   - Feedback assertion helper
+
+**Deliverables:**
+- ✅ `tests/e2e/workflows/context-driven.e2e.test.ts` - 10 tests
+- ✅ `tests/e2e/workflows/multi-agent.e2e.test.ts` - 9 tests
+- ✅ `tests/e2e/workflows/feedback-loop.e2e.test.ts` - 10 tests
+
+**Key Learnings:**
+- Ready query only returns `status: 'open'` tasks (not `in_progress`)
+- Ready query doesn't sort by priority
+- LinkResult uses `success` and `edge_id` fields
+
+### Phase 7: Provider Sync E2E Tests (RUN_FULL_AGENT_TESTS) ✅ COMPLETE
+
+**Priority: Medium** - Cross-provider integration validation
+
+**Purpose:** Test cross-provider blocking dependencies between NativeProvider and BeadsProvider, hydration/caching behavior, materialization strategies, and background sync.
+
+**Requirements:**
+- `bd` CLI installed (tests skip gracefully if unavailable)
+- `RUN_FULL_AGENT_TESTS=1` environment variable
+
+1. ✅ Hydration & Caching tests (12 tests)
+   - First access hydration from BeadsProvider
+   - cached_at timestamp tracking
+   - Cache reuse without re-fetching when fresh
+   - Staleness detection (TTL-based, non-hydrated nodes)
+   - Missing/non-existent node handling
+   - Concurrent hydration (same node, different nodes)
+   - Resolve API (single and batch resolution)
+
+2. ✅ Cross-provider edges (8 tests, 1 skipped)
+   - Native → External edge creation and queries
+   - External → Native edge creation and queries
+   - Bidirectional traversal via federated graph
+   - Transitive cross-provider chains (Native → Beads → Native)
+   - Ready query with cross-provider blockers
+   - Status change detection (skipped - requires cache invalidation investigation)
+
+3. ✅ Federated ready query (10 tests)
+   - Basic ready query (unblocked, closed blocker, open blocker)
+   - Cross-provider blockers (open external blocks, closed external unblocks)
+   - Multiple blockers (all native, mixed native+external)
+   - External status mapping (closed, open, in_progress)
+
+4. ✅ Materialization strategies (10 tests)
+   - Lazy strategy (materialize on resolve, explicit flag)
+   - On-demand strategy (explicit request only)
+   - Eager strategy (all access types)
+   - None strategy (never materialize)
+   - Per-provider strategy overrides
+   - Staleness detection (TTL, missing cached_at, stale flag)
+   - URI extraction for strategy lookup
+
+5. ✅ Background sync (16 tests)
+   - Start/stop lifecycle (running state, stop behavior)
+   - Configuration (interval=0 disables, negative interval, multiple starts)
+   - Materialization context (access types, explicit flag)
+   - Strategy handling (lazy, eager, on-demand, none)
+   - Default configuration and partial config merging
+
+**Deliverables:**
+- ✅ `tests/e2e/helpers/beads-helpers.ts` - Beads CLI helpers (isBdAvailable, createBeadsTask, getBeadsTask, updateBeadsStatus)
+- ✅ `tests/e2e/workflows/provider-sync/hydration.e2e.test.ts` - 12 tests
+- ✅ `tests/e2e/workflows/provider-sync/cross-provider-edges.e2e.test.ts` - 8 tests (1 skipped)
+- ✅ `tests/e2e/workflows/provider-sync/federated-ready.e2e.test.ts` - 10 tests
+- ✅ `tests/e2e/workflows/provider-sync/materialization.e2e.test.ts` - 10 tests
+- ✅ `tests/e2e/workflows/provider-sync/background-sync.e2e.test.ts` - 16 tests
+
+**Key Technical Patterns:**
+- Cross-provider queries use `HydratingFederatedGraph.related()` instead of daemon queries
+- Native nodes use `native://` URI prefix and must be added to GraphologyAdapter
+- bd CLI only supports statuses: `open`, `closed`, `blocked`, `in_progress`
+- CLOSED_STATUSES list includes: `closed`, `done`, `resolved`, `completed`, `cancelled`
+
+**Running Provider Sync Tests:**
+```bash
+# Run all provider sync tests (requires bd CLI)
+RUN_FULL_AGENT_TESTS=1 npx vitest run tests/e2e/workflows/provider-sync/
+
+# Tests skip gracefully if bd CLI is not available
+```
+
+---
+
+## Dev Dependencies to Consider
+
+| Package | Purpose | Decision Criteria |
+|---------|---------|-------------------|
+| `execa` | Better child process handling | If spawn tests become complex |
+| `tempy` | Temp directory management | If current approach insufficient |
+| `wait-for-expect` | Async assertion helpers | If timeout handling needed |
+| `msw` | Mock Service Worker | Only if HTTP mocking needed |
+
+**Current recommendation:** Start without additional dependencies, add as needed.
+
+---
+
+## Success Metrics
+
+### Coverage Targets
+
+| Tier | Target | Current |
+|------|--------|---------|
+| Unit | >90% | 926 tests ✅ |
+| Integration | >70% of external interfaces | 127 tests (Phases 1-4) ✅ |
+| E2E | >80% of documented workflows | 124 tests (Phases 5-7) ✅ |
+
+### Performance Baselines
+
+| Operation | Target | Measured |
+|-----------|--------|----------|
+| Unit test suite | <10s | ~3s ✅ |
+| Integration test suite | <2min | ~20s ✅ |
+| E2E test suite | <10min | ~2s (124 tests) ✅ |
+| Create 1000 nodes (JSONL) | <1s | <500ms ✅ |
+| Load 1000 nodes (JSONL) | <500ms | <100ms ✅ |
+| Insert 10k nodes (SQLite) | <5s | ~650ms ✅ |
+| Query 10k nodes (SQLite) | <1s | ~15ms ✅ |
+
+---
+
+## Next Steps
+
+1. ~~**Immediate:** Implement Phase 1 (test infrastructure, helpers, config)~~ ✅ DONE
+2. ~~**Short-term:** Implement Phases 2-3 (storage + daemon integration tests)~~ ✅ DONE
+3. ~~**Medium-term:** Implement Phase 4 (provider + graph integration)~~ ✅ DONE
+4. ~~**Next:** Implement Phase 5 (E2E infrastructure)~~ ✅ DONE
+5. ~~**Next:** Implement Phase 6 (agent workflow E2E tests)~~ ✅ DONE
+6. ~~**Next:** Implement Phase 7 (provider sync E2E tests)~~ ✅ DONE
+
+**All phases complete!** Future work may include:
+- ClaudeTasksProvider integration tests (when accessible outside Claude Code sessions)
+- Additional stress/performance tests for large graphs
+- CI integration with bd CLI installation
+
+The testing strategy prioritizes system-level tests (storage, daemon) first as they:
+- Have no external dependencies (no `bd` CLI needed)
+- Test the foundation that all other features rely on
+- Can be gated with `RUN_SLOW_TESTS` for fast CI cycles
+
+## Progress Summary
+
+| Phase | Status | Tests |
+|-------|--------|-------|
+| Phase 1: Infrastructure | ✅ Complete | 11 helper tests |
+| Phase 2: Storage | ✅ Complete | 33 tests (JSONL + SQLite) |
+| Phase 3: Daemon | ✅ Complete | 40 tests (lifecycle + IPC) |
+| Phase 4: Providers & Graph | ✅ Complete | 43 tests (BeadsProvider + FederatedGraph) |
+| Phase 5: E2E Infrastructure | ✅ Complete | 39 tests (system setup, TestAgent, providers, assertions, fixtures) |
+| Phase 6: Agent Workflows | ✅ Complete | 29 tests (context-driven, multi-agent, feedback-loop) |
+| Phase 7: Provider Sync | ✅ Complete | 56 tests (hydration, cross-provider, federated-ready, materialization, background-sync) |
+
+**Total Tests:** 1177 (926 unit + 127 integration + 124 E2E)
+
+**Note:** Provider sync tests require `bd` CLI and skip gracefully if unavailable. Run with `RUN_FULL_AGENT_TESTS=1`.