cognitive-core 0.0.2 → 0.1.2

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

@@ -0,0 +1,292 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { SkillLibrary, createSkillLibrary } from '../../src/surfacing/skill-library.js';
+import { PlaybookLibrary, createPlaybookLibrary } from '../../src/memory/playbook.js';
+import type { Playbook } from '../../src/types/playbook.js';
+import type { Task } from '../../src/types/task.js';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+describe('SkillLibrary', () => {
+  let tempDir: string;
+  let playbooks: PlaybookLibrary;
+  let skillLibrary: SkillLibrary;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'atlas-test-'));
+    playbooks = createPlaybookLibrary(tempDir);
+    await playbooks.init();
+    skillLibrary = createSkillLibrary(playbooks, {
+      promotion: {
+        minConfidence: 0.85,
+        minSuccessCount: 3,
+        minSuccessRate: 0.8,
+      },
+      limits: {
+        maxCoreSkills: 5,
+        maxDomainSkills: 3,
+        maxContextualPlaybooks: 2,
+      },
+    });
+  });
+
+  afterEach(async () => {
+    await playbooks.close();
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  function createSamplePlaybook(overrides?: Partial<Playbook>): Playbook {
+    return {
+      id: `playbook-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+      name: 'sample-playbook',
+      applicability: {
+        situations: ['General coding task'],
+        triggers: [],
+        antiPatterns: [],
+        domains: ['code'],
+      },
+      guidance: {
+        strategy: 'Follow best practices',
+        tactics: ['Read code', 'Understand context', 'Make changes'],
+      },
+      verification: {
+        successIndicators: ['Tests pass'],
+        failureIndicators: ['Tests fail'],
+      },
+      evolution: {
+        version: '1.0.0',
+        createdFrom: [],
+        failures: [],
+        refinements: [],
+        successCount: 0,
+        failureCount: 0,
+      },
+      confidence: 0.5,
+      complexity: 'moderate',
+      estimatedEffort: 3,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      ...overrides,
+    };
+  }
+
+  function createSampleTask(overrides?: Partial<Task>): Task {
+    return {
+      id: `task-${Date.now()}`,
+      description: 'Fix the bug in the code',
+      domain: 'code',
+      context: {},
+      metadata: {},
+      createdAt: new Date(),
+      ...overrides,
+    };
+  }
+
+  describe('refreshTiers', () => {
+    it('should promote high-confidence playbooks to core', async () => {
+      // Create a playbook that meets promotion criteria
+      const coreCandidate = createSamplePlaybook({
+        name: 'core-skill',
+        confidence: 0.9,
+        evolution: {
+          version: '1.0.0',
+          createdFrom: [],
+          failures: [],
+          refinements: [],
+          successCount: 10,
+          failureCount: 1,
+        },
+      });
+      await playbooks.add(coreCandidate);
+
+      // Create a low-confidence playbook
+      const lowConf = createSamplePlaybook({
+        name: 'low-conf',
+        confidence: 0.3,
+      });
+      await playbooks.add(lowConf);
+
+      const result = await skillLibrary.refreshTiers();
+
+      expect(result.promoted).toContain(coreCandidate.id);
+      expect(result.coreCount).toBeGreaterThanOrEqual(1);
+    });
+
+    it('should respect maxCoreSkills limit', async () => {
+      // Add more than maxCoreSkills (5) high-confidence playbooks
+      for (let i = 0; i < 7; i++) {
+        await playbooks.add(createSamplePlaybook({
+          name: `core-${i}`,
+          confidence: 0.9 + (i * 0.01),
+          evolution: {
+            version: '1.0.0',
+            createdFrom: [],
+            failures: [],
+            refinements: [],
+            successCount: 10,
+            failureCount: 0,
+          },
+        }));
+      }
+
+      const result = await skillLibrary.refreshTiers();
+
+      expect(result.coreCount).toBeLessThanOrEqual(5);
+    });
+  });
+
+  describe('getSkillsForAgent', () => {
+    it('should return skills for a task', async () => {
+      // Add a high-confidence playbook
+      await playbooks.add(createSamplePlaybook({
+        name: 'core-skill',
+        confidence: 0.9,
+        evolution: {
+          version: '1.0.0',
+          createdFrom: [],
+          failures: [],
+          refinements: [],
+          successCount: 10,
+          failureCount: 1,
+        },
+      }));
+
+      // Add a domain-specific playbook
+      await playbooks.add(createSamplePlaybook({
+        name: 'typescript-skill',
+        confidence: 0.7,
+        applicability: {
+          situations: ['TypeScript debugging'],
+          triggers: ['TS2322'],
+          antiPatterns: [],
+          domains: ['typescript'],
+        },
+      }));
+
+      await skillLibrary.refreshTiers();
+
+      const task = createSampleTask({
+        description: 'Fix TypeScript type error',
+        domain: 'typescript',
+      });
+
+      const skills = await skillLibrary.getSkillsForAgent(task);
+
+      expect(skills).toBeDefined();
+      expect(skills.totalTokenEstimate).toBeGreaterThan(0);
+    });
+
+    it('should respect includeCore option', async () => {
+      await playbooks.add(createSamplePlaybook({
+        name: 'core-skill',
+        confidence: 0.95,
+        evolution: {
+          version: '1.0.0',
+          createdFrom: [],
+          failures: [],
+          refinements: [],
+          successCount: 10,
+          failureCount: 0,
+        },
+      }));
+
+      await skillLibrary.refreshTiers();
+
+      const task = createSampleTask();
+
+      const withCore = await skillLibrary.getSkillsForAgent(task, { includeCore: true });
+      const withoutCore = await skillLibrary.getSkillsForAgent(task, { includeCore: false });
+
+      expect(withCore.core.length).toBeGreaterThanOrEqual(withoutCore.core.length);
+    });
+  });
+
+  describe('formatForSystemPrompt', () => {
+    it('should format skills as markdown', async () => {
+      await playbooks.add(createSamplePlaybook({
+        name: 'test-skill',
+        confidence: 0.9,
+        guidance: {
+          strategy: 'Test strategy',
+          tactics: ['Tactic 1', 'Tactic 2'],
+        },
+        evolution: {
+          version: '1.0.0',
+          createdFrom: [],
+          failures: [],
+          refinements: [],
+          successCount: 10,
+          failureCount: 0,
+        },
+      }));
+
+      await skillLibrary.refreshTiers();
+
+      const skills = await skillLibrary.getSkillsForAgent(createSampleTask());
+      const formatted = skillLibrary.formatForSystemPrompt(skills);
+
+      expect(formatted).toContain('Skills');
+      expect(typeof formatted).toBe('string');
+    });
+  });
+
+  describe('recordOutcome', () => {
+    it('should record playbook usage outcome', async () => {
+      const playbook = createSamplePlaybook({ name: 'tracked-playbook' });
+      await playbooks.add(playbook);
+
+      await skillLibrary.recordOutcome(playbook.id, 'traj-1', true);
+      await skillLibrary.recordOutcome(playbook.id, 'traj-2', true);
+      await skillLibrary.recordOutcome(playbook.id, 'traj-3', false);
+
+      const updated = await playbooks.get(playbook.id);
+      expect(updated?.evolution.successCount).toBe(2);
+      expect(updated?.evolution.failureCount).toBe(1);
+    });
+  });
+
+  describe('getPromotionCandidates and getDemotionCandidates', () => {
+    it('should return playbooks eligible for promotion', async () => {
+      // High performer not yet promoted
+      await playbooks.add(createSamplePlaybook({
+        name: 'promotion-candidate',
+        confidence: 0.86,
+        evolution: {
+          version: '1.0.0',
+          createdFrom: [],
+          failures: [],
+          refinements: [],
+          successCount: 5,
+          failureCount: 0,
+        },
+      }));
+
+      const candidates = await skillLibrary.getPromotionCandidates();
+      expect(candidates.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  describe('getStats', () => {
+    it('should return library statistics', async () => {
+      await playbooks.add(createSamplePlaybook({
+        name: 'core-1',
+        confidence: 0.95,
+        evolution: {
+          version: '1.0.0',
+          createdFrom: [],
+          failures: [],
+          refinements: [],
+          successCount: 10,
+          failureCount: 0,
+        },
+      }));
+
+      await skillLibrary.refreshTiers();
+
+      const stats = skillLibrary.getStats();
+      expect(stats).toHaveProperty('coreSkillCount');
+      expect(stats).toHaveProperty('domainSkillCounts');
+      expect(typeof stats.coreSkillCount).toBe('number');
+    });
+  });
+});

package/tests/surfacing/skill-publisher.test.ts

@@ -0,0 +1,398 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { convertPlaybookToSkill, SkillPublisher } from '../../src/surfacing/skill-publisher.js';
+import { MemoryStorageAdapter } from 'skill-tree';
+import type { Skill, StorageAdapter } from 'skill-tree';
+import type { Playbook } from '../../src/types/playbook.js';
+
+describe('SkillPublisher', () => {
+  let storage: StorageAdapter;
+
+  beforeEach(async () => {
+    storage = new MemoryStorageAdapter();
+    await storage.initialize();
+  });
+
+  function createSamplePlaybook(overrides?: Partial<Playbook>): Playbook {
+    const now = new Date('2025-06-01T12:00:00Z');
+    return {
+      id: `playbook-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+      name: 'fix-ts-import',
+      applicability: {
+        situations: ['TypeScript import fails with TS2307'],
+        triggers: ['TS2307', 'Cannot find module'],
+        antiPatterns: ['Module genuinely does not exist'],
+        domains: ['typescript', 'nodejs'],
+      },
+      guidance: {
+        strategy: 'Add .js extension to ES module imports',
+        tactics: [
+          'Check for imports without file extensions',
+          'Add .js extension to relative imports',
+        ],
+        steps: [
+          'Find the failing import',
+          'Add .js extension',
+          'Verify with tsc --noEmit',
+        ],
+        codeExample: 'import { helper } from "./utils.js";',
+      },
+      verification: {
+        successIndicators: ['Build passes', 'No TS2307 errors'],
+        failureIndicators: ['Same error persists'],
+        rollbackStrategy: 'Remove the .js extension',
+      },
+      evolution: {
+        version: '1.2.0',
+        createdFrom: ['session-abc'],
+        failures: [],
+        refinements: [
+          { context: 'monorepo', addition: 'Check workspace exports', source: 'failure', addedAt: now },
+        ],
+        successCount: 8,
+        failureCount: 2,
+        lastUsed: now,
+      },
+      confidence: 0.85,
+      complexity: 'simple',
+      estimatedEffort: 2,
+      createdAt: now,
+      updatedAt: now,
+      ...overrides,
+    };
+  }
+
+  describe('convertPlaybookToSkill', () => {
+    it('should produce a valid Skill with correct identity fields', () => {
+      const playbook = createSamplePlaybook({ id: 'pb-1', name: 'my-skill' });
+      const skill = convertPlaybookToSkill(playbook);
+
+      expect(skill.id).toBe('pb-1');
+      expect(skill.name).toBe('my-skill');
+      expect(skill.version).toBe('1.2.0');
+      expect(skill.author).toBe('cognitive-core');
+      expect(skill.status).toBe('active');
+    });
+
+    it('should map situations to problem and description', () => {
+      const playbook = createSamplePlaybook();
+      const skill = convertPlaybookToSkill(playbook);
+
+      expect(skill.description).toBe('TypeScript import fails with TS2307');
+      expect(skill.problem).toContain('TypeScript import fails with TS2307');
+    });
+
+    it('should build solution from strategy, tactics, and steps', () => {
+      const playbook = createSamplePlaybook();
+      const skill = convertPlaybookToSkill(playbook);
+
+      expect(skill.solution).toContain('Add .js extension to ES module imports');
+      expect(skill.solution).toContain('Tactics:');
+      expect(skill.solution).toContain('Check for imports without file extensions');
+      expect(skill.solution).toContain('Steps:');
+      expect(skill.solution).toContain('Verify with tsc --noEmit');
+    });
+
+    it('should map verification and notes correctly', () => {
+      const playbook = createSamplePlaybook();
+      const skill = convertPlaybookToSkill(playbook);
+
+      expect(skill.verification).toContain('Build passes');
+      expect(skill.notes).toContain('Do NOT use when:');
+      expect(skill.notes).toContain('Watch for:');
+      expect(skill.notes).toContain('Refinements:');
+      expect(skill.notes).toContain('Rollback:');
+    });
+
+    it('should compute metrics from evolution data', () => {
+      const playbook = createSamplePlaybook();
+      const skill = convertPlaybookToSkill(playbook);
+
+      expect(skill.metrics.usageCount).toBe(10); // 8 + 2
+      expect(skill.metrics.successRate).toBe(0.8); // 8/10
+      expect(skill.metrics.averageConfidence).toBe(0.85);
+      expect(skill.metrics.lastUsed).toBeDefined();
+    });
+
+    it('should create trigger conditions with correct types', () => {
+      const playbook = createSamplePlaybook();
+      const skill = convertPlaybookToSkill(playbook);
+
+      const contextTriggers = skill.triggerConditions.filter(t => t.type === 'context');
+      expect(contextTriggers.length).toBe(1);
+      expect(contextTriggers[0].value).toContain('TS2307');
+
+      const errorTriggers = skill.triggerConditions.filter(t => t.type === 'error');
+      expect(errorTriggers.some(t => t.value === 'TS2307')).toBe(true);
+
+      const keywordTriggers = skill.triggerConditions.filter(t => t.type === 'keyword');
+      expect(keywordTriggers.some(t => t.value === 'Cannot find module')).toBe(true);
+    });
+
+    it('should detect pattern-type triggers', () => {
+      const playbook = createSamplePlaybook({
+        applicability: {
+          situations: [],
+          triggers: ['*.config.ts', '/src/**/*.tsx'],
+          antiPatterns: [],
+          domains: [],
+        },
+      });
+      const skill = convertPlaybookToSkill(playbook);
+
+      const patternTriggers = skill.triggerConditions.filter(t => t.type === 'pattern');
+      expect(patternTriggers.length).toBe(2);
+    });
+
+    it('should map code example to examples array', () => {
+      const playbook = createSamplePlaybook();
+      const skill = convertPlaybookToSkill(playbook);
+
+      expect(skill.examples.length).toBe(1);
+      expect(skill.examples[0].after).toContain('utils.js');
+    });
+
+    it('should produce empty examples when no codeExample', () => {
+      const playbook = createSamplePlaybook();
+      playbook.guidance.codeExample = undefined;
+      const skill = convertPlaybookToSkill(playbook);
+
+      expect(skill.examples.length).toBe(0);
+    });
+
+    it('should set serving metadata with token estimate', () => {
+      const playbook = createSamplePlaybook();
+      const skill = convertPlaybookToSkill(playbook);
+
+      expect(skill.serving).toBeDefined();
+      expect(skill.serving!.tokenEstimate).toBeGreaterThan(0);
+      expect(skill.serving!.summary).toBeDefined();
+    });
+
+    it('should truncate long descriptions in serving summary', () => {
+      const playbook = createSamplePlaybook({
+        applicability: {
+          situations: ['A'.repeat(200)],
+          triggers: [],
+          antiPatterns: [],
+          domains: [],
+        },
+      });
+      const skill = convertPlaybookToSkill(playbook);
+
+      expect(skill.serving!.summary!.length).toBeLessThanOrEqual(150);
+      expect(skill.serving!.summary!).toMatch(/\.\.\.$/);
+    });
+
+    it('should handle minimal playbook with empty arrays', () => {
+      const playbook = createSamplePlaybook({
+        applicability: { situations: [], triggers: [], antiPatterns: [], domains: [] },
+        guidance: { strategy: 'simple fix', tactics: [] },
+        verification: { successIndicators: [], failureIndicators: [] },
+        evolution: {
+          version: '1.0.0', createdFrom: [], failures: [], refinements: [],
+          successCount: 0, failureCount: 0,
+        },
+      });
+      const skill = convertPlaybookToSkill(playbook);
+
+      expect(skill.problem).toBe('');
+      expect(skill.triggerConditions.length).toBe(0);
+      expect(skill.tags.length).toBe(0);
+      expect(skill.notes).toBeUndefined();
+      expect(skill.verification).toContain('Verify the approach worked');
+    });
+
+    it('should be type-compatible with skill-tree Skill', () => {
+      const playbook = createSamplePlaybook();
+      // This assignment verifies compile-time type compatibility
+      const skill: Skill = convertPlaybookToSkill(playbook);
+      expect(skill).toBeDefined();
+    });
+  });
+
+  describe('publish operations', () => {
+    it('should publish a playbook as a new skill', async () => {
+      const publisher = new SkillPublisher(storage);
+      const playbook = createSamplePlaybook({ id: 'pub-1' });
+
+      const result = await publisher.publishPlaybook(playbook);
+
+      expect(result.published).toBe(true);
+      expect(result.skillId).toBe('pub-1');
+      expect(result.version).toBe('1.2.0');
+      expect(result.isUpdate).toBe(false);
+    });
+
+    it('should store the skill in the StorageAdapter', async () => {
+      const publisher = new SkillPublisher(storage);
+      const playbook = createSamplePlaybook({ id: 'store-1' });
+
+      await publisher.publishPlaybook(playbook);
+
+      const skill = await storage.getSkill('store-1');
+      expect(skill).not.toBeNull();
+      expect(skill!.name).toBe('fix-ts-import');
+      expect(skill!.status).toBe('active');
+    });
+
+    it('should mark republish as an update', async () => {
+      const publisher = new SkillPublisher(storage);
+      const playbook = createSamplePlaybook({ id: 'update-1' });
+
+      const first = await publisher.publishPlaybook(playbook);
+      expect(first.isUpdate).toBe(false);
+
+      playbook.evolution.version = '2.0.0';
+      playbook.guidance.strategy = 'Updated approach';
+
+      const second = await publisher.publishPlaybook(playbook);
+      expect(second.published).toBe(true);
+      expect(second.isUpdate).toBe(true);
+      expect(second.version).toBe('2.0.0');
+
+      const skill = await storage.getSkill('update-1');
+      expect(skill!.version).toBe('2.0.0');
+      expect(skill!.solution).toContain('Updated approach');
+    });
+
+    it('should track published IDs', async () => {
+      const publisher = new SkillPublisher(storage);
+
+      expect(publisher.isPublished('pub-1')).toBe(false);
+      expect(publisher.getPublishedCount()).toBe(0);
+
+      await publisher.publishPlaybook(createSamplePlaybook({ id: 'pub-1' }));
+
+      expect(publisher.isPublished('pub-1')).toBe(true);
+      expect(publisher.getPublishedCount()).toBe(1);
+    });
+
+    it('should publish multiple playbooks', async () => {
+      const publisher = new SkillPublisher(storage);
+
+      const results = await publisher.publishPlaybooks([
+        createSamplePlaybook({ id: 'multi-1' }),
+        createSamplePlaybook({ id: 'multi-2' }),
+        createSamplePlaybook({ id: 'multi-3' }),
+      ]);
+
+      expect(results.length).toBe(3);
+      expect(results.every(r => r.published)).toBe(true);
+      expect(publisher.getPublishedCount()).toBe(3);
+
+      const all = await storage.listSkills();
+      expect(all.length).toBe(3);
+    });
+  });
+
+  describe('deprecate operations', () => {
+    it('should deprecate an existing skill', async () => {
+      const publisher = new SkillPublisher(storage);
+      await publisher.publishPlaybook(createSamplePlaybook({ id: 'dep-1' }));
+
+      const result = await publisher.deprecateSkill('dep-1', 'Low performance');
+
+      expect(result.deprecated).toBe(true);
+      expect(result.skillId).toBe('dep-1');
+      expect(publisher.isPublished('dep-1')).toBe(false);
+
+      const skill = await storage.getSkill('dep-1');
+      expect(skill!.status).toBe('deprecated');
+      expect(skill!.notes).toContain('Deprecated: Low performance');
+    });
+
+    it('should return error for non-existent skill', async () => {
+      const publisher = new SkillPublisher(storage);
+
+      const result = await publisher.deprecateSkill('nonexistent', 'reason');
+
+      expect(result.deprecated).toBe(false);
+      expect(result.error).toContain('not found');
+    });
+
+    it('should preserve existing notes when deprecating', async () => {
+      const publisher = new SkillPublisher(storage);
+      await publisher.publishPlaybook(createSamplePlaybook({ id: 'notes-1' }));
+
+      const before = await storage.getSkill('notes-1');
+      expect(before!.notes).toContain('Do NOT use when:');
+
+      await publisher.deprecateSkill('notes-1', 'Superseded');
+
+      const after = await storage.getSkill('notes-1');
+      expect(after!.notes).toContain('Do NOT use when:');
+      expect(after!.notes).toContain('Deprecated: Superseded');
+    });
+  });
+
+  describe('end-to-end lifecycle', () => {
+    it('should support full publish → list → filter → deprecate workflow', async () => {
+      const publisher = new SkillPublisher(storage);
+
+      // Publish several skills
+      await publisher.publishPlaybook(createSamplePlaybook({
+        id: 'ts-fix',
+        name: 'ts-fix',
+        applicability: {
+          situations: ['TS error'], triggers: [], antiPatterns: [], domains: ['typescript'],
+        },
+      }));
+      await publisher.publishPlaybook(createSamplePlaybook({
+        id: 'react-fix',
+        name: 'react-fix',
+        applicability: {
+          situations: ['React error'], triggers: [], antiPatterns: [], domains: ['react'],
+        },
+      }));
+      await publisher.publishPlaybook(createSamplePlaybook({
+        id: 'node-fix',
+        name: 'node-fix',
+        applicability: {
+          situations: ['Node error'], triggers: [], antiPatterns: [], domains: ['nodejs'],
+        },
+      }));
+
+      // List all
+      const all = await storage.listSkills();
+      expect(all.length).toBe(3);
+
+      // Filter by tag
+      const tsSkills = await storage.listSkills({ tags: ['typescript'] });
+      expect(tsSkills.length).toBe(1);
+      expect(tsSkills[0].id).toBe('ts-fix');
+
+      // Deprecate one
+      await publisher.deprecateSkill('node-fix', 'Replaced');
+
+      const active = await storage.listSkills({ status: ['active'] });
+      expect(active.length).toBe(2);
+
+      const deprecated = await storage.listSkills({ status: ['deprecated'] });
+      expect(deprecated.length).toBe(1);
+      expect(deprecated[0].id).toBe('node-fix');
+    });
+
+    it('should handle version evolution through publish updates', async () => {
+      const publisher = new SkillPublisher(storage);
+      const playbook = createSamplePlaybook({ id: 'evolve-1' });
+
+      // v1
+      await publisher.publishPlaybook(playbook);
+      let skill = await storage.getSkill('evolve-1');
+      expect(skill!.version).toBe('1.2.0');
+
+      // Evolve
+      playbook.evolution.version = '2.0.0';
+      playbook.evolution.successCount = 20;
+      playbook.confidence = 0.95;
+
+      const result = await publisher.publishPlaybook(playbook);
+      expect(result.isUpdate).toBe(true);
+
+      skill = await storage.getSkill('evolve-1');
+      expect(skill!.version).toBe('2.0.0');
+      expect(skill!.metrics.usageCount).toBe(22);
+      expect(skill!.metrics.averageConfidence).toBe(0.95);
+    });
+  });
+});