@holoscript/framework 6.0.3

package/src/__tests__/self-improve.test.ts

@@ -0,0 +1,349 @@
+/**
+ * Tests for FW-1.0 Self-Improvement Module
+ *
+ * FrameworkAbsorber, TestGenerator, PromptOptimizer
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Mock fetch globally
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+
+// Mock callLLM
+vi.mock('../llm/llm-adapter', () => ({
+  callLLM: vi.fn(),
+}));
+
+// Mock fs for TestGenerator
+vi.mock('fs', () => ({
+  readFileSync: vi.fn(() => 'export function add(a: number, b: number): number { return a + b; }'),
+  existsSync: vi.fn(() => true),
+}));
+
+import { FrameworkAbsorber } from '../self-improve/framework-absorber';
+import { TestGenerator } from '../self-improve/test-generator';
+import { PromptOptimizer } from '../self-improve/prompt-optimizer';
+import { callLLM } from '../llm/llm-adapter';
+import { existsSync } from 'fs';
+
+const mockedCallLLM = vi.mocked(callLLM);
+const mockedExistsSync = vi.mocked(existsSync);
+
+// ── FrameworkAbsorber ──
+
+describe('FrameworkAbsorber', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('constructs with default config', () => {
+    const absorber = new FrameworkAbsorber();
+    expect(absorber).toBeInstanceOf(FrameworkAbsorber);
+  });
+
+  it('constructs with custom config', () => {
+    const absorber = new FrameworkAbsorber({
+      absorbUrl: 'https://custom.absorb.net',
+      absorbApiKey: 'test-key',
+      codebasePath: '/tmp/code',
+    });
+    expect(absorber).toBeInstanceOf(FrameworkAbsorber);
+  });
+
+  it('scanSelf falls back to knowledge store when absorb is unreachable', async () => {
+    mockFetch.mockRejectedValueOnce(new Error('ECONNREFUSED'));
+    // Second call for knowledge store query
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        results: [
+          { type: 'gotcha', content: 'Test gotcha', metadata: { domain: 'framework' } },
+        ],
+      }),
+    });
+
+    const absorber = new FrameworkAbsorber({ absorbApiKey: 'test-key', mcpApiKey: 'test-key' });
+    const graph = await absorber.scanSelf();
+
+    expect(graph).toBeDefined();
+    expect(typeof graph.fileCount).toBe('number');
+    expect(typeof graph.edgeCount).toBe('number');
+    expect(Array.isArray(graph.modules)).toBe(true);
+  });
+
+  it('scanSelf returns graph from absorb MCP when reachable', async () => {
+    // Mock the MCP JSON-RPC response from absorb_run_absorb
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        result: {
+          content: [{ type: 'text', text: JSON.stringify({ file_count: 42, edge_count: 100, modules: ['core', 'self-improve'] }) }],
+        },
+      }),
+    });
+
+    const absorber = new FrameworkAbsorber({ absorbApiKey: 'test-key' });
+    const graph = await absorber.scanSelf();
+
+    expect(graph.fileCount).toBe(42);
+    expect(graph.edgeCount).toBe(100);
+    expect(graph.modules).toEqual(['core', 'self-improve']);
+  });
+
+  it('scanSelf returns empty graph when no API key', async () => {
+    // No key, no absorb call
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      json: async () => ({}),
+    });
+
+    const absorber = new FrameworkAbsorber({ absorbApiKey: '', mcpApiKey: '' });
+    const graph = await absorber.scanSelf();
+
+    expect(graph.fileCount).toBe(0);
+    expect(graph.edgeCount).toBe(0);
+  });
+
+  it('findImprovements returns improvement list from knowledge store', async () => {
+    // findImprovements calls runFullScan which calls scanFramework (knowledge store query)
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        results: [
+          { type: 'gotcha', content: 'Missing test coverage for X', metadata: { domain: 'framework', confidence: 0.8 } },
+          { type: 'pattern', content: 'Use dependency injection', metadata: { domain: 'architecture' } },
+        ],
+      }),
+    });
+
+    const absorber = new FrameworkAbsorber({ absorbApiKey: '', mcpApiKey: 'test-key' });
+    const improvements = await absorber.findImprovements();
+
+    expect(Array.isArray(improvements)).toBe(true);
+    // Only gotchas become improvements
+    expect(improvements.length).toBe(1);
+    expect(improvements[0].title).toContain('Missing test coverage');
+    expect(improvements[0].confidence).toBeGreaterThan(0);
+  });
+
+  it('getKnowledge returns empty array before scan', () => {
+    const absorber = new FrameworkAbsorber();
+    expect(absorber.getKnowledge()).toEqual([]);
+  });
+});
+
+// ── TestGenerator ──
+
+describe('TestGenerator', () => {
+  const modelConfig = { provider: 'anthropic' as const, model: 'claude-sonnet-4-20250514' };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockedExistsSync.mockReturnValue(true);
+  });
+
+  it('constructs with config', () => {
+    const gen = new TestGenerator({ model: modelConfig });
+    expect(gen).toBeInstanceOf(TestGenerator);
+  });
+
+  it('generateTests calls LLM and returns test content', async () => {
+    const testOutput = `import { describe, it, expect } from 'vitest';
+import { add } from '../add';
+
+describe('add', () => {
+  it('adds two numbers', () => {
+    expect(add(1, 2)).toBe(3);
+  });
+
+  it('handles negative numbers', () => {
+    expect(add(-1, 1)).toBe(0);
+  });
+});`;
+
+    mockedCallLLM.mockResolvedValueOnce({
+      content: testOutput,
+      model: 'claude-sonnet-4-20250514',
+      provider: 'anthropic',
+      tokensUsed: 500,
+    });
+
+    const gen = new TestGenerator({ model: modelConfig });
+    const result = await gen.generateTests('src/add.ts');
+
+    expect(result.testContent).toContain("describe('add'");
+    expect(result.testCount).toBe(2);
+    expect(result.tokensUsed).toBe(500);
+    expect(mockedCallLLM).toHaveBeenCalledOnce();
+  });
+
+  it('strips markdown fences from LLM output', async () => {
+    mockedCallLLM.mockResolvedValueOnce({
+      content: '```typescript\nit("works", () => {});\n```',
+      model: 'test',
+      provider: 'anthropic',
+    });
+
+    const gen = new TestGenerator({ model: modelConfig });
+    const result = await gen.generateTests('src/foo.ts');
+
+    expect(result.testContent).not.toContain('```');
+    expect(result.testContent).toContain('it("works"');
+  });
+
+  it('throws when source file does not exist', async () => {
+    mockedExistsSync.mockReturnValue(false);
+
+    const gen = new TestGenerator({ model: modelConfig });
+    await expect(gen.generateTests('nonexistent.ts')).rejects.toThrow('Source file not found');
+  });
+
+  it('generateBatch handles multiple files', async () => {
+    mockedCallLLM.mockResolvedValue({
+      content: 'it("test", () => {});',
+      model: 'test',
+      provider: 'anthropic',
+      tokensUsed: 100,
+    });
+
+    const gen = new TestGenerator({ model: modelConfig });
+    const results = await gen.generateBatch(['src/a.ts', 'src/b.ts']);
+
+    expect(results.length).toBe(2);
+    expect(mockedCallLLM).toHaveBeenCalledTimes(2);
+  });
+
+  it('generateBatch skips files that fail', async () => {
+    mockedExistsSync.mockReturnValueOnce(false).mockReturnValueOnce(true);
+    mockedCallLLM.mockResolvedValueOnce({
+      content: 'it("works", () => {});',
+      model: 'test',
+      provider: 'anthropic',
+      tokensUsed: 50,
+    });
+
+    const gen = new TestGenerator({ model: modelConfig });
+    const results = await gen.generateBatch(['nonexistent.ts', 'src/ok.ts']);
+
+    expect(results.length).toBe(1);
+  });
+});
+
+// ── PromptOptimizer ──
+
+describe('PromptOptimizer', () => {
+  const modelConfig = { provider: 'anthropic' as const, model: 'claude-sonnet-4-20250514' };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('constructs with config', () => {
+    const opt = new PromptOptimizer({ model: modelConfig });
+    expect(opt).toBeInstanceOf(PromptOptimizer);
+  });
+
+  it('abTest runs both variants and returns a winner', async () => {
+    // Mock callLLM: 3 runs per variant (6 calls) + 6 judge calls = 12 total
+    let callCount = 0;
+    mockedCallLLM.mockImplementation(async () => {
+      callCount++;
+      // Judge calls return JSON scores
+      if (callCount % 2 === 0) {
+        return {
+          content: JSON.stringify({ relevance: 8, quality: 7, completeness: 9 }),
+          model: 'test',
+          provider: 'anthropic',
+          tokensUsed: 50,
+        };
+      }
+      return {
+        content: 'Test response content',
+        model: 'test',
+        provider: 'anthropic',
+        tokensUsed: 200,
+      };
+    });
+
+    const opt = new PromptOptimizer({ model: modelConfig, runs: 2 });
+    const result = await opt.abTest(
+      'Explain this briefly.',
+      'You are an expert. Explain this in detail.',
+      'What is TypeScript?'
+    );
+
+    expect(result.task).toBe('What is TypeScript?');
+    expect(result.variantA).toBeDefined();
+    expect(result.variantB).toBeDefined();
+    expect(['A', 'B', 'tie']).toContain(result.winner);
+    expect(result.confidence).toBeGreaterThanOrEqual(0);
+    expect(result.confidence).toBeLessThanOrEqual(1);
+    expect(result.totalTokens).toBeGreaterThanOrEqual(0);
+    expect(result.variantA.responses.length).toBe(2);
+    expect(result.variantB.responses.length).toBe(2);
+  });
+
+  it('handles judge failures gracefully (neutral score)', async () => {
+    mockedCallLLM.mockImplementation(async (_config, messages) => {
+      // Judge prompt contains "Score the following"
+      const isJudge = messages.some(m => m.content.includes('Score the following') || m.content.includes('prompt quality evaluator'));
+      if (isJudge) {
+        throw new Error('LLM quota exceeded');
+      }
+      return {
+        content: 'Some response',
+        model: 'test',
+        provider: 'anthropic',
+        tokensUsed: 100,
+      };
+    });
+
+    const opt = new PromptOptimizer({ model: modelConfig, runs: 1 });
+    const result = await opt.abTest('Prompt A', 'Prompt B', 'Test task');
+
+    // Both variants should get neutral scores (5) when judge fails
+    expect(result.variantA.avgScore).toBe(5);
+    expect(result.variantB.avgScore).toBe(5);
+    expect(result.winner).toBe('tie');
+  });
+
+  it('reports correct variant scores', async () => {
+    // Make variant A consistently better than variant B
+    mockedCallLLM.mockImplementation(async (_config, messages) => {
+      const systemMsg = messages.find(m => m.role === 'system');
+      const isJudge = systemMsg?.content.includes('prompt quality evaluator');
+
+      if (isJudge) {
+        // Check if the response being judged is from variant A or B
+        const userMsg = messages.find(m => m.role === 'user');
+        const isVariantA = userMsg?.content.includes('Great response from A');
+        return {
+          content: JSON.stringify({
+            relevance: isVariantA ? 9 : 4,
+            quality: isVariantA ? 9 : 4,
+            completeness: isVariantA ? 9 : 4,
+          }),
+          model: 'test',
+          provider: 'anthropic',
+          tokensUsed: 50,
+        };
+      }
+
+      // Variant A uses system prompt "Prompt A"
+      const isA = systemMsg?.content === 'Prompt A';
+      return {
+        content: isA ? 'Great response from A' : 'Mediocre response from B',
+        model: 'test',
+        provider: 'anthropic',
+        tokensUsed: 100,
+      };
+    });
+
+    const opt = new PromptOptimizer({ model: modelConfig, runs: 2 });
+    const result = await opt.abTest('Prompt A', 'Prompt B', 'Test task');
+
+    expect(result.variantA.avgScore).toBeGreaterThan(result.variantB.avgScore);
+    expect(result.winner).toBe('A');
+    expect(result.confidence).toBeGreaterThan(0);
+  });
+});

package/src/__tests__/service-lifecycle.test.ts

@@ -0,0 +1,237 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  BaseService,
+  ServiceLifecycle,
+  ServiceErrorCode,
+  ServiceError,
+  ServiceManager,
+} from '../protocol/implementations';
+import type { ServiceMetadata, ServiceConfig } from '../protocol/implementations';
+
+// ── Concrete test service ──
+
+class TestService extends BaseService {
+  public initCalled = false;
+  public readyCalled = false;
+  public stopCalled = false;
+  public failOnInit = false;
+
+  constructor(name: string, config?: Partial<ServiceConfig>) {
+    super({ name, version: '1.0.0', description: `Test service: ${name}` }, config);
+  }
+
+  protected override async onInit(): Promise<void> {
+    if (this.failOnInit) throw new Error('init failed');
+    this.initCalled = true;
+  }
+
+  protected override async onReady(): Promise<void> {
+    this.readyCalled = true;
+  }
+
+  protected override async onStop(): Promise<void> {
+    this.stopCalled = true;
+  }
+
+  /** Expose executeWithMetrics for testing */
+  async doWork(shouldFail = false): Promise<string> {
+    return this.executeWithMetrics(async () => {
+      if (shouldFail) throw new Error('work failed');
+      return 'done';
+    });
+  }
+}
+
+// =============================================================================
+// BaseService
+// =============================================================================
+
+describe('BaseService', () => {
+  it('initializes through lifecycle states', async () => {
+    const svc = new TestService('alpha');
+    expect(svc.getMetadata().lifecycle).toBe(ServiceLifecycle.INITIALIZING);
+    expect(svc.isReady()).toBe(false);
+
+    await svc.initialize();
+
+    expect(svc.initCalled).toBe(true);
+    expect(svc.readyCalled).toBe(true);
+    expect(svc.isReady()).toBe(true);
+    expect(svc.getMetadata().lifecycle).toBe(ServiceLifecycle.READY);
+    expect(svc.getMetadata().initializedAt).toBeInstanceOf(Date);
+    expect(svc.getMetadata().readyAt).toBeInstanceOf(Date);
+  });
+
+  it('stops cleanly', async () => {
+    const svc = new TestService('beta');
+    await svc.initialize();
+    await svc.stop();
+
+    expect(svc.stopCalled).toBe(true);
+    expect(svc.isReady()).toBe(false);
+    expect(svc.getMetadata().lifecycle).toBe(ServiceLifecycle.STOPPED);
+  });
+
+  it('stop is idempotent', async () => {
+    const svc = new TestService('gamma');
+    await svc.initialize();
+    await svc.stop();
+    await svc.stop(); // second call should be a no-op
+    expect(svc.getMetadata().lifecycle).toBe(ServiceLifecycle.STOPPED);
+  });
+
+  it('records request metrics via executeWithMetrics', async () => {
+    const svc = new TestService('delta');
+    await svc.initialize();
+    const result = await svc.doWork();
+
+    expect(result).toBe('done');
+    expect(svc.getMetrics().requestCount).toBe(1);
+    expect(svc.getMetrics().errorCount).toBe(0);
+    expect(svc.getMetrics().lastRequestAt).toBeInstanceOf(Date);
+  });
+
+  it('records error metrics on failure', async () => {
+    const svc = new TestService('epsilon');
+    await svc.initialize();
+
+    await expect(svc.doWork(true)).rejects.toThrow('work failed');
+    expect(svc.getMetrics().errorCount).toBe(1);
+    expect(svc.getMetrics().lastErrorAt).toBeInstanceOf(Date);
+  });
+
+  it('uses default config values', () => {
+    const svc = new TestService('zeta');
+    const meta = svc.getMetadata();
+    expect(meta.name).toBe('zeta');
+    expect(meta.version).toBe('1.0.0');
+  });
+
+  it('merges custom config', () => {
+    const svc = new TestService('eta', { timeout: 5000, retries: 1 });
+    // Config is internal but we verify the service constructs without error
+    expect(svc.getMetadata().name).toBe('eta');
+  });
+});
+
+// =============================================================================
+// ServiceLifecycle enum
+// =============================================================================
+
+describe('ServiceLifecycle', () => {
+  it('has all expected states', () => {
+    expect(ServiceLifecycle.INITIALIZING).toBe('initializing');
+    expect(ServiceLifecycle.READY).toBe('ready');
+    expect(ServiceLifecycle.DEGRADED).toBe('degraded');
+    expect(ServiceLifecycle.STOPPING).toBe('stopping');
+    expect(ServiceLifecycle.STOPPED).toBe('stopped');
+    expect(ServiceLifecycle.ERROR).toBe('error');
+  });
+});
+
+// =============================================================================
+// ServiceError
+// =============================================================================
+
+describe('ServiceError', () => {
+  it('creates with code and message', () => {
+    const err = new ServiceError(ServiceErrorCode.NOT_FOUND, 'Resource missing', 404);
+    expect(err.code).toBe(ServiceErrorCode.NOT_FOUND);
+    expect(err.message).toBe('Resource missing');
+    expect(err.statusCode).toBe(404);
+    expect(err.name).toBe('ServiceError');
+  });
+
+  it('defaults to status 500', () => {
+    const err = new ServiceError(ServiceErrorCode.INTERNAL_ERROR, 'boom');
+    expect(err.statusCode).toBe(500);
+  });
+
+  it('carries optional details', () => {
+    const err = new ServiceError(ServiceErrorCode.VALIDATION_ERROR, 'bad input', 400, { field: 'name' });
+    expect(err.details).toEqual({ field: 'name' });
+  });
+});
+
+// =============================================================================
+// ServiceManager
+// =============================================================================
+
+describe('ServiceManager', () => {
+  it('starts and stops services in correct order', async () => {
+    const order: string[] = [];
+    class OrderedService extends BaseService {
+      constructor(name: string) {
+        super({ name, version: '1.0.0', description: name });
+      }
+      protected override async onInit() { order.push(`init:${this.getMetadata().name}`); }
+      protected override async onStop() { order.push(`stop:${this.getMetadata().name}`); }
+    }
+
+    const mgr = new ServiceManager();
+    mgr.register(new OrderedService('db'));
+    mgr.register(new OrderedService('cache'));
+    mgr.register(new OrderedService('api'));
+
+    await mgr.startAll();
+    expect(order).toEqual(['init:db', 'init:cache', 'init:api']);
+
+    order.length = 0;
+    await mgr.stopAll();
+    // Services stop in reverse order
+    expect(order).toEqual(['stop:api', 'stop:cache', 'stop:db']);
+  });
+
+  it('reports aggregate health', async () => {
+    const mgr = new ServiceManager();
+    const svcA = new TestService('a');
+    const svcB = new TestService('b');
+    mgr.register(svcA);
+    mgr.register(svcB);
+
+    // Before starting
+    let h = mgr.health();
+    expect(h.totalServices).toBe(2);
+    expect(h.readyCount).toBe(0);
+    expect(h.allReady).toBe(false);
+
+    await mgr.startAll();
+    h = mgr.health();
+    expect(h.readyCount).toBe(2);
+    expect(h.allReady).toBe(true);
+    expect(h.services).toHaveLength(2);
+    expect(h.services[0].name).toBe('a');
+    expect(h.services[0].ready).toBe(true);
+  });
+
+  it('tracks size', () => {
+    const mgr = new ServiceManager();
+    expect(mgr.size).toBe(0);
+    mgr.register(new TestService('x'));
+    expect(mgr.size).toBe(1);
+  });
+
+  it('prevents registration after startAll', async () => {
+    const mgr = new ServiceManager();
+    mgr.register(new TestService('first'));
+    await mgr.startAll();
+    expect(() => mgr.register(new TestService('late'))).toThrow('Cannot register');
+  });
+
+  it('handles empty manager', async () => {
+    const mgr = new ServiceManager();
+    await mgr.startAll();
+    await mgr.stopAll();
+    const h = mgr.health();
+    expect(h.totalServices).toBe(0);
+    expect(h.allReady).toBe(false);
+  });
+
+  it('propagates init errors', async () => {
+    const mgr = new ServiceManager();
+    const failing = new TestService('broken');
+    failing.failOnInit = true;
+    mgr.register(failing);
+    await expect(mgr.startAll()).rejects.toThrow('init failed');
+  });
+});

package/src/__tests__/skill-router.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect } from 'vitest';
+import { SkillRouter } from '../skill-router';
+import type { AgentConfig, TaskDef } from '../types';
+
+function makeAgent(overrides: Partial<AgentConfig> & { name: string }): AgentConfig {
+  return {
+    role: 'coder',
+    model: { provider: 'anthropic', model: 'claude-sonnet-4' },
+    capabilities: ['code-generation'],
+    claimFilter: { roles: ['coder'], maxPriority: 8 },
+    ...overrides,
+  };
+}
+
+function makeTask(overrides: Partial<TaskDef> = {}): TaskDef {
+  return {
+    id: 'task-1',
+    title: 'Fix the parser bug',
+    description: 'The parser fails on nested objects',
+    status: 'open',
+    priority: 3,
+    createdAt: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+describe('SkillRouter', () => {
+  const router = new SkillRouter();
+
+  const coder = makeAgent({
+    name: 'Coder',
+    capabilities: ['code-generation', 'parser', 'typescript'],
+    claimFilter: { roles: ['coder'], maxPriority: 8 },
+  });
+
+  const reviewer = makeAgent({
+    name: 'Reviewer',
+    role: 'reviewer',
+    capabilities: ['code-review', 'security-audit'],
+    claimFilter: { roles: ['reviewer', 'tester'], maxPriority: 5 },
+  });
+
+  const researcher = makeAgent({
+    name: 'Researcher',
+    role: 'researcher',
+    capabilities: ['research', 'documentation'],
+    claimFilter: { roles: ['researcher'], maxPriority: 10 },
+  });
+
+  const agents = [coder, reviewer, researcher];
+
+  it('routes to best-fit agent by capability match', () => {
+    const task = makeTask({ title: 'Fix the parser bug in typescript' });
+    const result = router.route(task, agents);
+    expect(result.agent?.name).toBe('Coder');
+    expect(result.score).toBeGreaterThan(0);
+  });
+
+  it('returns null when no agents available', () => {
+    const task = makeTask();
+    const result = router.route(task, []);
+    expect(result.agent).toBeNull();
+    expect(result.reason).toContain('No agents');
+  });
+
+  it('filters by priority alignment', () => {
+    const task = makeTask({ priority: 7 });
+    // Reviewer has maxPriority 5, so should be filtered out
+    const result = router.route(task, agents);
+    expect(result.candidates.find(c => c.agent.name === 'Reviewer')).toBeUndefined();
+  });
+
+  it('scores role match bonus', () => {
+    const task = makeTask({
+      title: 'Review the authentication module',
+      role: 'reviewer',
+    });
+    const result = router.route(task, agents);
+    const reviewerCandidate = result.candidates.find(c => c.agent.name === 'Reviewer');
+    expect(reviewerCandidate?.roleMatch).toBe(true);
+  });
+
+  it('respects required capabilities filter', () => {
+    const task = makeTask({ title: 'Security audit of payment flow' });
+    const result = router.route(task, agents, {
+      requiredCapabilities: ['security-audit'],
+    });
+    // Only reviewer has security-audit
+    expect(result.candidates).toHaveLength(1);
+    expect(result.candidates[0].agent.name).toBe('Reviewer');
+  });
+
+  it('applies minimum score threshold', () => {
+    const task = makeTask({ title: 'Something completely unrelated' });
+    const result = router.route(task, agents, { minScore: 100 });
+    expect(result.agent).toBeNull();
+    expect(result.reason).toContain('below minimum threshold');
+  });
+
+  it('routeMultiple returns top N candidates', () => {
+    const task = makeTask({ title: 'Fix parser and review typescript code' });
+    const result = router.routeMultiple(task, agents, 2);
+    expect(result.candidates.length).toBeLessThanOrEqual(2);
+  });
+
+  it('sorts candidates by score descending', () => {
+    const task = makeTask({ title: 'Fix the parser bug in typescript' });
+    const result = router.route(task, agents);
+    for (let i = 1; i < result.candidates.length; i++) {
+      expect(result.candidates[i - 1].score).toBeGreaterThanOrEqual(result.candidates[i].score);
+    }
+  });
+
+  it('tracks matched capabilities in result', () => {
+    const task = makeTask({ title: 'Fix the parser bug in typescript' });
+    const result = router.route(task, agents);
+    const coderCandidate = result.candidates.find(c => c.agent.name === 'Coder');
+    expect(coderCandidate?.matchedCapabilities).toContain('parser');
+    expect(coderCandidate?.matchedCapabilities).toContain('typescript');
+  });
+});