cognitive-core 0.1.2 → 0.2.1

package/src/workspace/templates/playbook-lifecycle-review.ts

@@ -0,0 +1,274 @@
+/**
+ * Playbook Lifecycle Review Template
+ *
+ * Portfolio-wide health assessment with lifecycle recommendations.
+ * Uses the efficacy toolkit's portfolio snapshot to give the agent
+ * a pre-computed view of the entire playbook portfolio, then asks
+ * for promotion, deprecation, merge, and evolution recommendations.
+ *
+ * This is the "skill designer" review step (inspired by MemSkill)
+ * that periodically evaluates the whole portfolio.
+ */
+
+import type { WorkspaceHandle } from 'agent-workspace';
+import type { Playbook } from '../../types/index.js';
+import type { TaskAnnotation, PlaybookEffectivenessEntry } from '../../learning/effectiveness.js';
+import type {
+  AgenticTaskTemplate,
+  AnalysisComplexity,
+} from '../types.js';
+import {
+  buildPortfolioSnapshot,
+  type PortfolioSnapshot,
+} from '../efficacy-toolkit.js';
+
+// ============================================================
+// Input / Output Types
+// ============================================================
+
+export interface PlaybookLifecycleReviewInput {
+  playbooks: Playbook[];
+  annotations: TaskAnnotation[];
+  playbookEffectiveness: PlaybookEffectivenessEntry[];
+  unguidedSuccessRate: number;
+  trajectoryDomainMap: Map<string, string>;
+  /** Current core tier playbook IDs (from SkillLibrary) */
+  corePlaybookIds?: string[];
+}
+
+export interface PlaybookLifecycleReviewOutput {
+  /** Pre-computed portfolio snapshot */
+  snapshot: PortfolioSnapshot;
+  /** Agent's lifecycle recommendations */
+  recommendations: LifecycleRecommendation[];
+  /** Portfolio-level strategic insights */
+  insights: string[];
+  /** Priority-ordered action plan */
+  actionPlan: string[];
+}
+
+export interface LifecycleRecommendation {
+  playbookId: string;
+  playbookName: string;
+  currentState: 'active' | 'core' | 'stale' | 'underperforming';
+  proposedState: 'promote-to-core' | 'keep-active' | 'deprecate' | 'archive'
+    | 'merge' | 'evolve' | 'split';
+  rationale: string;
+  /** For merge: target playbook */
+  mergeTarget?: { id: string; name: string };
+  /** For evolve: suggested guidance changes */
+  evolutionNotes?: string;
+  priority: 'high' | 'medium' | 'low';
+}
+
+// ============================================================
+// Template Implementation
+// ============================================================
+
+export const playbookLifecycleReviewTemplate: AgenticTaskTemplate<
+  PlaybookLifecycleReviewInput,
+  PlaybookLifecycleReviewOutput
+> = {
+  taskType: 'playbook-lifecycle-review',
+  domain: 'meta-learning',
+  description: 'Portfolio-wide playbook health assessment with lifecycle recommendations',
+
+  assessComplexity(input: PlaybookLifecycleReviewInput): AnalysisComplexity {
+    if (input.playbooks.length === 0) return 'heuristic';
+    if (input.playbooks.length <= 3 && input.annotations.length < 10) return 'heuristic';
+    if (input.playbooks.length > 30) return 'thorough';
+    if (input.playbooks.length > 10) return 'standard';
+    return 'lightweight';
+  },
+
+  async heuristicFallback(input: PlaybookLifecycleReviewInput): Promise<PlaybookLifecycleReviewOutput> {
+    const snapshot = buildPortfolioSnapshot(
+      input.playbooks,
+      input.annotations,
+      input.playbookEffectiveness,
+      input.unguidedSuccessRate,
+      input.trajectoryDomainMap,
+    );
+
+    // Simple heuristic recommendations
+    const recommendations: LifecycleRecommendation[] = [];
+
+    for (const flag of snapshot.decaying) {
+      recommendations.push({
+        playbookId: flag.playbookId,
+        playbookName: flag.playbookName,
+        currentState: 'active',
+        proposedState: 'evolve',
+        rationale: flag.reason,
+        priority: 'high',
+      });
+    }
+
+    for (const flag of snapshot.stale) {
+      recommendations.push({
+        playbookId: flag.playbookId,
+        playbookName: flag.playbookName,
+        currentState: 'stale',
+        proposedState: 'archive',
+        rationale: flag.reason,
+        priority: 'medium',
+      });
+    }
+
+    return {
+      snapshot,
+      recommendations,
+      insights: [],
+      actionPlan: recommendations.map(r =>
+        `${r.proposedState} "${r.playbookName}" — ${r.rationale}`
+      ),
+    };
+  },
+
+  async prepareWorkspace(
+    input: PlaybookLifecycleReviewInput,
+    handle: WorkspaceHandle
+  ): Promise<void> {
+    const snapshot = buildPortfolioSnapshot(
+      input.playbooks,
+      input.annotations,
+      input.playbookEffectiveness,
+      input.unguidedSuccessRate,
+      input.trajectoryDomainMap,
+    );
+
+    // Portfolio snapshot — the core data
+    await handle.writeJson('input', 'portfolio-snapshot.json', snapshot);
+
+    // Per-playbook summaries for the agent to reference
+    const playbookSummaries = input.playbooks.map(pb => ({
+      id: pb.id,
+      name: pb.name,
+      confidence: pb.confidence,
+      successCount: pb.evolution.successCount,
+      failureCount: pb.evolution.failureCount,
+      successRate: pb.evolution.successCount + pb.evolution.failureCount > 0
+        ? pb.evolution.successCount / (pb.evolution.successCount + pb.evolution.failureCount)
+        : 0,
+      domains: pb.applicability.domains,
+      strategy: pb.guidance.strategy,
+      tacticsCount: pb.guidance.tactics.length,
+      refinementsCount: pb.evolution.refinements.length,
+      version: pb.evolution.version,
+      lastUsed: pb.evolution.lastUsed,
+      isCore: input.corePlaybookIds?.includes(pb.id) ?? false,
+      consolidationStrength: pb.evolution.consolidationStrength ?? 0,
+    }));
+
+    await handle.writeJson('input', 'playbook-summaries.json', playbookSummaries);
+
+    // Redundancy pairs (pre-computed by toolkit)
+    if (snapshot.redundant.length > 0) {
+      await handle.writeJson('input', 'redundancy-pairs.json', snapshot.redundant);
+    }
+  },
+
+  buildTaskPrompt(input: PlaybookLifecycleReviewInput): string {
+    return [
+      `Review the health of the entire playbook portfolio (${input.playbooks.length} playbooks).`,
+      '',
+      'Read:',
+      '- input/portfolio-snapshot.json — Portfolio health metrics, flagged issues (decaying, stale, low adoption, redundant)',
+      '- input/playbook-summaries.json — Per-playbook summaries with confidence, success rates, domains',
+      '- input/redundancy-pairs.json — (if present) Playbook pairs with high content overlap',
+      '',
+      'For each playbook, recommend a lifecycle action:',
+      '- **promote-to-core**: High confidence + success rate, proven across tasks',
+      '- **keep-active**: Performing well, no changes needed',
+      '- **evolve**: Decent foundation but guidance needs updating based on failure patterns',
+      '- **merge**: Two playbooks cover the same ground — merge into one stronger playbook',
+      '- **split**: One playbook covers too many domains — split into domain-specific variants',
+      '- **deprecate**: Low value, actively misleading, or superseded',
+      '- **archive**: No longer relevant but worth preserving for reference',
+      '',
+      'Also provide:',
+      '- Strategic insights about the portfolio (coverage gaps, over-invested domains, etc.)',
+      '- A priority-ordered action plan (most impactful changes first)',
+      '',
+      'Write to output/lifecycle-review.json:',
+      '```json',
+      '{',
+      '  "recommendations": [',
+      '    {',
+      '      "playbookId": "id",',
+      '      "playbookName": "name",',
+      '      "currentState": "active" | "core" | "stale" | "underperforming",',
+      '      "proposedState": "promote-to-core" | "keep-active" | "deprecate" | "archive" | "merge" | "evolve" | "split",',
+      '      "rationale": "why this change",',
+      '      "mergeTarget": { "id": "...", "name": "..." },',
+      '      "evolutionNotes": "optional: what to change in guidance",',
+      '      "priority": "high" | "medium" | "low"',
+      '    }',
+      '  ],',
+      '  "insights": ["insight1", "insight2"],',
+      '  "actionPlan": ["step1", "step2"]',
+      '}',
+      '```',
+    ].join('\n');
+  },
+
+  getSkills() { return []; },
+  getResources() { return []; },
+
+  outputConfig: {
+    files: [
+      {
+        path: 'lifecycle-review.json',
+        format: 'json' as const,
+        required: true,
+        description: 'Playbook lifecycle review results',
+      },
+    ],
+  },
+
+  async collectOutput(handle: WorkspaceHandle): Promise<PlaybookLifecycleReviewOutput> {
+    const raw = await handle.readJson('output', 'lifecycle-review.json') as Record<string, unknown>;
+    const snapshot = await handle.readJson('input', 'portfolio-snapshot.json') as PortfolioSnapshot;
+
+    const recommendations: LifecycleRecommendation[] = Array.isArray(raw.recommendations)
+      ? (raw.recommendations as Record<string, unknown>[]).map(r => {
+          const mergeTarget = r.mergeTarget as Record<string, unknown> | undefined;
+          return {
+            playbookId: String(r.playbookId ?? ''),
+            playbookName: String(r.playbookName ?? ''),
+            currentState: String(r.currentState ?? 'active') as LifecycleRecommendation['currentState'],
+            proposedState: String(r.proposedState ?? 'keep-active') as LifecycleRecommendation['proposedState'],
+            rationale: String(r.rationale ?? ''),
+            mergeTarget: mergeTarget
+              ? { id: String(mergeTarget.id ?? ''), name: String(mergeTarget.name ?? '') }
+              : undefined,
+            evolutionNotes: r.evolutionNotes ? String(r.evolutionNotes) : undefined,
+            priority: String(r.priority ?? 'medium') as LifecycleRecommendation['priority'],
+          };
+        })
+      : [];
+
+    return {
+      snapshot,
+      recommendations,
+      insights: Array.isArray(raw.insights) ? raw.insights.map(String) : [],
+      actionPlan: Array.isArray(raw.actionPlan) ? raw.actionPlan.map(String) : [],
+    };
+  },
+
+  async processOutput(): Promise<void> {
+    // Caller decides how to act on lifecycle recommendations
+  },
+
+  getComputeRequirements(_input, complexity) {
+    return {
+      mode: 'local' as const,
+      complexity,
+      timeout: complexity === 'thorough' ? 240_000 : 120_000,
+    };
+  },
+
+  agentType: 'claude-code',
+  timeout: 180_000,
+  captureToolCalls: true,
+};

package/src/workspace/types.ts

@@ -1,6 +1,6 @@
 import type { WorkspaceHandle, OutputSpec } from 'agent-workspace';
 import type { MemorySystem, MemoryQueryResultV2 } from '../memory/system.js';
-import type { LearningPipeline } from '../learning/pipeline.js';
+import type { Trajectory } from '../types/index.js';
 import type { ComputeRequirements } from '../runtime/compute-provider.js';
 
 // Re-export agent-workspace types used by consumers
@@ -61,9 +61,17 @@ export type AnalysisComplexity =
 /**
  * Context passed to processOutput for storing/accumulating results.
  */
+/**
+ * Minimal pipeline interface for workspace processing context.
+ * Satisfied by both LearningPipeline and UnifiedLearningPipeline.
+ */
+export interface TrajectoryProcessor {
+  processTrajectory(trajectory: Trajectory, ...args: unknown[]): Promise<unknown>;
+}
+
 export interface ProcessingContext {
   memory: MemorySystem;
-  learningPipeline: LearningPipeline;
+  learningPipeline: TrajectoryProcessor;
 }
 
 // ============================================================

package/tests/embeddings/inverted-index.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { InvertedIndex } from '../../src/embeddings/inverted-index.js';
+
+describe('InvertedIndex', () => {
+  let index: InvertedIndex;
+
+  beforeEach(() => {
+    index = new InvertedIndex();
+  });
+
+  describe('add and has', () => {
+    it('should add a document and report it exists', () => {
+      index.add('doc1', 'fix typescript import error');
+      expect(index.has('doc1')).toBe(true);
+      expect(index.size()).toBe(1);
+    });
+
+    it('should report non-existent document as missing', () => {
+      expect(index.has('missing')).toBe(false);
+    });
+
+    it('should handle updating an existing document', () => {
+      index.add('doc1', 'original content');
+      index.add('doc1', 'updated content');
+      expect(index.size()).toBe(1);
+
+      // Should find by updated content
+      const candidates = index.getCandidates('updated');
+      expect(candidates).toContain('doc1');
+    });
+  });
+
+  describe('remove', () => {
+    it('should remove a document and clean up postings', () => {
+      index.add('doc1', 'typescript error');
+      expect(index.has('doc1')).toBe(true);
+
+      const removed = index.remove('doc1');
+      expect(removed).toBe(true);
+      expect(index.has('doc1')).toBe(false);
+      expect(index.size()).toBe(0);
+    });
+
+    it('should return false when removing non-existent document', () => {
+      expect(index.remove('missing')).toBe(false);
+    });
+
+    it('should not return removed document in candidates', () => {
+      index.add('doc1', 'typescript error');
+      index.add('doc2', 'typescript warning');
+      index.remove('doc1');
+
+      const candidates = index.getCandidates('typescript');
+      expect(candidates).not.toContain('doc1');
+      expect(candidates).toContain('doc2');
+    });
+  });
+
+  describe('getCandidates', () => {
+    it('should return relevant candidates ranked by match count', () => {
+      index.add('doc1', 'fix typescript import error in module');
+      index.add('doc2', 'fix python import error in package');
+      index.add('doc3', 'create database schema migration');
+
+      const candidates = index.getCandidates('fix typescript import error');
+
+      // doc1 should rank first (most token matches)
+      expect(candidates[0]).toBe('doc1');
+      // doc2 should also appear (shares fix, import, error)
+      expect(candidates).toContain('doc2');
+      // doc3 should not appear or rank low (no overlap after stopword removal)
+      expect(candidates.indexOf('doc3')).toBe(-1);
+    });
+
+    it('should return empty array for empty query', () => {
+      index.add('doc1', 'some content');
+      expect(index.getCandidates('')).toEqual([]);
+    });
+
+    it('should return empty array for stopword-only query', () => {
+      index.add('doc1', 'some content');
+      expect(index.getCandidates('the and is')).toEqual([]);
+    });
+
+    it('should respect maxCandidates limit', () => {
+      for (let i = 0; i < 100; i++) {
+        index.add(`doc${i}`, `common term unique${i}`);
+      }
+
+      const candidates = index.getCandidates('common term', 5);
+      expect(candidates).toHaveLength(5);
+    });
+
+    it('should handle duplicate tokens in same document', () => {
+      index.add('doc1', 'error error error typescript');
+      index.add('doc2', 'error typescript');
+
+      const candidates = index.getCandidates('error');
+      // Both should appear — the index deduplicates postings per doc
+      expect(candidates).toContain('doc1');
+      expect(candidates).toContain('doc2');
+    });
+
+    it('should be case-insensitive', () => {
+      index.add('doc1', 'TypeScript Import Error');
+
+      const candidates = index.getCandidates('typescript import error');
+      expect(candidates).toContain('doc1');
+    });
+  });
+
+  describe('clear', () => {
+    it('should remove all documents', () => {
+      index.add('doc1', 'first');
+      index.add('doc2', 'second');
+      index.clear();
+
+      expect(index.size()).toBe(0);
+      expect(index.has('doc1')).toBe(false);
+      expect(index.getCandidates('first')).toEqual([]);
+    });
+  });
+
+  describe('size', () => {
+    it('should track document count correctly', () => {
+      expect(index.size()).toBe(0);
+
+      index.add('a', 'one');
+      expect(index.size()).toBe(1);
+
+      index.add('b', 'two');
+      expect(index.size()).toBe(2);
+
+      index.remove('a');
+      expect(index.size()).toBe(1);
+    });
+  });
+});