cognitive-core 0.2.5 → 0.3.1

package/src/workspace/templates/meta-reflection.ts

@@ -1,208 +0,0 @@
-/**
- * Meta-Reflection Template
- *
- * Replaces MetaLearner.generateReflection() with workspace-based
- * semantic reflection that analyzes what worked and why.
- *
- * - Clear success with high confidence routing → heuristic fallback
- * - Failures or uncertain outcomes → agent reflects on execution
- */
-
-import type { WorkspaceHandle } from 'agent-workspace';
-import type { Trajectory } from '../../types/index.js';
-import type { PlaybookMatch } from '../../memory/playbook.js';
-import type {
-  AgenticTaskTemplate,
-  AnalysisComplexity,
-} from '../types.js';
-
-// ============================================================
-// Input / Output Types
-// ============================================================
-
-export interface MetaReflectionInput {
-  trajectory: Trajectory;
-  routingDecision: {
-    strategy: string;
-    confidence: number;
-    estimatedBudget: number;
-    reasoning: string;
-  };
-  playbooksUsed: PlaybookMatch[];
-}
-
-/**
- * Simplified meta-reflection output.
- * The full MetaObservation is constructed by the MetaLearner after
- * receiving this output, so we only need the core reflection data.
- */
-export interface MetaReflectionOutput {
-  /** Was the retrieval helpful, neutral, or misleading? */
-  retrievalQuality: 'helpful' | 'neutral' | 'misleading';
-  /** Overall outcome quality */
-  outcomeQuality: 'excellent' | 'good' | 'acceptable' | 'poor';
-  /** What worked well */
-  whatWorked: string[];
-  /** What failed or was suboptimal */
-  whatFailed: string[];
-  /** Suggestions for improvement */
-  suggestions: string[];
-  /** Whether decomposition was used */
-  decompositionUsed: boolean;
-  /** Whether backtracking occurred */
-  backtrackingOccurred: boolean;
-  /** Estimated refinement iterations */
-  refinementIterations: number;
-}
-
-// ============================================================
-// Template Implementation
-// ============================================================
-
-export const metaReflectionTemplate: AgenticTaskTemplate<
-  MetaReflectionInput,
-  MetaReflectionOutput
-> = {
-  taskType: 'meta-reflection',
-  domain: 'meta-reflection',
-  description: 'Reflect on task execution to generate meta-learning observations',
-
-  assessComplexity(input: MetaReflectionInput): AnalysisComplexity {
-    // Clear success with high confidence → heuristic
-    if (
-      input.trajectory.outcome.success &&
-      input.routingDecision.confidence > 0.8
-    ) {
-      return 'heuristic';
-    }
-    return 'lightweight';
-  },
-
-  async heuristicFallback(input: MetaReflectionInput): Promise<MetaReflectionOutput> {
-    const { trajectory, routingDecision, playbooksUsed } = input;
-    const wasSuccessful = trajectory.outcome.success;
-    const actualEffort = trajectory.llmCalls ?? trajectory.steps.length;
-    const effortRatio = actualEffort / routingDecision.estimatedBudget;
-
-    return {
-      retrievalQuality: playbooksUsed.length === 0 ? 'neutral'
-        : wasSuccessful ? 'helpful' : 'neutral',
-      outcomeQuality: !wasSuccessful ? 'poor'
-        : effortRatio <= 0.5 ? 'excellent'
-        : effortRatio <= 1.0 ? 'good'
-        : effortRatio <= 2.0 ? 'acceptable' : 'poor',
-      whatWorked: wasSuccessful
-        ? [`${routingDecision.strategy} routing led to success`]
-        : [],
-      whatFailed: wasSuccessful
-        ? []
-        : [`${routingDecision.strategy} routing did not lead to success`],
-      suggestions: wasSuccessful ? [] : ['Consider alternative approaches'],
-      decompositionUsed: trajectory.steps.some(
-        s => s.thought?.includes('break') || s.thought?.includes('step by step')
-      ),
-      backtrackingOccurred: false,
-      refinementIterations: 0,
-    };
-  },
-
-  async prepareWorkspace(
-    input: MetaReflectionInput,
-    handle: WorkspaceHandle
-  ): Promise<void> {
-    const { trajectory, routingDecision, playbooksUsed } = input;
-
-    await handle.writeJson('input', 'context.json', {
-      routing: routingDecision,
-      outcome: trajectory.outcome,
-      stepCount: trajectory.steps.length,
-      wallTimeSeconds: trajectory.wallTimeSeconds,
-      playbooksInjected: playbooksUsed.map(pm => ({
-        name: pm.playbook.name,
-        strategy: pm.playbook.guidance.strategy,
-        score: pm.score,
-        matchType: pm.matchType,
-      })),
-    });
-
-    await handle.writeJsonl('input', 'steps.jsonl',
-      trajectory.steps.map((step, i) => ({
-        index: i,
-        thought: step.thought?.slice(0, 200),
-        action: step.action.slice(0, 200),
-        observation: step.observation?.slice(0, 200),
-      }))
-    );
-  },
-
-  buildTaskPrompt(input: MetaReflectionInput): string {
-    const outcome = input.trajectory.outcome.success ? 'SUCCESSFUL' : 'FAILED';
-    return [
-      `Reflect on this ${outcome} task execution.`,
-      '',
-      'Read input/context.json for routing decision and outcome.',
-      'Read input/steps.jsonl for the execution trace.',
-      '',
-      'Analyze:',
-      '1. Was the retrieved knowledge helpful, neutral, or misleading?',
-      '2. What outcome quality level (excellent/good/acceptable/poor)?',
-      '3. What worked well? What failed?',
-      '4. What suggestions for future similar tasks?',
-      '5. Was decomposition used? Did backtracking occur?',
-      '',
-      'Write to output/reflection.json with this schema:',
-      '```json',
-      '{',
-      '  "retrievalQuality": "helpful" | "neutral" | "misleading",',
-      '  "outcomeQuality": "excellent" | "good" | "acceptable" | "poor",',
-      '  "whatWorked": ["..."],',
-      '  "whatFailed": ["..."],',
-      '  "suggestions": ["..."],',
-      '  "decompositionUsed": boolean,',
-      '  "backtrackingOccurred": boolean,',
-      '  "refinementIterations": number',
-      '}',
-      '```',
-    ].join('\n');
-  },
-
-  getSkills() { return []; },
-  getResources() { return []; },
-
-  outputConfig: {
-    files: [{
-      path: 'reflection.json',
-      format: 'json' as const,
-      required: true,
-      description: 'Meta-reflection on task execution',
-    }],
-  },
-
-  async collectOutput(handle: WorkspaceHandle): Promise<MetaReflectionOutput> {
-    const raw = await handle.readJson('output', 'reflection.json') as Record<string, unknown>;
-    return {
-      retrievalQuality: (['helpful', 'neutral', 'misleading'].includes(String(raw.retrievalQuality))
-        ? raw.retrievalQuality : 'neutral') as MetaReflectionOutput['retrievalQuality'],
-      outcomeQuality: (['excellent', 'good', 'acceptable', 'poor'].includes(String(raw.outcomeQuality))
-        ? raw.outcomeQuality : 'poor') as MetaReflectionOutput['outcomeQuality'],
-      whatWorked: Array.isArray(raw.whatWorked) ? raw.whatWorked.map(String) : [],
-      whatFailed: Array.isArray(raw.whatFailed) ? raw.whatFailed.map(String) : [],
-      suggestions: Array.isArray(raw.suggestions) ? raw.suggestions.map(String) : [],
-      decompositionUsed: Boolean(raw.decompositionUsed),
-      backtrackingOccurred: Boolean(raw.backtrackingOccurred),
-      refinementIterations: typeof raw.refinementIterations === 'number'
-        ? raw.refinementIterations : 0,
-    };
-  },
-
-  async processOutput(): Promise<void> {},
-
-  agentType: 'claude-code',
-  timeout: 120_000,
-  captureToolCalls: true,
-
-  computeRequirements: {
-    mode: 'local',
-    complexity: 'lightweight',
-  },
-};

package/src/workspace/templates/playbook-decay-detection.ts

@@ -1,272 +0,0 @@
-/**
- * Playbook Decay Detection Template
- *
- * Portfolio-wide scan for playbooks showing declining efficacy.
- * Uses temporal trend analysis to identify decay early, before
- * playbooks accumulate enough failures to trigger confidence drops.
- *
- * The agent reviews pre-computed trends and cross-references with
- * failure patterns to determine whether decay is real (environment
- * changed) or noise (small sample size).
- */
-
-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 {
-  computeTemporalTrend,
-  computeNormalizedGain,
-  type TemporalTrend,
-} from '../efficacy-toolkit.js';
-import { getPlaybookSuccessRate } from '../../types/index.js';
-
-// ============================================================
-// Input / Output Types
-// ============================================================
-
-export interface PlaybookDecayDetectionInput {
-  playbooks: Playbook[];
-  annotations: TaskAnnotation[];
-  playbookEffectiveness: PlaybookEffectivenessEntry[];
-  unguidedSuccessRate: number;
-}
-
-export interface PlaybookDecayDetectionOutput {
-  /** Playbooks with detected decay signals */
-  decaying: DecaySignal[];
-  /** Playbooks at risk of decay (early warning) */
-  atRisk: DecaySignal[];
-  /** Playbooks confirmed stable or improving */
-  healthy: string[];
-  /** Agent's overall assessment */
-  portfolioAssessment: string;
-}
-
-export interface DecaySignal {
-  playbookId: string;
-  playbookName: string;
-  trend: TemporalTrend;
-  /** Agent's explanation of why this playbook is decaying */
-  diagnosis: string;
-  /** Recommended action */
-  recommendation: 'investigate' | 'refine' | 'deprecate' | 'monitor';
-  /** Severity: how urgently this needs attention */
-  severity: 'critical' | 'warning' | 'info';
-  /** Supporting evidence */
-  evidence: string[];
-}
-
-// ============================================================
-// Template Implementation
-// ============================================================
-
-export const playbookDecayDetectionTemplate: AgenticTaskTemplate<
-  PlaybookDecayDetectionInput,
-  PlaybookDecayDetectionOutput
-> = {
-  taskType: 'playbook-decay-detection',
-  domain: 'meta-learning',
-  description: 'Detect declining efficacy across the playbook portfolio',
-
-  assessComplexity(input: PlaybookDecayDetectionInput): AnalysisComplexity {
-    if (input.playbooks.length === 0) return 'heuristic';
-    if (input.annotations.length < 10) return 'heuristic';
-    if (input.playbooks.length > 20) return 'standard';
-    return 'lightweight';
-  },
-
-  async heuristicFallback(input: PlaybookDecayDetectionInput): Promise<PlaybookDecayDetectionOutput> {
-    const decaying: DecaySignal[] = [];
-    const atRisk: DecaySignal[] = [];
-    const healthy: string[] = [];
-
-    for (const pb of input.playbooks) {
-      const trend = computeTemporalTrend(input.annotations, pb.id);
-
-      if (trend.dataPoints < 4) {
-        healthy.push(pb.id);
-        continue;
-      }
-
-      if (trend.direction === 'decaying') {
-        decaying.push({
-          playbookId: pb.id,
-          playbookName: pb.name,
-          trend,
-          diagnosis: `Success rate declining from ${(trend.oldestSuccessRate * 100).toFixed(0)}% to ${(trend.recentSuccessRate * 100).toFixed(0)}%`,
-          recommendation: trend.slope < -0.15 ? 'refine' : 'monitor',
-          severity: trend.slope < -0.15 ? 'warning' : 'info',
-          evidence: [`Trend slope: ${trend.slope.toFixed(3)}`],
-        });
-      } else if (trend.daysSinceLastUse !== null && trend.daysSinceLastUse > 30) {
-        atRisk.push({
-          playbookId: pb.id,
-          playbookName: pb.name,
-          trend,
-          diagnosis: `No usage in ${Math.round(trend.daysSinceLastUse)} days — may be going stale`,
-          recommendation: 'investigate',
-          severity: 'info',
-          evidence: [`Last used ${Math.round(trend.daysSinceLastUse)} days ago`],
-        });
-      } else {
-        healthy.push(pb.id);
-      }
-    }
-
-    return {
-      decaying,
-      atRisk,
-      healthy,
-      portfolioAssessment: `${decaying.length} decaying, ${atRisk.length} at risk, ${healthy.length} healthy.`,
-    };
-  },
-
-  async prepareWorkspace(
-    input: PlaybookDecayDetectionInput,
-    handle: WorkspaceHandle
-  ): Promise<void> {
-    const effectivenessMap = new Map(
-      input.playbookEffectiveness.map(e => [e.playbookId, e])
-    );
-
-    // Pre-compute trends for all playbooks
-    const trendData = input.playbooks.map(pb => {
-      const trend = computeTemporalTrend(input.annotations, pb.id);
-      const eff = effectivenessMap.get(pb.id);
-      const successRate = getPlaybookSuccessRate(pb);
-      const appliedRate = eff?.appliedSuccessRate ?? successRate;
-      const normalizedGain = computeNormalizedGain(appliedRate, input.unguidedSuccessRate);
-
-      return {
-        playbookId: pb.id,
-        playbookName: pb.name,
-        confidence: pb.confidence,
-        successRate,
-        normalizedGain,
-        totalUses: pb.evolution.successCount + pb.evolution.failureCount,
-        domains: pb.applicability.domains,
-        trend,
-        recentFailureModes: pb.evolution.failures.slice(-3).map(f => f.failureMode),
-        adoptionRate: eff && eff.surfacedCount > 0
-          ? eff.appliedCount / eff.surfacedCount
-          : null,
-      };
-    });
-
-    await handle.writeJson('input', 'playbook-trends.json', trendData);
-
-    // Summary stats
-    await handle.writeJson('input', 'summary.json', {
-      totalPlaybooks: input.playbooks.length,
-      totalAnnotations: input.annotations.length,
-      unguidedSuccessRate: input.unguidedSuccessRate,
-      decayingCount: trendData.filter(t => t.trend.direction === 'decaying').length,
-      improvingCount: trendData.filter(t => t.trend.direction === 'improving').length,
-      stableCount: trendData.filter(t => t.trend.direction === 'stable').length,
-    });
-  },
-
-  buildTaskPrompt(input: PlaybookDecayDetectionInput): string {
-    return [
-      `Analyze ${input.playbooks.length} playbooks for signs of declining efficacy.`,
-      '',
-      'Read:',
-      '- input/playbook-trends.json — Pre-computed temporal trends, normalized gains, and failure modes for each playbook',
-      '- input/summary.json — Portfolio summary statistics',
-      '',
-      'For each playbook showing negative trends or staleness:',
-      '1. Is the decay real or just noise from small sample size?',
-      '2. What might be causing the decline? (environment changes, scope mismatch, guidance outdated)',
-      '3. What action should be taken?',
-      '',
-      'Also flag playbooks that aren\'t decaying yet but show early warning signs:',
-      '- Declining adoption rate (agents stop choosing to use it)',
-      '- Increasing failure modes diversity (suggests scope drift)',
-      '- High normalized gain but low confidence (fragile effectiveness)',
-      '',
-      'Write results to output/decay-report.json:',
-      '```json',
-      '{',
-      '  "decaying": [',
-      '    {',
-      '      "playbookId": "id",',
-      '      "playbookName": "name",',
-      '      "diagnosis": "why this is decaying",',
-      '      "recommendation": "investigate" | "refine" | "deprecate" | "monitor",',
-      '      "severity": "critical" | "warning" | "info",',
-      '      "evidence": ["supporting facts"]',
-      '    }',
-      '  ],',
-      '  "atRisk": [same structure],',
-      '  "healthy": ["playbookId1", "playbookId2"],',
-      '  "portfolioAssessment": "2-3 sentence overall assessment"',
-      '}',
-      '```',
-    ].join('\n');
-  },
-
-  getSkills() { return []; },
-  getResources() { return []; },
-
-  outputConfig: {
-    files: [
-      {
-        path: 'decay-report.json',
-        format: 'json' as const,
-        required: true,
-        description: 'Playbook decay detection results',
-      },
-    ],
-  },
-
-  async collectOutput(handle: WorkspaceHandle): Promise<PlaybookDecayDetectionOutput> {
-    const raw = await handle.readJson('output', 'decay-report.json') as Record<string, unknown>;
-
-    // Also read back trend data for full DecaySignal objects
-    const trendData = await handle.readJson('input', 'playbook-trends.json') as Array<{
-      playbookId: string;
-      trend: TemporalTrend;
-    }>;
-    const trendMap = new Map(trendData.map(t => [t.playbookId, t.trend]));
-
-    const parseSignals = (items: unknown): DecaySignal[] => {
-      if (!Array.isArray(items)) return [];
-      return (items as Record<string, unknown>[]).map(item => ({
-        playbookId: String(item.playbookId ?? ''),
-        playbookName: String(item.playbookName ?? ''),
-        trend: trendMap.get(String(item.playbookId ?? '')) ?? {
-          slope: 0, direction: 'stable' as const, dataPoints: 0,
-          recentSuccessRate: 0, oldestSuccessRate: 0, daysSinceLastUse: null,
-        },
-        diagnosis: String(item.diagnosis ?? ''),
-        recommendation: String(item.recommendation ?? 'monitor') as DecaySignal['recommendation'],
-        severity: String(item.severity ?? 'info') as DecaySignal['severity'],
-        evidence: Array.isArray(item.evidence) ? item.evidence.map(String) : [],
-      }));
-    };
-
-    return {
-      decaying: parseSignals(raw.decaying),
-      atRisk: parseSignals(raw.atRisk),
-      healthy: Array.isArray(raw.healthy) ? raw.healthy.map(String) : [],
-      portfolioAssessment: String(raw.portfolioAssessment ?? ''),
-    };
-  },
-
-  async processOutput(): Promise<void> {
-    // Caller decides how to act on decay signals
-  },
-
-  computeRequirements: {
-    mode: 'local',
-    complexity: 'lightweight',
-  },
-
-  agentType: 'claude-code',
-  timeout: 120_000,
-  captureToolCalls: true,
-};