cognitive-core 0.2.0 → 0.2.1

package/dist/workspace/templates/playbook-lifecycle-review.js

@@ -0,0 +1,187 @@
+/**
+ * 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 { buildPortfolioSnapshot, } from '../efficacy-toolkit.js';
+// ============================================================
+// Template Implementation
+// ============================================================
+export const playbookLifecycleReviewTemplate = {
+    taskType: 'playbook-lifecycle-review',
+    domain: 'meta-learning',
+    description: 'Portfolio-wide playbook health assessment with lifecycle recommendations',
+    assessComplexity(input) {
+        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) {
+        const snapshot = buildPortfolioSnapshot(input.playbooks, input.annotations, input.playbookEffectiveness, input.unguidedSuccessRate, input.trajectoryDomainMap);
+        // Simple heuristic recommendations
+        const recommendations = [];
+        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, handle) {
+        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) {
+        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',
+                required: true,
+                description: 'Playbook lifecycle review results',
+            },
+        ],
+    },
+    async collectOutput(handle) {
+        const raw = await handle.readJson('output', 'lifecycle-review.json');
+        const snapshot = await handle.readJson('input', 'portfolio-snapshot.json');
+        const recommendations = Array.isArray(raw.recommendations)
+            ? raw.recommendations.map(r => {
+                const mergeTarget = r.mergeTarget;
+                return {
+                    playbookId: String(r.playbookId ?? ''),
+                    playbookName: String(r.playbookName ?? ''),
+                    currentState: String(r.currentState ?? 'active'),
+                    proposedState: String(r.proposedState ?? 'keep-active'),
+                    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'),
+                };
+            })
+            : [];
+        return {
+            snapshot,
+            recommendations,
+            insights: Array.isArray(raw.insights) ? raw.insights.map(String) : [],
+            actionPlan: Array.isArray(raw.actionPlan) ? raw.actionPlan.map(String) : [],
+        };
+    },
+    async processOutput() {
+        // Caller decides how to act on lifecycle recommendations
+    },
+    getComputeRequirements(_input, complexity) {
+        return {
+            mode: 'local',
+            complexity,
+            timeout: complexity === 'thorough' ? 240_000 : 120_000,
+        };
+    },
+    agentType: 'claude-code',
+    timeout: 180_000,
+    captureToolCalls: true,
+};
+//# sourceMappingURL=playbook-lifecycle-review.js.map

package/dist/workspace/templates/playbook-lifecycle-review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playbook-lifecycle-review.js","sourceRoot":"","sources":["../../../src/workspace/templates/playbook-lifecycle-review.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognitive-core",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "TypeScript-native cognitive core for adaptive learning and abstraction",
   "type": "module",
   "main": "dist/index.js",
@@ -12,26 +12,32 @@
   "exports": {
     ".": {
       "import": "./dist/index.js",
+      "default": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
     "./memory": {
       "import": "./dist/memory/index.js",
+      "default": "./dist/memory/index.js",
       "types": "./dist/memory/index.d.ts"
     },
     "./learning": {
       "import": "./dist/learning/index.js",
+      "default": "./dist/learning/index.js",
       "types": "./dist/learning/index.d.ts"
     },
     "./agents": {
       "import": "./dist/agents/index.js",
+      "default": "./dist/agents/index.js",
       "types": "./dist/agents/index.d.ts"
     },
     "./embeddings": {
       "import": "./dist/embeddings/index.js",
+      "default": "./dist/embeddings/index.js",
       "types": "./dist/embeddings/index.d.ts"
     },
     "./session-bank": {
       "import": "./dist/session-bank/index.js",
+      "default": "./dist/session-bank/index.js",
       "types": "./dist/session-bank/index.d.ts"
     }
   },

package/src/index.ts

@@ -435,6 +435,33 @@ export {
   type AgenticTaskResult,
   type AgenticTaskMetrics,
   AgenticTaskOutputError,
+  // Efficacy toolkit
+  computeNormalizedGain,
+  computeTemporalTrend,
+  computeDomainBreakdown,
+  buildEfficacyProfile,
+  buildPortfolioSnapshot,
+  type PlaybookEfficacyProfile,
+  type DomainBreakdown,
+  type TemporalTrend,
+  type UsageProfile,
+  type EvolutionSummary,
+  type PortfolioSnapshot,
+  type PlaybookHealthFlag,
+  type RedundancyPair,
+  // Efficacy templates
+  playbookEfficacyAuditTemplate,
+  type PlaybookEfficacyAuditInput,
+  type PlaybookEfficacyAuditOutput,
+  type PlaybookRecommendation,
+  playbookDecayDetectionTemplate,
+  type PlaybookDecayDetectionInput,
+  type PlaybookDecayDetectionOutput,
+  type DecaySignal,
+  playbookLifecycleReviewTemplate,
+  type PlaybookLifecycleReviewInput,
+  type PlaybookLifecycleReviewOutput,
+  type LifecycleRecommendation,
 } from './workspace/index.js';
 
 // Persistence - Unified SQLite database for system-internal state

package/src/learning/index.ts

@@ -106,6 +106,7 @@ export {
   createUnifiedPipeline,
   type UnifiedPipelineConfig,
   type UnifiedPipelineFeatures,
+  type EfficacyMaintenanceConfig,
   type ImmediateResult,
   type UnifiedBatchResult,
   type UnifiedPipelineStats,

package/src/learning/unified-pipeline.ts

@@ -54,7 +54,12 @@ import { playbookExtractionTemplate } from '../workspace/templates/playbook-extr
 
 // Meta-learning and effectiveness
 import { MetaLearner, type MetaLearnerConfig } from './meta-learner.js';
-import { LearningEffectivenessTracker } from './effectiveness.js';
+import { LearningEffectivenessTracker, type TaskAnnotation, type PlaybookEffectivenessEntry } from './effectiveness.js';
+
+// Efficacy templates (used in maintenance tasks)
+import { playbookDecayDetectionTemplate, type PlaybookDecayDetectionOutput } from '../workspace/templates/playbook-decay-detection.js';
+import { playbookEfficacyAuditTemplate } from '../workspace/templates/playbook-efficacy-audit.js';
+import { playbookLifecycleReviewTemplate } from '../workspace/templates/playbook-lifecycle-review.js';
 
 // Energy evaluator (batch trigger)
 import {
@@ -121,6 +126,8 @@ export interface UnifiedPipelineFeatures {
   effectivenessTracking?: boolean;
   /** Enable healing orchestrator with built-in detectors (default: true) */
   healing?: boolean;
+  /** Enable efficacy maintenance tasks (decay detection, audit, lifecycle review) (default: true) */
+  efficacy?: boolean;
 }
 
 /**
@@ -140,10 +147,30 @@ export interface UnifiedPipelineConfig {
   metaLearner: Partial<MetaLearnerConfig>;
   /** Feature flags */
   features: UnifiedPipelineFeatures;
+  /** Efficacy maintenance config */
+  efficacy: EfficacyMaintenanceConfig;
   /** Max latency warning threshold for instant loop in ms (default: 200) */
   maxInstantLatencyMs: number;
 }
 
+/**
+ * Configuration for efficacy maintenance tasks.
+ */
+export interface EfficacyMaintenanceConfig {
+  /** Run lifecycle review every Nth maintenance cycle (default: 3) */
+  lifecycleReviewFrequency: number;
+  /** Minimum playbooks required before running efficacy tasks (default: 1) */
+  minPlaybooks: number;
+  /** Minimum annotations required before running efficacy tasks (default: 3) */
+  minAnnotations: number;
+}
+
+const DEFAULT_EFFICACY_CONFIG: EfficacyMaintenanceConfig = {
+  lifecycleReviewFrequency: 3,
+  minPlaybooks: 1,
+  minAnnotations: 3,
+};
+
 const DEFAULT_UNIFIED_CONFIG: UnifiedPipelineConfig = {
   instant: {},
   batch: {
@@ -153,6 +180,7 @@ const DEFAULT_UNIFIED_CONFIG: UnifiedPipelineConfig = {
   maintenance: {},
   metaLearner: {},
   features: {},
+  efficacy: DEFAULT_EFFICACY_CONFIG,
   maxInstantLatencyMs: 200,
 };
 
@@ -267,6 +295,7 @@ export class UnifiedLearningPipeline {
   private batchCyclesRun = 0;
   private maintenanceCyclesRun = 0;
   private _onLatencyWarning: ((durationMs: number) => void) | null = null;
+  private lastDecayResult: PlaybookDecayDetectionOutput | null = null;
 
   constructor(
     memory: MemorySystem,
@@ -284,6 +313,7 @@ export class UnifiedLearningPipeline {
       maintenance: { ...DEFAULT_UNIFIED_CONFIG.maintenance, ...config?.maintenance },
       metaLearner: { ...DEFAULT_UNIFIED_CONFIG.metaLearner, ...config?.metaLearner },
       features: { ...DEFAULT_UNIFIED_CONFIG.features, ...config?.features },
+      efficacy: { ...DEFAULT_EFFICACY_CONFIG, ...config?.efficacy },
     };
 
     this.memory = memory;
@@ -822,6 +852,246 @@ export class UnifiedLearningPipeline {
         },
       });
     }
+
+    // Efficacy maintenance tasks
+    this.registerEfficacyMaintenanceTasks();
+  }
+
+  /**
+   * Register efficacy maintenance tasks (decay detection, audit, lifecycle review).
+   * All tasks are log-only — results are returned in details but no automatic mutations.
+   */
+  private registerEfficacyMaintenanceTasks(): void {
+    if (!(this.config.features.efficacy ?? true)) return;
+
+    const efficacyCfg = this.config.efficacy;
+
+    // 1. Playbook Decay Detection (priority 70) — runs every maintenance cycle
+    this.maintenanceScheduler.registerTask({
+      name: 'playbook-decay-detection',
+      priority: 70,
+      execute: async () => {
+        const start = Date.now();
+        this.lastDecayResult = null;
+
+        const { annotations, playbooks, playbookEffectiveness, unguidedSuccessRate } =
+          await this.getEfficacyData();
+
+        if (playbooks.length < efficacyCfg.minPlaybooks || annotations.length < efficacyCfg.minAnnotations) {
+          return {
+            taskName: 'playbook-decay-detection',
+            success: true,
+            durationMs: Date.now() - start,
+            details: { skipped: true, reason: 'insufficient data' },
+          };
+        }
+
+        const result = await playbookDecayDetectionTemplate.heuristicFallback!({
+          playbooks,
+          annotations,
+          playbookEffectiveness,
+          unguidedSuccessRate,
+        });
+
+        this.lastDecayResult = result;
+
+        return {
+          taskName: 'playbook-decay-detection',
+          success: true,
+          durationMs: Date.now() - start,
+          details: {
+            decayingCount: result.decaying.length,
+            atRiskCount: result.atRisk.length,
+            healthyCount: result.healthy.length,
+            decaying: result.decaying,
+            atRisk: result.atRisk,
+            portfolioAssessment: result.portfolioAssessment,
+          },
+        };
+      },
+    });
+
+    // 2. Playbook Efficacy Audit (priority 65) — audits flagged playbooks from decay detection
+    this.maintenanceScheduler.registerTask({
+      name: 'playbook-efficacy-audit',
+      priority: 65,
+      execute: async () => {
+        const start = Date.now();
+
+        if (!this.lastDecayResult) {
+          return {
+            taskName: 'playbook-efficacy-audit',
+            success: true,
+            durationMs: Date.now() - start,
+            details: { skipped: true, reason: 'no decay detection results' },
+          };
+        }
+
+        const flagged = [
+          ...this.lastDecayResult.decaying,
+          ...this.lastDecayResult.atRisk,
+        ];
+
+        if (flagged.length === 0) {
+          return {
+            taskName: 'playbook-efficacy-audit',
+            success: true,
+            durationMs: Date.now() - start,
+            details: { skipped: true, reason: 'no flagged playbooks' },
+          };
+        }
+
+        const { annotations, playbooks, playbookEffectiveness, unguidedSuccessRate } =
+          await this.getEfficacyData();
+
+        const playbookMap = new Map(playbooks.map(p => [p.id, p]));
+        const effectivenessMap = new Map(playbookEffectiveness.map(e => [e.playbookId, e]));
+        const trajectoryDomainMap = this.buildTrajectoryDomainMap(annotations);
+
+        const audits: Array<{
+          playbookId: string;
+          health: string;
+          recommendations: unknown[];
+          summary: string;
+        }> = [];
+
+        for (const signal of flagged) {
+          const playbook = playbookMap.get(signal.playbookId);
+          if (!playbook) continue;
+
+          const auditResult = await playbookEfficacyAuditTemplate.heuristicFallback!({
+            playbook,
+            annotations,
+            playbookEffectiveness: effectivenessMap.get(signal.playbookId),
+            unguidedSuccessRate,
+            trajectoryDomainMap,
+          });
+
+          audits.push({
+            playbookId: signal.playbookId,
+            health: auditResult.assessment.health,
+            recommendations: auditResult.assessment.recommendations,
+            summary: auditResult.assessment.summary,
+          });
+        }
+
+        return {
+          taskName: 'playbook-efficacy-audit',
+          success: true,
+          durationMs: Date.now() - start,
+          details: {
+            auditsPerformed: audits.length,
+            audits,
+          },
+        };
+      },
+    });
+
+    // 3. Playbook Lifecycle Review (priority 50) — runs every Nth maintenance cycle
+    this.maintenanceScheduler.registerTask({
+      name: 'playbook-lifecycle-review',
+      priority: 50,
+      execute: async () => {
+        const start = Date.now();
+
+        // Only run every Nth maintenance cycle
+        if (this.maintenanceCyclesRun % efficacyCfg.lifecycleReviewFrequency !== 0) {
+          return {
+            taskName: 'playbook-lifecycle-review',
+            success: true,
+            durationMs: Date.now() - start,
+            details: {
+              skipped: true,
+              reason: `runs every ${efficacyCfg.lifecycleReviewFrequency} maintenance cycles`,
+            },
+          };
+        }
+
+        const { annotations, playbooks, playbookEffectiveness, unguidedSuccessRate } =
+          await this.getEfficacyData();
+
+        if (playbooks.length < efficacyCfg.minPlaybooks || annotations.length < efficacyCfg.minAnnotations) {
+          return {
+            taskName: 'playbook-lifecycle-review',
+            success: true,
+            durationMs: Date.now() - start,
+            details: { skipped: true, reason: 'insufficient data' },
+          };
+        }
+
+        const trajectoryDomainMap = this.buildTrajectoryDomainMap(annotations);
+
+        const result = await playbookLifecycleReviewTemplate.heuristicFallback!({
+          playbooks,
+          annotations,
+          playbookEffectiveness,
+          unguidedSuccessRate,
+          trajectoryDomainMap,
+        });
+
+        return {
+          taskName: 'playbook-lifecycle-review',
+          success: true,
+          durationMs: Date.now() - start,
+          details: {
+            totalPlaybooks: result.snapshot.totalPlaybooks,
+            recommendationsCount: result.recommendations.length,
+            recommendations: result.recommendations,
+            insights: result.insights,
+            actionPlan: result.actionPlan,
+            snapshot: {
+              avgConfidence: result.snapshot.avgConfidence,
+              avgSuccessRate: result.snapshot.avgSuccessRate,
+              confidenceBands: result.snapshot.confidenceBands,
+              decayingCount: result.snapshot.decaying.length,
+              staleCount: result.snapshot.stale.length,
+            },
+          },
+        };
+      },
+    });
+  }
+
+  /**
+   * Fetch shared efficacy data used by all three efficacy maintenance tasks.
+   */
+  private async getEfficacyData(): Promise<{
+    annotations: TaskAnnotation[];
+    playbooks: Playbook[];
+    playbookEffectiveness: PlaybookEffectivenessEntry[];
+    unguidedSuccessRate: number;
+  }> {
+    const playbooks = await this.memory.playbooks.getAll();
+
+    let annotations: TaskAnnotation[] = [];
+    let playbookEffectiveness: PlaybookEffectivenessEntry[] = [];
+    let unguidedSuccessRate = 0;
+
+    if (this.effectivenessTracker) {
+      annotations = await this.effectivenessTracker.getAll();
+      const metrics = await this.effectivenessTracker.computeMetrics();
+      playbookEffectiveness = metrics.playbookEffectiveness;
+      unguidedSuccessRate = metrics.unguidedSuccessRate;
+    }
+
+    return { annotations, playbooks, playbookEffectiveness, unguidedSuccessRate };
+  }
+
+  /**
+   * Build a trajectoryId→domain map from annotations.
+   * Uses accumulated trajectories when available, otherwise infers from task annotations.
+   */
+  private buildTrajectoryDomainMap(_annotations: TaskAnnotation[]): Map<string, string> {
+    const domainMap = new Map<string, string>();
+
+    // Map from accumulated trajectories (has task.domain directly).
+    // Annotations don't carry domain, so historical trajectories will
+    // fall through to the toolkit's 'unknown' default — acceptable for log-only mode.
+    for (const t of this.accumulated) {
+      domainMap.set(t.id, t.task.domain);
+    }
+
+    return domainMap;
   }
 
   /**

package/src/memory/candidate-retrieval.ts

@@ -63,7 +63,8 @@ export function getCandidates<T>(
       const item = resolver.get(id);
       if (item) items.push(item);
     }
-    return items;
+    // If all IDs were stale/unresolvable, fall back to full scan
+    if (items.length > 0) return items;
   }
 
   // Too few candidates — fall back

package/src/utils/error-classifier.ts

@@ -60,26 +60,26 @@ const ERROR_RULES: Array<{ test: (s: string) => boolean; type: ErrorType; descri
     type: 'permission-error',
     description: 'Permission denied',
   },
-  {
-    test: (s) => /not\s*found|missing|no\s*such\s*file/i.test(s),
-    type: 'not-found',
-    description: 'Resource not found',
-  },
   {
     test: (s) => /network|connection|ECONNREFUSED|ENOTFOUND/i.test(s),
     type: 'network-error',
     description: 'Network or connection error',
   },
   {
-    test: (s) => /test.*fail|fail.*test|assertion|assert/i.test(s),
-    type: 'test-failure',
-    description: 'Test or assertion failure',
+    test: (s) => /not\s*found|missing|no\s*such\s*file/i.test(s),
+    type: 'not-found',
+    description: 'Resource not found',
   },
   {
     test: (s) => /assertion|assert/i.test(s),
     type: 'assertion-error',
     description: 'Assertion failed',
   },
+  {
+    test: (s) => /test.*fail|fail.*test/i.test(s),
+    type: 'test-failure',
+    description: 'Test or assertion failure',
+  },
   {
     test: (s) => /exception|error/i.test(s),
     type: 'general-error',