create-genia-os 2.4.0 → 3.0.0

package/template/.aiox-core/workflow-intelligence/engine/suggestion-engine.js

@@ -0,0 +1,797 @@
+/**
+ * @module SuggestionEngine
+ * @description High-level suggestion engine for the *next task
+ * @story WIS-3 - *next Task Implementation
+ * @story WIS-5 - Pattern Capture Integration
+ * @version 1.1.0
+ *
+ * @example
+ * const { SuggestionEngine } = require('./suggestion-engine');
+ * const engine = new SuggestionEngine();
+ *
+ * const context = await engine.buildContext({ storyOverride: 'path/to/story.md' });
+ * const result = await engine.suggestNext(context);
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// Lazy-loaded dependencies for performance
+let wis = null;
+let SessionContextLoader = null;
+let learning = null;
+let WorkflowStateManager = null;
+
+/**
+ * Default cache TTL for suggestions (5 minutes)
+ * @type {number}
+ */
+const SUGGESTION_CACHE_TTL = 5 * 60 * 1000;
+
+/**
+ * Low confidence threshold for marking suggestions as "uncertain"
+ * @type {number}
+ */
+const LOW_CONFIDENCE_THRESHOLD = 0.5;
+
+/**
+ * SuggestionEngine class for generating context-aware command suggestions
+ */
+class SuggestionEngine {
+  /**
+   * Create a SuggestionEngine instance
+   * @param {Object} options - Configuration options
+   * @param {number} options.cacheTTL - Cache time-to-live in milliseconds
+   * @param {boolean} options.lazyLoad - Whether to lazy-load dependencies
+   * @param {boolean} options.useLearnedPatterns - Whether to use learned patterns (default: true)
+   * @param {number} options.learnedPatternBoost - Confidence boost for learned patterns (default: 0.15)
+   */
+  constructor(options = {}) {
+    this.cacheTTL = options.cacheTTL || SUGGESTION_CACHE_TTL;
+    this.lazyLoad = options.lazyLoad !== false;
+    this.useLearnedPatterns = options.useLearnedPatterns !== false;
+    this.learnedPatternBoost = options.learnedPatternBoost || 0.15;
+    this.suggestionCache = null;
+    this.cacheTimestamp = null;
+    this.cacheKey = null;
+
+    // Load dependencies immediately if not lazy loading
+    if (!this.lazyLoad) {
+      this._loadDependencies();
+    }
+  }
+
+  /**
+   * Lazy-load WIS and session dependencies
+   * @private
+   */
+  _loadDependencies() {
+    if (!wis) {
+      try {
+        wis = require('../index');
+      } catch (error) {
+        console.warn('[SuggestionEngine] Failed to load WIS module:', error.message);
+        wis = null;
+      }
+    }
+
+    if (!SessionContextLoader) {
+      try {
+        SessionContextLoader = require('../../core/session/context-loader');
+      } catch (error) {
+        console.warn('[SuggestionEngine] Failed to load SessionContextLoader:', error.message);
+        SessionContextLoader = null;
+      }
+    }
+
+    if (!learning && this.useLearnedPatterns) {
+      try {
+        learning = require('../learning');
+      } catch (error) {
+        console.warn('[SuggestionEngine] Failed to load learning module:', error.message);
+        learning = null;
+      }
+    }
+
+    if (!WorkflowStateManager) {
+      try {
+        ({ WorkflowStateManager } = require('../../development/scripts/workflow-state-manager'));
+      } catch (error) {
+        console.warn('[SuggestionEngine] Failed to load WorkflowStateManager:', error.message);
+        WorkflowStateManager = null;
+      }
+    }
+  }
+
+  /**
+   * Build context from multiple sources
+   * @param {Object} options - Context building options
+   * @param {string} options.storyOverride - Explicit story path (optional)
+   * @param {boolean} options.autoDetect - Whether to auto-detect context (default: true)
+   * @param {string} options.agentId - Current agent ID (optional)
+   * @returns {Promise<Object>} Built context object
+   */
+  async buildContext(options = {}) {
+    this._loadDependencies();
+
+    const context = {
+      agentId: options.agentId || this._detectCurrentAgent(),
+      lastCommand: null,
+      lastCommands: [],
+      storyPath: null,
+      branch: null,
+      projectState: {},
+    };
+
+    // 1. Load session context if available
+    if (options.autoDetect !== false && SessionContextLoader) {
+      try {
+        const loader = new SessionContextLoader();
+        const sessionContext = loader.loadContext(context.agentId);
+
+        context.lastCommands = sessionContext.lastCommands || [];
+        context.lastCommand = context.lastCommands[context.lastCommands.length - 1] || null;
+        context.storyPath = sessionContext.currentStory || null;
+        context.workflowActive = sessionContext.workflowActive || null;
+      } catch (error) {
+        console.warn('[SuggestionEngine] Failed to load session context:', error.message);
+      }
+    }
+
+    // 2. Story override takes precedence
+    if (options.storyOverride) {
+      const resolvedPath = this._resolveStoryPath(options.storyOverride);
+      if (resolvedPath) {
+        context.storyPath = resolvedPath;
+      }
+    }
+
+    // 3. Detect git branch
+    context.branch = this._detectGitBranch();
+
+    // 4. Build project state
+    context.projectState = await this._buildProjectState(context);
+
+    return context;
+  }
+
+  /**
+   * Get suggestions for next commands based on context
+   * @param {Object} context - Current session context
+   * @returns {Promise<Object>} Suggestion result
+   */
+  async suggestNext(context) {
+    this._loadDependencies();
+    const runtimeNext = this._getRuntimeNextRecommendation(context);
+
+    // Check cache first
+    const cacheKey = this._generateCacheKey(context);
+    if (this._isCacheValid(cacheKey)) {
+      return this._withRuntimeRecommendation(this.suggestionCache, runtimeNext);
+    }
+
+    // Default result for when WIS is not available
+    const defaultResult = {
+      workflow: null,
+      currentState: null,
+      confidence: 0,
+      suggestions: [],
+      isUncertain: true,
+      message: 'Unable to determine workflow context',
+    };
+
+    if (!wis) {
+      return this._withRuntimeRecommendation(defaultResult, runtimeNext);
+    }
+
+    try {
+      // Get suggestions from WIS
+      const suggestions = wis.getSuggestions(context);
+
+      if (!suggestions || suggestions.length === 0) {
+        return this._withRuntimeRecommendation({
+          ...defaultResult,
+          message: 'No matching workflow found for current context',
+        }, runtimeNext);
+      }
+
+      // Get workflow match info
+      const commands = context.lastCommands || (context.lastCommand ? [context.lastCommand] : []);
+      const match = wis.matchWorkflow(commands);
+
+      // Calculate overall confidence
+      const _avgConfidence =
+        suggestions.length > 0
+          ? suggestions.reduce((sum, s) => sum + (s.confidence || 0), 0) / suggestions.length
+          : 0;
+
+      // Format base suggestions
+      let formattedSuggestions = suggestions.map((s, index) => ({
+        command: `*${s.command}`,
+        args: this._interpolateArgs(s.args_template, context),
+        description: s.description || '',
+        confidence: Math.round((s.confidence || 0) * 100) / 100,
+        priority: s.priority || index + 1,
+        source: 'workflow',
+      }));
+
+      // Apply learned pattern boost (WIS-5)
+      if (this.useLearnedPatterns && learning) {
+        formattedSuggestions = this._applyLearnedPatternBoost(formattedSuggestions, context);
+      }
+
+      // Re-sort after boost
+      formattedSuggestions.sort((a, b) => b.confidence - a.confidence);
+
+      // Recalculate average confidence
+      const finalAvgConfidence =
+        formattedSuggestions.length > 0
+          ? formattedSuggestions.reduce((sum, s) => sum + s.confidence, 0) /
+            formattedSuggestions.length
+          : 0;
+
+      // Build result
+      let result = {
+        workflow: match?.name || suggestions[0]?.workflow || null,
+        currentState: suggestions[0]?.state || null,
+        confidence: Math.round(finalAvgConfidence * 100) / 100,
+        suggestions: formattedSuggestions,
+        isUncertain: finalAvgConfidence < LOW_CONFIDENCE_THRESHOLD,
+        message: null,
+      };
+
+      result = this._withRuntimeRecommendation(result, runtimeNext);
+
+      // Cache the result
+      this._cacheResult(cacheKey, result);
+
+      return result;
+    } catch (error) {
+      console.error('[SuggestionEngine] Error getting suggestions:', error.message);
+      return {
+        ...defaultResult,
+        message: `Error: ${error.message}`,
+      };
+    }
+  }
+
+  /**
+   * Build runtime execution signals for deterministic next-action recommendation
+   * @param {Object} context - Current session context
+   * @returns {Object} Normalized runtime signals
+   * @private
+   */
+  _buildRuntimeSignals(context = {}) {
+    const projectState = context.projectState || {};
+    const hasUncommitted =
+      typeof projectState.hasUncommittedChanges === 'boolean'
+        ? projectState.hasUncommittedChanges
+        : false;
+
+    const baseSignals = {
+      story_status:
+        projectState.story_status || projectState.storyStatus || (projectState.activeStory ? 'in_progress' : 'unknown'),
+      qa_status: projectState.qa_status || projectState.qaStatus || 'unknown',
+      ci_status:
+        projectState.ci_status ||
+        projectState.ciStatus ||
+        (projectState.failingTests ? 'failed' : 'unknown'),
+      has_uncommitted_changes: hasUncommitted,
+    };
+
+    return {
+      ...baseSignals,
+      ...(context.executionSignals || {}),
+    };
+  }
+
+  /**
+   * Get deterministic runtime-first recommendation if signals are available
+   * @param {Object} context - Current session context
+   * @returns {Object|null} Runtime recommendation or null
+   * @private
+   */
+  _getRuntimeNextRecommendation(context = {}) {
+    if (!WorkflowStateManager) {
+      return null;
+    }
+
+    try {
+      const manager = new WorkflowStateManager();
+      const runtimeSignals = this._buildRuntimeSignals(context);
+      const recommendation = manager.getNextActionRecommendation(runtimeSignals, {
+        story: context.storyPath || '',
+      });
+
+      if (!recommendation || recommendation.state === 'unknown') {
+        return null;
+      }
+
+      return recommendation;
+    } catch (_error) {
+      return null;
+    }
+  }
+
+  /**
+   * Merge runtime-first deterministic recommendation into suggestion result.
+   * @param {Object} result - Suggestion result
+   * @param {Object|null} runtimeNext - Runtime recommendation
+   * @returns {Object} Enhanced result
+   * @private
+   */
+  _withRuntimeRecommendation(result, runtimeNext) {
+    if (!result || !runtimeNext) {
+      return result;
+    }
+
+    const runtimeSuggestion = {
+      command: runtimeNext.command,
+      args: '',
+      description: runtimeNext.rationale,
+      confidence: runtimeNext.confidence,
+      priority: 0,
+      source: 'runtime_first',
+      agent: runtimeNext.agent,
+      executionState: runtimeNext.state,
+    };
+
+    const existing = Array.isArray(result.suggestions) ? result.suggestions : [];
+    const normalizedRuntimeCommand = String(runtimeSuggestion.command || '').trim().toLowerCase();
+    const deduped = existing.filter(
+      (s) => String((s.command || '') + (s.args ? ` ${s.args}` : '')).trim().toLowerCase() !== normalizedRuntimeCommand,
+    );
+
+    return {
+      ...result,
+      suggestions: [runtimeSuggestion, ...deduped],
+      confidence: Math.max(result.confidence || 0, runtimeNext.confidence || 0),
+      isUncertain: false,
+      runtimeState: runtimeNext.state,
+    };
+  }
+
+  /**
+   * Detect current active agent from environment or session
+   * @returns {string} Agent ID
+   * @private
+   */
+  _detectCurrentAgent() {
+    // Check environment variable first
+    if (process.env.AIOX_CURRENT_AGENT) {
+      return process.env.AIOX_CURRENT_AGENT.replace('@', '');
+    }
+
+    // Default to 'dev' if unknown
+    return 'dev';
+  }
+
+  /**
+   * Resolve and validate story path
+   * @param {string} storyPath - Story path to resolve
+   * @returns {string|null} Resolved path or null if invalid
+   * @private
+   */
+  _resolveStoryPath(storyPath) {
+    if (!storyPath) return null;
+
+    // Handle relative paths
+    const resolved = path.isAbsolute(storyPath)
+      ? storyPath
+      : path.resolve(process.cwd(), storyPath);
+
+    // Validate file exists
+    try {
+      if (fs.existsSync(resolved)) {
+        return resolved;
+      }
+    } catch (_error) {
+      // File doesn't exist
+    }
+
+    console.warn(`[SuggestionEngine] Story path not found: ${storyPath}`);
+    return null;
+  }
+
+  /**
+   * Detect current git branch
+   * @returns {string|null} Branch name or null
+   * @private
+   */
+  _detectGitBranch() {
+    try {
+      const gitHeadPath = path.join(process.cwd(), '.git', 'HEAD');
+      if (fs.existsSync(gitHeadPath)) {
+        const content = fs.readFileSync(gitHeadPath, 'utf8').trim();
+        if (content.startsWith('ref: refs/heads/')) {
+          return content.replace('ref: refs/heads/', '');
+        }
+      }
+    } catch (_error) {
+      // Git not available or not a git repo
+    }
+    return null;
+  }
+
+  /**
+   * Build project state object
+   * @param {Object} context - Current context
+   * @returns {Promise<Object>} Project state
+   * @private
+   */
+  async _buildProjectState(context) {
+    const state = {
+      activeStory: !!context.storyPath,
+      hasUncommittedChanges: false,
+      failingTests: false,
+      workflowPhase: null,
+    };
+
+    // Check for uncommitted changes
+    try {
+      const gitStatusPath = path.join(process.cwd(), '.git', 'index');
+      if (fs.existsSync(gitStatusPath)) {
+        // Simple check - if there are modified files in git status
+        // For production, would use git status command
+        state.hasUncommittedChanges = true; // Assume true for now
+      }
+    } catch (_error) {
+      // Ignore
+    }
+
+    // Infer workflow phase from last command
+    if (context.lastCommand) {
+      const cmd = context.lastCommand.toLowerCase();
+      if (cmd.includes('develop') || cmd.includes('implement')) {
+        state.workflowPhase = 'development';
+      } else if (cmd.includes('review') || cmd.includes('qa')) {
+        state.workflowPhase = 'review';
+      } else if (cmd.includes('push') || cmd.includes('pr') || cmd.includes('deploy')) {
+        state.workflowPhase = 'deployment';
+      } else if (cmd.includes('create') || cmd.includes('story') || cmd.includes('epic')) {
+        state.workflowPhase = 'planning';
+      }
+    }
+
+    return state;
+  }
+
+  /**
+   * Interpolate argument templates with context values
+   * @param {string} argsTemplate - Template string with ${var} placeholders
+   * @param {Object} context - Context for interpolation
+   * @returns {string} Interpolated arguments
+   * @private
+   */
+  _interpolateArgs(argsTemplate, context) {
+    if (!argsTemplate) return '';
+
+    return argsTemplate
+      .replace(/\$\{story_path\}/g, context.storyPath || '')
+      .replace(/\$\{epic_path\}/g, context.epicPath || '')
+      .replace(/\$\{doc_path\}/g, context.docPath || '')
+      .replace(/\$\{file_path\}/g, context.filePath || '')
+      .replace(/\$\{feature_name\}/g, context.featureName || '')
+      .replace(/\$\{topic\}/g, context.topic || '')
+      .replace(/\$\{branch\}/g, context.branch || '')
+      .trim();
+  }
+
+  /**
+   * Generate cache key from context
+   * @param {Object} context - Context object
+   * @returns {string} Cache key
+   * @private
+   */
+  _generateCacheKey(context) {
+    const keyParts = [
+      context.agentId || '',
+      context.lastCommand || '',
+      (context.lastCommands || []).slice(-3).join(','),
+      context.storyPath || '',
+      context.branch || '',
+    ];
+    return keyParts.join('|');
+  }
+
+  /**
+   * Check if cache is valid for given key
+   * @param {string} key - Cache key
+   * @returns {boolean} True if cache is valid
+   * @private
+   */
+  _isCacheValid(key) {
+    if (!this.suggestionCache || !this.cacheTimestamp || !this.cacheKey) {
+      return false;
+    }
+    if (this.cacheKey !== key) {
+      return false;
+    }
+    return Date.now() - this.cacheTimestamp < this.cacheTTL;
+  }
+
+  /**
+   * Cache suggestion result
+   * @param {string} key - Cache key
+   * @param {Object} result - Result to cache
+   * @private
+   */
+  _cacheResult(key, result) {
+    this.suggestionCache = result;
+    this.cacheTimestamp = Date.now();
+    this.cacheKey = key;
+  }
+
+  /**
+   * Apply learned pattern boost to suggestions
+   * @param {Object[]} suggestions - Base suggestions
+   * @param {Object} context - Session context
+   * @returns {Object[]} Boosted suggestions
+   * @private
+   */
+  _applyLearnedPatternBoost(suggestions, context) {
+    if (!learning) {
+      return suggestions;
+    }
+
+    try {
+      // Get commands to match against
+      const lastCommands = context.lastCommands || [];
+      if (lastCommands.length === 0 && context.lastCommand) {
+        lastCommands.push(context.lastCommand);
+      }
+
+      if (lastCommands.length === 0) {
+        return suggestions;
+      }
+
+      // Find matching learned patterns
+      const matchingPatterns = learning.findMatchingPatterns(lastCommands);
+
+      if (!matchingPatterns || matchingPatterns.length === 0) {
+        return suggestions;
+      }
+
+      // Build a map of command -> boost based on learned patterns
+      const boostMap = new Map();
+
+      for (const pattern of matchingPatterns) {
+        // Find the next command in the pattern after the current position
+        const patternSeq = pattern.sequence || [];
+        const matchIndex = this._findSequencePosition(lastCommands, patternSeq);
+
+        if (matchIndex >= 0 && matchIndex < patternSeq.length - 1) {
+          const nextCommand = patternSeq[matchIndex + 1];
+          const currentBoost = boostMap.get(nextCommand) || 0;
+
+          // Calculate boost based on pattern quality
+          const occurrenceBoost = Math.min(pattern.occurrences * 0.02, 0.1);
+          const successBoost = (pattern.successRate || 1) * 0.05;
+          const similarityBoost = (pattern.similarity || 0.5) * 0.05;
+
+          const totalBoost =
+            this.learnedPatternBoost + occurrenceBoost + successBoost + similarityBoost;
+          boostMap.set(nextCommand, Math.max(currentBoost, totalBoost));
+        }
+      }
+
+      // Apply boosts to suggestions
+      return suggestions.map((suggestion) => {
+        const cmdNormalized = suggestion.command.replace(/^\*/, '').toLowerCase();
+        const boost = boostMap.get(cmdNormalized) || 0;
+
+        if (boost > 0) {
+          return {
+            ...suggestion,
+            confidence: Math.min(1.0, suggestion.confidence + boost),
+            source: 'learned_pattern',
+            learnedBoost: Math.round(boost * 100) / 100,
+          };
+        }
+
+        return suggestion;
+      });
+    } catch (error) {
+      console.warn('[SuggestionEngine] Failed to apply learned pattern boost:', error.message);
+      return suggestions;
+    }
+  }
+
+  /**
+   * Find position of a subsequence in a pattern sequence
+   * @param {string[]} subseq - Subsequence to find
+   * @param {string[]} pattern - Full pattern sequence
+   * @returns {number} End index of match, or -1 if not found
+   * @private
+   */
+  _findSequencePosition(subseq, pattern) {
+    if (!subseq || !pattern || subseq.length === 0) {
+      return -1;
+    }
+
+    // Normalize for comparison
+    const normalizedSubseq = subseq.map((c) => c.toLowerCase().replace(/^\*/, ''));
+    const normalizedPattern = pattern.map((c) => c.toLowerCase().replace(/^\*/, ''));
+
+    // Find where the subsequence ends in the pattern
+    for (let i = 0; i <= normalizedPattern.length - normalizedSubseq.length; i++) {
+      let matches = true;
+      for (let j = 0; j < normalizedSubseq.length; j++) {
+        if (normalizedPattern[i + j] !== normalizedSubseq[j]) {
+          matches = false;
+          break;
+        }
+      }
+      if (matches) {
+        return i + normalizedSubseq.length - 1;
+      }
+    }
+
+    // Try partial match (last command matches)
+    const lastCmd = normalizedSubseq[normalizedSubseq.length - 1];
+    for (let i = 0; i < normalizedPattern.length; i++) {
+      if (normalizedPattern[i] === lastCmd) {
+        return i;
+      }
+    }
+
+    return -1;
+  }
+
+  /**
+   * Invalidate the cache
+   */
+  invalidateCache() {
+    this.suggestionCache = null;
+    this.cacheTimestamp = null;
+    this.cacheKey = null;
+  }
+
+  /**
+   * Get fallback suggestions when WIS is unavailable
+   * @param {Object} context - Context object
+   * @returns {Object} Fallback suggestions
+   */
+  getFallbackSuggestions(context) {
+    const agent = context.agentId || 'dev';
+
+    // Agent-specific fallback suggestions
+    const fallbacks = {
+      dev: [
+        {
+          command: '*help',
+          args: '',
+          description: 'Show available commands',
+          confidence: 0.3,
+          priority: 1,
+        },
+        {
+          command: '*run-tests',
+          args: '',
+          description: 'Run test suite',
+          confidence: 0.25,
+          priority: 2,
+        },
+        {
+          command: '*develop',
+          args: '',
+          description: 'Start development mode',
+          confidence: 0.2,
+          priority: 3,
+        },
+      ],
+      po: [
+        {
+          command: '*help',
+          args: '',
+          description: 'Show available commands',
+          confidence: 0.3,
+          priority: 1,
+        },
+        {
+          command: '*backlog-review',
+          args: '',
+          description: 'Review backlog',
+          confidence: 0.25,
+          priority: 2,
+        },
+        {
+          command: '*create-story',
+          args: '',
+          description: 'Create new story',
+          confidence: 0.2,
+          priority: 3,
+        },
+      ],
+      qa: [
+        {
+          command: '*help',
+          args: '',
+          description: 'Show available commands',
+          confidence: 0.3,
+          priority: 1,
+        },
+        {
+          command: '*run-tests',
+          args: '',
+          description: 'Run test suite',
+          confidence: 0.25,
+          priority: 2,
+        },
+        {
+          command: '*review-qa',
+          args: '',
+          description: 'Start QA review',
+          confidence: 0.2,
+          priority: 3,
+        },
+      ],
+      sm: [
+        {
+          command: '*help',
+          args: '',
+          description: 'Show available commands',
+          confidence: 0.3,
+          priority: 1,
+        },
+        {
+          command: '*create-next-story',
+          args: '',
+          description: 'Create next story',
+          confidence: 0.25,
+          priority: 2,
+        },
+        {
+          command: '*validate-story-draft',
+          args: '',
+          description: 'Validate story',
+          confidence: 0.2,
+          priority: 3,
+        },
+      ],
+      default: [
+        {
+          command: '*help',
+          args: '',
+          description: 'Show available commands',
+          confidence: 0.3,
+          priority: 1,
+        },
+        {
+          command: '*status',
+          args: '',
+          description: 'Show project status',
+          confidence: 0.2,
+          priority: 2,
+        },
+      ],
+    };
+
+    return {
+      workflow: null,
+      currentState: null,
+      confidence: 0.25,
+      suggestions: fallbacks[agent] || fallbacks.default,
+      isUncertain: true,
+      message: 'Using fallback suggestions - context unclear',
+    };
+  }
+}
+
+/**
+ * Create a new SuggestionEngine instance
+ * @param {Object} options - Configuration options
+ * @returns {SuggestionEngine} New engine instance
+ */
+function createSuggestionEngine(options = {}) {
+  return new SuggestionEngine(options);
+}
+
+module.exports = {
+  SuggestionEngine,
+  createSuggestionEngine,
+  SUGGESTION_CACHE_TTL,
+  LOW_CONFIDENCE_THRESHOLD,
+};