@polymorphism-tech/morph-spec 3.2.0 → 4.3.0

package/src/lib/context/context-optimizer.js

@@ -0,0 +1,212 @@
+/**
+ * Context Optimizer — Selective context loading strategy
+ *
+ * Provides intelligent recommendations for reducing context window usage:
+ * - selectStandards: pick only relevant standards for a feature type
+ * - selectTemplates: pick only relevant templates
+ * - suggestOptimizations: compare current vs optimal context, return savings
+ *
+ * Connects to standards resolver and template registry.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const STANDARDS_DIR = join(process.cwd(), 'framework/standards');
+const TEMPLATES_REGISTRY = join(process.cwd(), 'framework/templates/REGISTRY.json');
+
+// Average token cost estimates per file type
+const TOKEN_ESTIMATES = {
+  standard_file: 2000,
+  template_file: 1500,
+  claude_md: 23000,
+  spec_file: 8000,
+  decisions_file: 3000
+};
+
+// Feature type → relevant standards mapping
+const STANDARDS_BY_FEATURE_TYPE = {
+  backend: [
+    'coding.md', 'architecture.md', 'dotnet10-compatibility.md',
+    'integration/api/rest-design.md'
+  ],
+  frontend: [
+    'coding.md', 'blazor-components.md', 'blazor-state.md',
+    'css-architecture.md', 'css-design-system.md'
+  ],
+  database: [
+    'coding.md', 'ef-core.md', 'architecture.md'
+  ],
+  infrastructure: [
+    'azure.md', 'bicep.md', 'devops.md'
+  ],
+  authentication: [
+    'coding.md', 'architecture.md', 'dotnet10-compatibility.md',
+    'integration/api/rest-design.md'
+  ],
+  fullstack: [
+    'coding.md', 'architecture.md', 'blazor-components.md',
+    'ef-core.md', 'dotnet10-compatibility.md'
+  ],
+  observability: [
+    'observability/monitoring.md', 'observability/logging.md',
+    'observability/tracing.md', 'observability/metrics.md'
+  ],
+  event_driven: [
+    'integration/event-driven/service-bus.md',
+    'integration/event-driven/cqrs.md'
+  ]
+};
+
+// ============================================================================
+// Standards Selection
+// ============================================================================
+
+/**
+ * Select minimal relevant standards for a given feature type
+ * @param {string} featureType - Feature type keyword
+ * @param {Object} [opts]
+ * @param {string[]} [opts.extraKeywords] - Additional keywords for selection
+ * @returns {Object} { selected: string[], skipped: string[], estimatedTokens: number }
+ */
+export function selectStandards(featureType, { extraKeywords = [] } = {}) {
+  const typeKey = detectFeatureCategory(featureType, extraKeywords);
+  const selected = STANDARDS_BY_FEATURE_TYPE[typeKey] || STANDARDS_BY_FEATURE_TYPE.fullstack;
+
+  // Check which selected files actually exist
+  const existing = selected.filter(f => {
+    const fullPath = join(STANDARDS_DIR, f);
+    return existsSync(fullPath);
+  });
+
+  // Estimate all standard files count for skipped calculation
+  const allStandards = getAllStandardsCount();
+  const skippedCount = allStandards - existing.length;
+
+  return {
+    selected: existing,
+    skipped: skippedCount,
+    featureType: typeKey,
+    estimatedTokens: existing.length * TOKEN_ESTIMATES.standard_file,
+    fullLoadTokens: allStandards * TOKEN_ESTIMATES.standard_file,
+    savings: skippedCount * TOKEN_ESTIMATES.standard_file
+  };
+}
+
+/**
+ * Select relevant templates for a feature type
+ * @param {string} featureType - Feature type keyword
+ * @returns {Object} { selected: string[], estimatedTokens: number }
+ */
+export function selectTemplates(featureType) {
+  const TEMPLATES_BY_TYPE = {
+    backend: ['dotnet-backend-service', 'dotnet-repository', 'dotnet-api-contracts'],
+    frontend: ['dotnet-blazor-component', 'dotnet-design-system'],
+    database: ['dotnet-migration', 'sql-migration'],
+    infrastructure: ['azure-container-app', 'azure-key-vault', 'azure-main-bicep'],
+    fullstack: ['dotnet-backend-service', 'dotnet-blazor-component', 'dotnet-migration']
+  };
+
+  const typeKey = detectFeatureCategory(featureType, []);
+  const selected = TEMPLATES_BY_TYPE[typeKey] || TEMPLATES_BY_TYPE.fullstack;
+
+  // Load registry to get full template count
+  let totalTemplates = 50;
+  try {
+    const registry = JSON.parse(readFileSync(TEMPLATES_REGISTRY, 'utf8'));
+    totalTemplates = (registry.templates || []).length;
+  } catch {
+    // Use estimate
+  }
+
+  return {
+    selected,
+    skipped: totalTemplates - selected.length,
+    estimatedTokens: selected.length * TOKEN_ESTIMATES.template_file,
+    fullLoadTokens: totalTemplates * TOKEN_ESTIMATES.template_file,
+    savings: (totalTemplates - selected.length) * TOKEN_ESTIMATES.template_file
+  };
+}
+
+/**
+ * Suggest context optimizations based on current vs optimal load
+ * @param {Object} current - Current context state
+ * @param {number} current.totalTokens - Current token count
+ * @param {number} current.standardsCount - Number of standards currently loaded
+ * @param {number} current.templatesCount - Number of templates currently loaded
+ * @param {string} featureType - Feature type for optimal selection
+ * @returns {Object} Optimization suggestions with savings estimates
+ */
+export function suggestOptimizations(current, featureType) {
+  const optimalStandards = selectStandards(featureType);
+  const optimalTemplates = selectTemplates(featureType);
+  const suggestions = [];
+
+  // Claude.md optimization
+  if (current.totalTokens > 50000) {
+    suggestions.push({
+      type: 'priming_file',
+      title: 'Use priming file instead of full CLAUDE.md',
+      description: 'Replace 23K token CLAUDE.md with a 500-token priming file',
+      savings: TOKEN_ESTIMATES.claude_md - 500,
+      priority: 'high',
+      command: 'morph-spec prime feature'
+    });
+  }
+
+  // Standards optimization
+  if (current.standardsCount > optimalStandards.selected.length + 3) {
+    suggestions.push({
+      type: 'standards_subset',
+      title: `Load only ${optimalStandards.selected.length} relevant standards`,
+      description: `Currently loading ${current.standardsCount} standards. Only ${optimalStandards.selected.length} are needed for ${featureType} features.`,
+      savings: optimalStandards.savings,
+      priority: 'medium',
+      selectedStandards: optimalStandards.selected
+    });
+  }
+
+  // Context bundle for large sessions
+  if (current.totalTokens > 100000) {
+    suggestions.push({
+      type: 'context_bundle',
+      title: 'Create context bundle checkpoint',
+      description: 'Compress current context (180K → ~15K tokens) for session resume',
+      savings: current.totalTokens - 15000,
+      priority: 'critical',
+      command: 'morph-spec bundle create'
+    });
+  }
+
+  const totalSavings = suggestions.reduce((sum, s) => sum + s.savings, 0);
+  const optimizedTokens = Math.max(current.totalTokens - totalSavings, 5000);
+
+  return {
+    currentTokens: current.totalTokens,
+    optimizedTokens,
+    totalSavings,
+    savingsPercent: Math.round(totalSavings / current.totalTokens * 100),
+    suggestions: suggestions.sort((a, b) => b.savings - a.savings)
+  };
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function detectFeatureCategory(featureType, extraKeywords) {
+  const text = (featureType + ' ' + extraKeywords.join(' ')).toLowerCase();
+
+  if (/auth|login|jwt|oauth|identity/.test(text)) return 'authentication';
+  if (/blazor|frontend|ui|component|razor/.test(text)) return 'frontend';
+  if (/migration|ef.core|database|entity/.test(text)) return 'database';
+  if (/bicep|azure|infra|container|devops/.test(text)) return 'infrastructure';
+  if (/service.bus|cqrs|event.sourcing|pub.sub/.test(text)) return 'event_driven';
+  if (/monitor|logging|trace|metric|appinsight/.test(text)) return 'observability';
+  if (/api|endpoint|controller|rest/.test(text)) return 'backend';
+  return 'fullstack';
+}
+
+function getAllStandardsCount() {
+  return 30; // Known approximate count
+}

package/src/lib/context/context-tracker.js

@@ -0,0 +1,273 @@
+/**
+ * Context Tracker — Real-time token monitoring
+ *
+ * Tracks token usage per thread/session, detects peak usage moments,
+ * calculates averages, and identifies optimization opportunities.
+ * Integrates with analytics-engine to record context events.
+ */
+
+import { recordContextEvent } from '../analytics/analytics-engine.js';
+import { addThreadEvent } from '../threads/thread-manager.js';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const WARNING_THRESHOLD = 0.75;   // 75% of context window
+const CRITICAL_THRESHOLD = 0.90;  // 90% of context window
+
+export const OPTIMIZATION_STRATEGIES = {
+  MCP_HYGIENE: 'mcp_hygiene',
+  MICRO_AGENT: 'micro_agent_switch',
+  CONTEXT_BUNDLE: 'context_bundle',
+  PRIMING_FILE: 'priming_file',
+  STANDARDS_SUBSET: 'standards_subset'
+};
+
+// In-memory session state (not persisted — resets each session)
+const sessions = new Map();
+
+// ============================================================================
+// Session Management
+// ============================================================================
+
+/**
+ * Start tracking a session
+ * @param {Object} opts
+ * @param {string} opts.feature - Feature name
+ * @param {string} [opts.threadId] - Thread ID
+ * @param {number} [opts.contextWindow=200000] - Model context window size
+ * @param {string} [opts.model] - Model name
+ * @returns {string} Session ID
+ */
+export function startSession({ feature, threadId = null, contextWindow = 200000, model = 'claude-sonnet-4-6' }) {
+  const sessionId = threadId || `session-${Date.now()}`;
+
+  sessions.set(sessionId, {
+    sessionId,
+    feature,
+    threadId,
+    model,
+    contextWindow,
+    startedAt: new Date().toISOString(),
+    peakUsage: 0,
+    currentUsage: 0,
+    samples: [],
+    events: []
+  });
+
+  recordContextEvent({
+    type: 'context_session_started',
+    feature,
+    threadId,
+    data: { model, contextWindow }
+  });
+
+  return sessionId;
+}
+
+/**
+ * Record a token usage sample for a session
+ * @param {string} sessionId - Session ID
+ * @param {Object} usage
+ * @param {number} usage.tokensUsed - Total tokens in context
+ * @param {Object} [usage.breakdown] - Token breakdown by source
+ * @returns {Object} Current session state with any optimization recommendations
+ */
+export function recordTokenUsage(sessionId, { tokensUsed, breakdown = {} }) {
+  const session = sessions.get(sessionId);
+  if (!session) {
+    throw new Error(`Session not found: ${sessionId}`);
+  }
+
+  const utilization = tokensUsed / session.contextWindow;
+  session.currentUsage = tokensUsed;
+
+  if (tokensUsed > session.peakUsage) {
+    session.peakUsage = tokensUsed;
+  }
+
+  const sample = {
+    timestamp: new Date().toISOString(),
+    tokensUsed,
+    utilization: Math.round(utilization * 100) / 100,
+    breakdown
+  };
+  session.samples.push(sample);
+
+  // Record to analytics
+  recordContextEvent({
+    type: 'token_usage',
+    feature: session.feature,
+    threadId: session.threadId,
+    data: { tokensUsed, utilization, breakdown }
+  });
+
+  // Check thresholds and identify opportunities
+  const recommendations = identifyOptimizations(session, utilization);
+
+  if (utilization >= CRITICAL_THRESHOLD) {
+    const event = { type: 'context_critical', utilization, recommendations };
+    session.events.push(event);
+
+    if (session.threadId) {
+      try {
+        addThreadEvent(session.threadId, 'context_critical', { utilization });
+      } catch {
+        // Thread may not exist in state yet
+      }
+    }
+
+    recordContextEvent({
+      type: 'context_critical',
+      feature: session.feature,
+      threadId: session.threadId,
+      data: { utilization, tokensUsed, recommendations }
+    });
+  } else if (utilization >= WARNING_THRESHOLD) {
+    recordContextEvent({
+      type: 'context_warning',
+      feature: session.feature,
+      threadId: session.threadId,
+      data: { utilization, tokensUsed }
+    });
+  }
+
+  return { session, recommendations };
+}
+
+/**
+ * End a session and record summary
+ * @param {string} sessionId - Session ID
+ * @returns {Object} Session summary
+ */
+export function endSession(sessionId) {
+  const session = sessions.get(sessionId);
+  if (!session) return null;
+
+  const avgUsage = session.samples.length > 0
+    ? Math.round(session.samples.reduce((sum, s) => sum + s.tokensUsed, 0) / session.samples.length)
+    : 0;
+
+  const summary = {
+    sessionId,
+    feature: session.feature,
+    model: session.model,
+    startedAt: session.startedAt,
+    endedAt: new Date().toISOString(),
+    peakUsage: session.peakUsage,
+    avgUsage,
+    samples: session.samples.length,
+    criticalMoments: session.events.filter(e => e.type === 'context_critical').length
+  };
+
+  recordContextEvent({
+    type: 'context_session_ended',
+    feature: session.feature,
+    threadId: session.threadId,
+    data: summary
+  });
+
+  sessions.delete(sessionId);
+  return summary;
+}
+
+// ============================================================================
+// Optimization Analysis
+// ============================================================================
+
+/**
+ * Identify context optimization opportunities based on current utilization
+ * @param {Object} session - Session object
+ * @param {number} utilization - Current utilization (0-1)
+ * @returns {Array} Array of optimization recommendations
+ */
+export function identifyOptimizations(session, utilization) {
+  const recommendations = [];
+
+  if (utilization >= 0.5) {
+    recommendations.push({
+      strategy: OPTIMIZATION_STRATEGIES.MCP_HYGIENE,
+      description: 'Disable unused MCP servers to free ~15-30K tokens',
+      estimatedSavings: '15,000-30,000 tokens',
+      priority: utilization >= 0.75 ? 'high' : 'medium'
+    });
+  }
+
+  if (utilization >= 0.65) {
+    recommendations.push({
+      strategy: OPTIMIZATION_STRATEGIES.STANDARDS_SUBSET,
+      description: 'Load only task-relevant standards instead of all standards',
+      estimatedSavings: '10,000-20,000 tokens',
+      priority: 'medium'
+    });
+  }
+
+  if (utilization >= 0.80) {
+    recommendations.push({
+      strategy: OPTIMIZATION_STRATEGIES.MICRO_AGENT,
+      description: 'Switch to a micro-agent with minimal context for focused tasks',
+      estimatedSavings: '50,000-100,000 tokens',
+      priority: 'high'
+    });
+    recommendations.push({
+      strategy: OPTIMIZATION_STRATEGIES.PRIMING_FILE,
+      description: 'Use a 500-token priming file instead of full CLAUDE.md',
+      estimatedSavings: '22,000 tokens',
+      priority: 'high'
+    });
+  }
+
+  if (utilization >= 0.90) {
+    recommendations.push({
+      strategy: OPTIMIZATION_STRATEGIES.CONTEXT_BUNDLE,
+      description: 'Create a context bundle checkpoint (180K → 15K token compression)',
+      estimatedSavings: '165,000 tokens',
+      priority: 'critical'
+    });
+  }
+
+  return recommendations;
+}
+
+/**
+ * Get statistics for a session
+ * @param {string} sessionId - Session ID
+ * @returns {Object|null} Session statistics
+ */
+export function getSessionStats(sessionId) {
+  const session = sessions.get(sessionId);
+  if (!session) return null;
+
+  const avgUsage = session.samples.length > 0
+    ? Math.round(session.samples.reduce((sum, s) => sum + s.tokensUsed, 0) / session.samples.length)
+    : 0;
+
+  return {
+    sessionId,
+    feature: session.feature,
+    model: session.model,
+    contextWindow: session.contextWindow,
+    currentUsage: session.currentUsage,
+    peakUsage: session.peakUsage,
+    avgUsage,
+    peakUtilization: Math.round(session.peakUsage / session.contextWindow * 100),
+    currentUtilization: Math.round(session.currentUsage / session.contextWindow * 100),
+    samples: session.samples.length
+  };
+}
+
+/**
+ * Get all active sessions
+ * @returns {Array} Active session summaries
+ */
+export function getActiveSessions() {
+  return Array.from(sessions.values()).map(s => ({
+    sessionId: s.sessionId,
+    feature: s.feature,
+    model: s.model,
+    currentUsage: s.currentUsage,
+    peakUsage: s.peakUsage,
+    utilization: Math.round(s.currentUsage / s.contextWindow * 100)
+  }));
+}

package/src/lib/context/core-four-tracker.js

@@ -0,0 +1,201 @@
+/**
+ * Core Four Tracker — Context/Model/Prompt/Tools tracking
+ *
+ * Tracks the "Core Four" metrics that determine LLM behavior:
+ *   Context  — Token count breakdown by source
+ *   Model    — Model name and context window
+ *   Prompt   — Current request summary
+ *   Tools    — Tool usage counts (Read/Write/Edit/Bash/etc.)
+ *
+ * Reads from analytics-engine for historical data.
+ * Formats output for ASCII terminal display.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { recordContextEvent } from '../analytics/analytics-engine.js';
+
+// In-memory state for current session
+let currentSession = {
+  model: null,
+  contextWindow: 200000,
+  contextBreakdown: {},
+  promptSummary: '',
+  toolCalls: {}
+};
+
+// ============================================================================
+// Session Initialization
+// ============================================================================
+
+/**
+ * Initialize Core Four tracking for a session
+ * @param {Object} opts
+ * @param {string} opts.model - Model name
+ * @param {number} [opts.contextWindow] - Context window size
+ * @param {string} [opts.feature] - Feature being worked on
+ */
+export function initCoreFour({ model, contextWindow = 200000, feature = '' }) {
+  currentSession = {
+    model,
+    contextWindow,
+    feature,
+    contextBreakdown: {
+      'CLAUDE.md': 0,
+      standards: 0,
+      templates: 0,
+      spec: 0,
+      conversation: 0,
+      other: 0
+    },
+    promptSummary: '',
+    toolCalls: {
+      Read: 0,
+      Write: 0,
+      Edit: 0,
+      Bash: 0,
+      Glob: 0,
+      Grep: 0,
+      Task: 0,
+      other: 0
+    },
+    startedAt: new Date().toISOString()
+  };
+}
+
+// ============================================================================
+// Tracking Updates
+// ============================================================================
+
+/**
+ * Update context breakdown by source
+ * @param {Object} breakdown - { sourceName: tokenCount }
+ */
+export function updateContextBreakdown(breakdown) {
+  for (const [source, tokens] of Object.entries(breakdown)) {
+    currentSession.contextBreakdown[source] = tokens;
+  }
+}
+
+/**
+ * Update current prompt summary
+ * @param {string} summary - Brief summary of current request
+ */
+export function updatePromptSummary(summary) {
+  currentSession.promptSummary = summary;
+}
+
+/**
+ * Record a tool call
+ * @param {string} toolName - Tool name (Read|Write|Edit|Bash|etc.)
+ */
+export function recordToolCall(toolName) {
+  const key = currentSession.toolCalls.hasOwnProperty(toolName) ? toolName : 'other';
+  currentSession.toolCalls[key] = (currentSession.toolCalls[key] || 0) + 1;
+
+  if (currentSession.feature) {
+    recordContextEvent({
+      type: 'tool_call',
+      feature: currentSession.feature,
+      data: { tool: toolName }
+    });
+  }
+}
+
+// ============================================================================
+// Display Formatting
+// ============================================================================
+
+/**
+ * Get the current Core Four state
+ * @returns {Object} Core Four metrics
+ */
+export function getCoreFour() {
+  const totalContextTokens = Object.values(currentSession.contextBreakdown)
+    .reduce((sum, v) => sum + v, 0);
+
+  const contextUtilization = currentSession.contextWindow > 0
+    ? Math.round(totalContextTokens / currentSession.contextWindow * 100)
+    : 0;
+
+  return {
+    context: {
+      total: totalContextTokens,
+      window: currentSession.contextWindow,
+      utilization: contextUtilization,
+      breakdown: currentSession.contextBreakdown
+    },
+    model: {
+      name: currentSession.model || 'unknown',
+      contextWindow: currentSession.contextWindow,
+      provider: 'Anthropic'
+    },
+    prompt: {
+      summary: currentSession.promptSummary || '(no active prompt)',
+      length: currentSession.promptSummary?.length || 0
+    },
+    tools: {
+      calls: { ...currentSession.toolCalls },
+      total: Object.values(currentSession.toolCalls).reduce((sum, v) => sum + v, 0)
+    }
+  };
+}
+
+/**
+ * Format Core Four as ASCII display string
+ * @returns {string} ASCII formatted Core Four display
+ */
+export function formatCoreFour() {
+  const { context, model, prompt, tools } = getCoreFour();
+  const lines = [];
+
+  lines.push('╔══════════════════════════════════════════╗');
+  lines.push('║          CORE FOUR DASHBOARD             ║');
+  lines.push('╠══════════════════════════════════════════╣');
+
+  // Context
+  lines.push('║ CONTEXT                                  ║');
+  const bar = buildProgressBar(context.utilization, 30);
+  lines.push(`║  ${bar} ${String(context.utilization).padStart(3)}%          ║`);
+  lines.push(`║  Total: ${String(context.total.toLocaleString()).padEnd(10)} Window: ${String(context.window.toLocaleString()).padEnd(8)}║`);
+
+  // Breakdown
+  for (const [src, tokens] of Object.entries(context.breakdown)) {
+    if (tokens > 0) {
+      const pct = Math.round(tokens / Math.max(context.total, 1) * 100);
+      lines.push(`║    ${src.padEnd(14)} ${String(tokens.toLocaleString()).padStart(8)} (${String(pct).padStart(2)}%)     ║`);
+    }
+  }
+  lines.push('║                                          ║');
+
+  // Model
+  lines.push('║ MODEL                                    ║');
+  lines.push(`║  ${model.name.padEnd(40)}║`);
+  lines.push(`║  Window: ${String(model.contextWindow.toLocaleString()).padEnd(32)}║`);
+  lines.push('║                                          ║');
+
+  // Prompt
+  lines.push('║ PROMPT                                   ║');
+  const pStr = (prompt.summary || '—').substring(0, 38);
+  lines.push(`║  ${pStr.padEnd(40)}║`);
+  lines.push('║                                          ║');
+
+  // Tools
+  lines.push('║ TOOLS                                    ║');
+  lines.push(`║  Total calls: ${String(tools.total).padEnd(27)}║`);
+  for (const [tool, count] of Object.entries(tools.calls)) {
+    if (count > 0) {
+      lines.push(`║    ${tool.padEnd(10)} ${String(count).padStart(4)} calls${' '.repeat(20)}║`);
+    }
+  }
+  lines.push('╚══════════════════════════════════════════╝');
+
+  return lines.join('\n');
+}
+
+function buildProgressBar(pct, width) {
+  const filled = Math.round(pct / 100 * width);
+  const empty = width - filled;
+  const color = pct >= 90 ? '█' : pct >= 75 ? '▓' : '░';
+  return '[' + color.repeat(filled) + '░'.repeat(empty) + ']';
+}