cognitive-core 0.1.0 → 0.1.2

package/tests/surfacing/team-skill-library.test.ts

@@ -0,0 +1,444 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  TeamSkillLibrary,
+  createTeamSkillLibrary,
+  type TeamOutcomeFeedback,
+} from '../../src/surfacing/team-skill-library.js';
+import type { TeamExperienceMemory } from '../../src/memory/team-experience.js';
+import { createTeamPlaybook, createRolePlaybook } from '../../src/types/team-playbook.js';
+import type { TeamPlaybook, RolePlaybook } from '../../src/types/team-playbook.js';
+
+function makeSamplePlaybook(overrides?: Partial<TeamPlaybook>): TeamPlaybook {
+  return createTeamPlaybook({
+    name: 'wave-web-team',
+    applicability: {
+      taskTypes: ['feature'],
+      teamSizeRange: { min: 2, max: 4 },
+      complexityLevels: ['moderate'],
+      domains: ['web'],
+      antiPatterns: [],
+    },
+    composition: {
+      topology: 'wave',
+      roles: [
+        { role: 'planner', rationale: 'Plan', capabilities: ['planning'], optional: false, modelTier: 'capable', spawnAs: 'root' },
+        { role: 'executor', rationale: 'Execute', capabilities: ['execution'], optional: false, modelTier: 'balanced', spawnAs: 'companion' },
+      ],
+      spawnRules: { planner: ['executor'] },
+      enforcement: 'permissive',
+    },
+    coordination: {
+      executionModel: 'wave-parallel',
+      channels: [{ name: 'tasks', signals: ['ready'], subscribers: ['executor'], emitters: ['planner'] }],
+      interactionPatterns: [{ name: 'plan-execute', description: 'Planner delegates to executor', roles: ['planner', 'executor'], frequency: 'per-task', correlatedWithSuccess: true }],
+      delegationStrategy: 'planner-driven',
+    },
+    confidence: 0.8,
+    ...overrides,
+  });
+}
+
+function makeSampleRolePlaybook(role: string, overrides?: Partial<RolePlaybook>): RolePlaybook {
+  return createRolePlaybook({
+    name: `effective-${role}`,
+    role,
+    teamContext: {
+      topologies: ['wave'],
+      teamSizeRange: { min: 2, max: 10 },
+      taskTypes: ['feature'],
+      domains: ['web'],
+    },
+    guidance: {
+      responsibilities: ['Execute assigned tasks', 'Report completion'],
+      interactionGuidance: [
+        {
+          withRole: 'planner',
+          interactionType: 'signal',
+          guidance: 'Signal completion immediately',
+          examples: ['Send TASK_DONE signal'],
+          antiPatterns: ['Wait for planner to check'],
+        },
+      ],
+      decisionFrameworks: [
+        { name: 'Escalation', when: 'blocked for >5 min', guidance: 'Signal planner with context' },
+      ],
+      antiPatterns: ['Working beyond scope'],
+    },
+    confidence: 0.7,
+    ...overrides,
+  });
+}
+
+function createMockMemory(options?: {
+  teamPlaybooks?: TeamPlaybook[];
+  rolePlaybooks?: RolePlaybook[];
+}): TeamExperienceMemory {
+  const teamPlaybooks = options?.teamPlaybooks ?? [];
+  const rolePlaybooks = options?.rolePlaybooks ?? [];
+
+  return {
+    getTeamPlaybooks: vi.fn().mockResolvedValue(teamPlaybooks),
+    getRolePlaybooks: vi.fn().mockResolvedValue(rolePlaybooks),
+    findMatchingTeamPlaybooks: vi.fn().mockImplementation(async ({ k }) => {
+      return teamPlaybooks.slice(0, k ?? 5).map((p, i) => ({
+        playbook: p,
+        score: 0.9 - i * 0.1,
+      }));
+    }),
+    findMatchingRolePlaybooks: vi.fn().mockImplementation(async ({ role, k }) => {
+      return rolePlaybooks
+        .filter((p) => p.role === role)
+        .slice(0, k ?? 3)
+        .map((p, i) => ({
+          playbook: p,
+          score: 0.85 - i * 0.1,
+        }));
+    }),
+    storeTeamPlaybook: vi.fn().mockResolvedValue(undefined),
+    storeRolePlaybook: vi.fn().mockResolvedValue(undefined),
+  } as unknown as TeamExperienceMemory;
+}
+
+describe('TeamSkillLibrary', () => {
+  let mockMemory: TeamExperienceMemory;
+
+  beforeEach(() => {
+    mockMemory = createMockMemory();
+  });
+
+  it('should create via factory function', () => {
+    const lib = createTeamSkillLibrary(mockMemory);
+    expect(lib).toBeInstanceOf(TeamSkillLibrary);
+  });
+
+  describe('refreshTiers', () => {
+    it('should promote high-confidence playbooks to core', async () => {
+      const highConfidence = makeSamplePlaybook({
+        confidence: 0.85,
+        evolution: {
+          version: '1.0.0',
+          createdFrom: [],
+          refinements: [],
+          successCount: 5,
+          failureCount: 1,
+        },
+      });
+      mockMemory = createMockMemory({ teamPlaybooks: [highConfidence] });
+      const lib = createTeamSkillLibrary(mockMemory);
+
+      const result = await lib.refreshTiers();
+
+      expect(result.coreCount).toBe(1);
+      expect(result.promoted).toContain(highConfidence.id);
+      expect(lib.getCoreTeamPlaybooks()).toHaveLength(1);
+    });
+
+    it('should not promote low-confidence playbooks', async () => {
+      const lowConfidence = makeSamplePlaybook({
+        confidence: 0.3,
+        evolution: { version: '1.0.0', createdFrom: [], refinements: [], successCount: 1, failureCount: 0 },
+      });
+      mockMemory = createMockMemory({ teamPlaybooks: [lowConfidence] });
+      const lib = createTeamSkillLibrary(mockMemory);
+
+      const result = await lib.refreshTiers();
+
+      expect(result.coreCount).toBe(0);
+    });
+
+    it('should demote playbooks with consecutive failures', async () => {
+      const playbook = makeSamplePlaybook({
+        confidence: 0.85,
+        evolution: { version: '1.0.0', createdFrom: [], refinements: [], successCount: 5, failureCount: 1 },
+      });
+      mockMemory = createMockMemory({ teamPlaybooks: [playbook] });
+      const lib = createTeamSkillLibrary(mockMemory);
+
+      // First promote it
+      await lib.refreshTiers();
+      expect(lib.getCoreTeamPlaybooks()).toHaveLength(1);
+
+      // Record multiple failures
+      for (let i = 0; i < 3; i++) {
+        await lib.recordTeamOutcome({
+          playbookId: playbook.id,
+          success: false,
+          quality: 'poor',
+        });
+      }
+
+      // Refresh should demote
+      const result = await lib.refreshTiers();
+      expect(result.demoted).toContain(playbook.id);
+    });
+  });
+
+  describe('findMatchingTeamPlaybooks', () => {
+    it('should return ranked team playbooks', async () => {
+      const p1 = makeSamplePlaybook({ confidence: 0.8 });
+      const p2 = makeSamplePlaybook({ name: 'flat-web-team', confidence: 0.6 });
+      mockMemory = createMockMemory({ teamPlaybooks: [p1, p2] });
+      const lib = createTeamSkillLibrary(mockMemory);
+
+      const ranked = await lib.findMatchingTeamPlaybooks({ domain: 'web' });
+
+      expect(ranked).toHaveLength(2);
+      expect(ranked[0].rankScore).toBeGreaterThanOrEqual(ranked[1].rankScore);
+      expect(ranked[0].relevanceScore).toBeGreaterThan(0);
+      expect(ranked[0].successRate).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  describe('findRolePlaybooks', () => {
+    it('should return ranked role playbooks', async () => {
+      const plannerPlaybook = makeSampleRolePlaybook('planner');
+      mockMemory = createMockMemory({ rolePlaybooks: [plannerPlaybook] });
+      const lib = createTeamSkillLibrary(mockMemory);
+
+      const ranked = await lib.findRolePlaybooks('planner', { topology: 'wave' });
+
+      expect(ranked).toHaveLength(1);
+      expect(ranked[0].playbook.role).toBe('planner');
+      expect(ranked[0].rankScore).toBeGreaterThan(0);
+    });
+  });
+
+  describe('getSkillsForTeam', () => {
+    it('should return organized team skills', async () => {
+      const teamPlaybook = makeSamplePlaybook({ confidence: 0.85 });
+      const plannerPlaybook = makeSampleRolePlaybook('planner');
+      const executorPlaybook = makeSampleRolePlaybook('executor');
+      mockMemory = createMockMemory({
+        teamPlaybooks: [teamPlaybook],
+        rolePlaybooks: [plannerPlaybook, executorPlaybook],
+      });
+      const lib = createTeamSkillLibrary(mockMemory);
+
+      const skills = await lib.getSkillsForTeam({
+        description: 'Implement auth feature',
+        domain: 'web',
+        roles: ['planner', 'executor'],
+        topology: 'wave',
+      });
+
+      expect(skills.matchedTeamPlaybooks.length).toBeGreaterThanOrEqual(0);
+      expect(skills.rolePlaybooks.get('planner')?.length).toBeGreaterThanOrEqual(1);
+      expect(skills.rolePlaybooks.get('executor')?.length).toBeGreaterThanOrEqual(1);
+      expect(skills.totalTokenEstimate).toBeGreaterThan(0);
+    });
+  });
+
+  describe('formatRoleGuidance', () => {
+    it('should format role playbook as markdown', () => {
+      const lib = createTeamSkillLibrary(mockMemory);
+      const playbook = makeSampleRolePlaybook('executor');
+
+      const formatted = lib.formatRoleGuidance('executor', [playbook]);
+
+      expect(formatted).toContain('## Team Role Guidance: executor');
+      expect(formatted).toContain('effective-executor');
+      expect(formatted).toContain('**Your Role:** executor');
+      expect(formatted).toContain('**Responsibilities:**');
+      expect(formatted).toContain('Execute assigned tasks');
+      expect(formatted).toContain('**Working with planner:**');
+      expect(formatted).toContain('Signal completion immediately');
+      expect(formatted).toContain('**Escalation:**');
+      expect(formatted).toContain('**Avoid:**');
+    });
+
+    it('should return empty string for no playbooks', () => {
+      const lib = createTeamSkillLibrary(mockMemory);
+      expect(lib.formatRoleGuidance('executor', [])).toBe('');
+    });
+  });
+
+  describe('formatTeamPlaybookSummary', () => {
+    it('should format team playbook as markdown', () => {
+      const lib = createTeamSkillLibrary(mockMemory);
+      const playbook = makeSamplePlaybook({
+        evolution: {
+          version: '1.2.0',
+          createdFrom: ['t-1'],
+          refinements: [{ context: 'monorepo', adjustment: 'add coordinator', source: 'failure', addedAt: new Date() }],
+          successCount: 5,
+          failureCount: 1,
+        },
+      });
+
+      const formatted = lib.formatTeamPlaybookSummary([playbook]);
+
+      expect(formatted).toContain('## Team Coordination Patterns');
+      expect(formatted).toContain('wave-web-team');
+      expect(formatted).toContain('**Topology:** wave');
+      expect(formatted).toContain('**Execution Model:** wave-parallel');
+      expect(formatted).toContain('planner');
+      expect(formatted).toContain('executor');
+      expect(formatted).toContain('plan-execute');
+      expect(formatted).toContain('monorepo');
+      expect(formatted).toContain('add coordinator');
+    });
+  });
+
+  describe('recordTeamOutcome', () => {
+    it('should update success count and confidence on successful outcome', async () => {
+      const playbook = makeSamplePlaybook({
+        evolution: { version: '1.0.0', createdFrom: [], refinements: [], successCount: 3, failureCount: 1 },
+      });
+      mockMemory = createMockMemory({ teamPlaybooks: [playbook] });
+      const lib = createTeamSkillLibrary(mockMemory);
+
+      await lib.recordTeamOutcome({
+        playbookId: playbook.id,
+        success: true,
+        quality: 'good',
+        metrics: { coordinationOverhead: 0.2, parallelismRatio: 0.7 },
+      });
+
+      expect(mockMemory.storeTeamPlaybook).toHaveBeenCalledTimes(1);
+      const stored = vi.mocked(mockMemory.storeTeamPlaybook).mock.calls[0][0];
+      expect(stored.evolution.successCount).toBe(4);
+      expect(stored.evolution.failureCount).toBe(1);
+      expect(stored.evolution.lastUsed).toBeDefined();
+      expect(stored.evolution.avgMetrics).toBeDefined();
+    });
+
+    it('should update failure count on failed outcome', async () => {
+      const playbook = makeSamplePlaybook({
+        evolution: { version: '1.0.0', createdFrom: [], refinements: [], successCount: 3, failureCount: 1 },
+      });
+      mockMemory = createMockMemory({ teamPlaybooks: [playbook] });
+      const lib = createTeamSkillLibrary(mockMemory);
+
+      await lib.recordTeamOutcome({
+        playbookId: playbook.id,
+        success: false,
+        quality: 'poor',
+      });
+
+      const stored = vi.mocked(mockMemory.storeTeamPlaybook).mock.calls[0][0];
+      expect(stored.evolution.successCount).toBe(3);
+      expect(stored.evolution.failureCount).toBe(2);
+    });
+
+    it('should recalculate confidence based on track record', async () => {
+      const playbook = makeSamplePlaybook({
+        confidence: 0.8,
+        evolution: { version: '1.0.0', createdFrom: [], refinements: [], successCount: 8, failureCount: 1 },
+      });
+      mockMemory = createMockMemory({ teamPlaybooks: [playbook] });
+      const lib = createTeamSkillLibrary(mockMemory);
+
+      await lib.recordTeamOutcome({
+        playbookId: playbook.id,
+        success: true,
+        quality: 'good',
+      });
+
+      const stored = vi.mocked(mockMemory.storeTeamPlaybook).mock.calls[0][0];
+      // 9 successes / 10 total = 0.9 success rate
+      // Blended with original confidence with high observedWeight
+      expect(stored.confidence).toBeGreaterThan(0.8);
+    });
+
+    it('should accumulate average metrics', async () => {
+      const playbook = makeSamplePlaybook({
+        evolution: {
+          version: '1.0.0', createdFrom: [], refinements: [],
+          successCount: 1, failureCount: 0,
+          avgMetrics: { coordinationOverhead: 0.3, parallelismRatio: 0.5, timeToFirstOutput: 30 },
+        },
+      });
+      mockMemory = createMockMemory({ teamPlaybooks: [playbook] });
+      const lib = createTeamSkillLibrary(mockMemory);
+
+      await lib.recordTeamOutcome({
+        playbookId: playbook.id,
+        success: true,
+        quality: 'good',
+        metrics: { coordinationOverhead: 0.1, parallelismRatio: 0.9, timeToFirstOutput: 20 },
+      });
+
+      const stored = vi.mocked(mockMemory.storeTeamPlaybook).mock.calls[0][0];
+      // Running average: (0.3 * 1 + 0.1) / 2 = 0.2
+      expect(stored.evolution.avgMetrics!.coordinationOverhead).toBe(0.2);
+      // (0.5 * 1 + 0.9) / 2 = 0.7
+      expect(stored.evolution.avgMetrics!.parallelismRatio).toBe(0.7);
+    });
+
+    it('should silently handle non-existent playbook', async () => {
+      const lib = createTeamSkillLibrary(mockMemory);
+
+      // Should not throw
+      await lib.recordTeamOutcome({
+        playbookId: 'non-existent',
+        success: true,
+        quality: 'good',
+      });
+
+      expect(mockMemory.storeTeamPlaybook).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('recordRoleOutcome', () => {
+    it('should update role playbook evolution', async () => {
+      const playbook = makeSampleRolePlaybook('executor', {
+        evolution: { version: '1.0.0', createdFrom: [], refinements: [], successCount: 2, failureCount: 0 },
+      });
+      mockMemory = createMockMemory({ rolePlaybooks: [playbook] });
+      const lib = createTeamSkillLibrary(mockMemory);
+
+      await lib.recordRoleOutcome({
+        playbookId: playbook.id,
+        success: true,
+        quality: 'good',
+      });
+
+      expect(mockMemory.storeRolePlaybook).toHaveBeenCalledTimes(1);
+      const stored = vi.mocked(mockMemory.storeRolePlaybook).mock.calls[0][0];
+      expect(stored.evolution.successCount).toBe(3);
+    });
+  });
+
+  describe('getStats', () => {
+    it('should return library stats', async () => {
+      const lib = createTeamSkillLibrary(mockMemory);
+
+      const stats = lib.getStats();
+
+      expect(stats.coreTeamPlaybookCount).toBe(0);
+      expect(stats.lastRefresh).toBeNull();
+      expect(Object.keys(stats.consecutiveFailures)).toHaveLength(0);
+    });
+  });
+
+  describe('cross-pollination types', () => {
+    it('should support rolePlaybookReferences on TeamPlaybook', () => {
+      const playbook = makeSamplePlaybook({
+        rolePlaybookReferences: [
+          { role: 'planner', suggestedPlaybookIds: ['task-decomp-1', 'architecture-1'] },
+          { role: 'executor', suggestedPlaybookIds: ['slice-impl-1'] },
+        ],
+      });
+
+      expect(playbook.rolePlaybookReferences).toHaveLength(2);
+      expect(playbook.rolePlaybookReferences![0].role).toBe('planner');
+      expect(playbook.rolePlaybookReferences![0].suggestedPlaybookIds).toHaveLength(2);
+    });
+
+    it('should support relatedTaskPlaybooks on RolePlaybook', () => {
+      const playbook = makeSampleRolePlaybook('executor', {
+        relatedTaskPlaybooks: [
+          {
+            playbookId: 'slice-impl-1',
+            playbookName: 'Vertical Slice Implementation',
+            applicableToTask: 'implementing features',
+            rationale: 'Direct application of slice strategy within wave',
+          },
+        ],
+      });
+
+      expect(playbook.relatedTaskPlaybooks).toHaveLength(1);
+      expect(playbook.relatedTaskPlaybooks![0].playbookId).toBe('slice-impl-1');
+    });
+  });
+});

package/tests/types/team-meta.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect } from 'vitest';
+import {
+  createTeamMetaObservation,
+  createTeamMetaStrategy,
+  type TeamMetaObservation,
+  type TeamMetaStrategy,
+} from '../../src/types/team-meta.js';
+
+describe('TeamMetaObservation', () => {
+  it('should create a team meta-observation with all fields', () => {
+    const obs = createTeamMetaObservation({
+      teamTrajectoryId: 'team-traj-001',
+      formation: {
+        playbookUsed: 'wave-parallel-feature',
+        formationMethod: 'playbook',
+        confidence: 0.85,
+        reasoning: 'Task matches wave-parallel pattern',
+      },
+      compositionEffectiveness: {
+        roleUtilization: { planner: 0.9, executor: 0.8, verifier: 0.7 },
+        missingRoles: [],
+        redundantRoles: [],
+        teamSizeAssessment: 'right-sized',
+        topologyAssessment: 'effective',
+      },
+      coordinationEffectiveness: {
+        enforcementAssessment: 'appropriate',
+        channelEffectiveness: 'helpful',
+        bottlenecks: [],
+        coordinationOverhead: 0.22,
+      },
+      outcome: {
+        success: true,
+        quality: 'good',
+        speedupEstimate: 1.5,
+        costEfficiency: 0.8,
+      },
+      lessons: {
+        whatWorked: ['Wave topology allowed parallel execution'],
+        whatFailed: [],
+        formationSuggestions: [],
+        coordinationSuggestions: ['Add direct executor-to-verifier channel'],
+      },
+    });
+
+    expect(obs.id).toBeDefined();
+    expect(obs.teamTrajectoryId).toBe('team-traj-001');
+    expect(obs.formation.playbookUsed).toBe('wave-parallel-feature');
+    expect(obs.formation.formationMethod).toBe('playbook');
+    expect(obs.compositionEffectiveness.teamSizeAssessment).toBe('right-sized');
+    expect(obs.coordinationEffectiveness.coordinationOverhead).toBe(0.22);
+    expect(obs.outcome.speedupEstimate).toBe(1.5);
+    expect(obs.lessons.whatWorked).toHaveLength(1);
+    expect(obs.timestamp).toBeInstanceOf(Date);
+  });
+
+  it('should create with custom id', () => {
+    const obs = createTeamMetaObservation({
+      id: 'tmo-custom-1',
+      teamTrajectoryId: 'tt-1',
+      formation: {
+        formationMethod: 'manual',
+        confidence: 0.5,
+        reasoning: 'Manual formation',
+      },
+      compositionEffectiveness: {
+        roleUtilization: {},
+        missingRoles: ['verifier'],
+        redundantRoles: [],
+        teamSizeAssessment: 'too-small',
+        topologyAssessment: 'neutral',
+      },
+      coordinationEffectiveness: {
+        enforcementAssessment: 'too-loose',
+        channelEffectiveness: 'neutral',
+        bottlenecks: ['orchestrator'],
+        coordinationOverhead: 0.45,
+      },
+      outcome: {
+        success: false,
+        quality: 'poor',
+        speedupEstimate: 0.8,
+        costEfficiency: 0.3,
+      },
+      lessons: {
+        whatWorked: [],
+        whatFailed: ['Single orchestrator became bottleneck'],
+        formationSuggestions: ['Add verifier role'],
+        coordinationSuggestions: ['Use direct peer routes'],
+      },
+    });
+
+    expect(obs.id).toBe('tmo-custom-1');
+    expect(obs.compositionEffectiveness.missingRoles).toContain('verifier');
+    expect(obs.coordinationEffectiveness.bottlenecks).toContain('orchestrator');
+  });
+});
+
+describe('TeamMetaStrategy', () => {
+  it('should create a team meta-strategy with defaults', () => {
+    const strategy = createTeamMetaStrategy({
+      name: 'prefer-wave-for-features',
+      condition: {
+        taskCharacteristics: ['multi-component', 'full-stack'],
+        resourceConstraints: [],
+        domains: ['web', 'fullstack'],
+      },
+      adjustment: {
+        topologyBias: { wave: 0.8, hierarchical: -0.3 },
+        teamSizeAdjustment: 'maintain',
+        roleAdjustments: ['add verifier for complex tasks'],
+        coordinationHints: ['use direct peer routes'],
+        enforcementBias: 'permissive',
+      },
+    });
+
+    expect(strategy.id).toBeDefined();
+    expect(strategy.name).toBe('prefer-wave-for-features');
+    expect(strategy.condition.domains).toContain('web');
+    expect(strategy.adjustment.topologyBias?.wave).toBe(0.8);
+    expect(strategy.adjustment.teamSizeAdjustment).toBe('maintain');
+    expect(strategy.applicationCount).toBe(0);
+    expect(strategy.successRate).toBe(0);
+    expect(strategy.createdAt).toBeInstanceOf(Date);
+    expect(strategy.updatedAt).toBeInstanceOf(Date);
+  });
+
+  it('should create with custom id', () => {
+    const strategy = createTeamMetaStrategy({
+      id: 'tms-001',
+      name: 'test-strategy',
+      condition: {
+        taskCharacteristics: [],
+        resourceConstraints: ['limited budget'],
+        domains: [],
+      },
+      adjustment: {
+        teamSizeAdjustment: 'decrease',
+        roleAdjustments: [],
+        coordinationHints: [],
+      },
+    });
+
+    expect(strategy.id).toBe('tms-001');
+    expect(strategy.adjustment.teamSizeAdjustment).toBe('decrease');
+  });
+});