grimoire-framework 1.0.0

package/.grimoire/core/orchestration/surface-checker.js

@@ -0,0 +1,403 @@
+/**
+ * Surface Checker - Determines when Bob should surface to ask human
+ *
+ * Story 11.4: Bob Surface Criteria
+ *
+ * This module evaluates codified criteria to determine when the AI
+ * should interrupt and ask for human decision, ensuring consistent
+ * behavior regardless of LLM reasoning.
+ *
+ * @module core/orchestration/surface-checker
+ * @version 1.0.0
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+/**
+ * @typedef {Object} SurfaceContext
+ * @property {number} [estimated_cost] - Estimated cost in USD
+ * @property {string} [risk_level] - Risk level ('LOW', 'MEDIUM', 'HIGH')
+ * @property {string} [risk_details] - Details about the risk
+ * @property {number} [valid_options_count] - Number of valid options available
+ * @property {string} [options_with_tradeoffs] - Formatted options with trade-offs
+ * @property {number} [errors_in_task] - Number of consecutive errors in current task
+ * @property {string} [error_summary] - Summary of errors encountered
+ * @property {string} [action_type] - Type of action being performed
+ * @property {string} [action_description] - Description of the action
+ * @property {string} [affected_files] - Files affected by destructive action
+ * @property {string} [requested_scope] - Requested scope
+ * @property {string} [approved_scope] - Approved scope
+ * @property {string} [scope_difference] - Difference between scopes
+ * @property {boolean} [requires_api_key] - Whether operation requires API key
+ * @property {boolean} [requires_payment] - Whether operation requires payment
+ * @property {boolean} [requires_external_service] - Whether operation requires external service
+ * @property {string} [dependency_description] - Description of external dependency
+ */
+
+/**
+ * @typedef {Object} SurfaceResult
+ * @property {boolean} should_surface - Whether Bob should surface to ask human
+ * @property {string|null} criterion_id - ID of the triggered criterion (null if no surface)
+ * @property {string|null} criterion_name - Name of the triggered criterion
+ * @property {string|null} action - Action to take (null if no surface)
+ * @property {string|null} message - Interpolated message to display (null if no surface)
+ * @property {string|null} severity - Severity level (null if no surface)
+ * @property {boolean} can_bypass - Whether this criterion can be bypassed in YOLO mode
+ */
+
+/**
+ * @typedef {Object} ActionConfig
+ * @property {string} type - Action type
+ * @property {string} prompt_type - Prompt type to use
+ * @property {string|null} default - Default value
+ * @property {number} timeout_seconds - Timeout in seconds
+ * @property {string} on_timeout - Action on timeout
+ * @property {Array<{value: string, label: string}>} [options] - Options for select prompts
+ * @property {string} [required_input] - Required input for explicit confirm
+ */
+
+class SurfaceChecker {
+  /**
+   * Create a SurfaceChecker instance
+   * @param {string} [criteriaPath] - Path to criteria YAML file (optional, uses default)
+   */
+  constructor(criteriaPath = null) {
+    this.criteriaPath =
+      criteriaPath ||
+      path.join(__dirname, 'bob-surface-criteria.yaml');
+    this.criteria = null;
+    this._loaded = false;
+  }
+
+  /**
+   * Load criteria from YAML file
+   * @returns {boolean} Whether loading was successful
+   */
+  load() {
+    try {
+      if (!fs.existsSync(this.criteriaPath)) {
+        console.warn(`[SurfaceChecker] Criteria file not found: ${this.criteriaPath}`);
+        return false;
+      }
+
+      const content = fs.readFileSync(this.criteriaPath, 'utf8');
+      this.criteria = yaml.load(content);
+      this._loaded = true;
+      return true;
+    } catch (error) {
+      console.error(`[SurfaceChecker] Failed to load criteria: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Ensure criteria are loaded
+   * @private
+   */
+  _ensureLoaded() {
+    if (!this._loaded) {
+      this.load();
+    }
+  }
+
+  /**
+   * Evaluate a condition against the context
+   * @param {string} condition - Condition expression
+   * @param {SurfaceContext} context - Context to evaluate against
+   * @returns {boolean} Whether condition is met
+   */
+  evaluateCondition(condition, context) {
+    // Handle comparison operators
+    // Pattern: field operator value
+    // Supported: >, <, >=, <=, ==, !=
+
+    // Greater than
+    const gtMatch = condition.match(/^(\w+)\s*>\s*(\d+(?:\.\d+)?)$/);
+    if (gtMatch) {
+      const [, field, value] = gtMatch;
+      return (context[field] || 0) > parseFloat(value);
+    }
+
+    // Greater than or equal
+    const gteMatch = condition.match(/^(\w+)\s*>=\s*(\d+(?:\.\d+)?)$/);
+    if (gteMatch) {
+      const [, field, value] = gteMatch;
+      return (context[field] || 0) >= parseFloat(value);
+    }
+
+    // Less than
+    const ltMatch = condition.match(/^(\w+)\s*<\s*(\d+(?:\.\d+)?)$/);
+    if (ltMatch) {
+      const [, field, value] = ltMatch;
+      return (context[field] || 0) < parseFloat(value);
+    }
+
+    // Less than or equal
+    const lteMatch = condition.match(/^(\w+)\s*<=\s*(\d+(?:\.\d+)?)$/);
+    if (lteMatch) {
+      const [, field, value] = lteMatch;
+      return (context[field] || 0) <= parseFloat(value);
+    }
+
+    // Equality with string
+    const eqStrMatch = condition.match(/^(\w+)\s*==\s*['"](\w+)['"]$/);
+    if (eqStrMatch) {
+      const [, field, value] = eqStrMatch;
+      return context[field] === value;
+    }
+
+    // Equality with number
+    const eqNumMatch = condition.match(/^(\w+)\s*==\s*(\d+(?:\.\d+)?)$/);
+    if (eqNumMatch) {
+      const [, field, value] = eqNumMatch;
+      return context[field] === parseFloat(value);
+    }
+
+    // IN operator for destructive actions
+    const inMatch = condition.match(/^(\w+)\s+IN\s+(\w+)$/);
+    if (inMatch) {
+      const [, field, listName] = inMatch;
+      const list = this.criteria?.criteria?.[listName] || [];
+      return Array.isArray(list) && list.includes(context[field]);
+    }
+
+    // Scope comparison (requested_scope > approved_scope)
+    if (condition === 'requested_scope > approved_scope') {
+      const requested = context.requested_scope || '';
+      const approved = context.approved_scope || '';
+      // Compare by length or explicit scope_expanded flag
+      return context.scope_expanded === true || requested.length > approved.length;
+    }
+
+    // OR conditions
+    if (condition.includes(' OR ')) {
+      const parts = condition.split(' OR ').map((p) => p.trim());
+      return parts.some((part) => this.evaluateCondition(part, context));
+    }
+
+    // AND conditions
+    if (condition.includes(' AND ')) {
+      const parts = condition.split(' AND ').map((p) => p.trim());
+      return parts.every((part) => this.evaluateCondition(part, context));
+    }
+
+    // Boolean field check
+    if (/^[a-z_]+$/.test(condition)) {
+      return Boolean(context[condition]);
+    }
+
+    // Unknown condition - log warning and return false (safe default)
+    console.warn(`[SurfaceChecker] Unknown condition format: ${condition}`);
+    return false;
+  }
+
+  /**
+   * Interpolate message template with context values
+   * @param {string} template - Message template with ${var} placeholders
+   * @param {SurfaceContext} context - Context with values
+   * @returns {string} Interpolated message
+   */
+  interpolateMessage(template, context) {
+    if (!template) return '';
+
+    return template.replace(/\$\{(\w+)\}/g, (match, key) => {
+      if (key in context) {
+        const value = context[key];
+        // Format numbers with 2 decimal places if they're currency
+        if (typeof value === 'number' && key.includes('cost')) {
+          return value.toFixed(2);
+        }
+        return String(value ?? '');
+      }
+      return match; // Keep original if not found
+    });
+  }
+
+  /**
+   * Check if Bob should surface to ask human
+   * @param {SurfaceContext} context - Current execution context
+   * @returns {SurfaceResult} Result indicating whether to surface and how
+   */
+  shouldSurface(context) {
+    this._ensureLoaded();
+
+    // Default result - no surface needed
+    const noSurface = {
+      should_surface: false,
+      criterion_id: null,
+      criterion_name: null,
+      action: null,
+      message: null,
+      severity: null,
+      can_bypass: true,
+    };
+
+    if (!this.criteria || !this.criteria.criteria) {
+      return noSurface;
+    }
+
+    // Get evaluation order
+    const evaluationOrder = this.criteria.evaluation_order || Object.keys(this.criteria.criteria);
+
+    // Evaluate criteria in order (first match wins)
+    for (const criterionKey of evaluationOrder) {
+      const criterion = this.criteria.criteria[criterionKey];
+
+      // Skip if it's not a criterion object (e.g., destructive_actions list)
+      if (!criterion || !criterion.condition || !criterion.id) {
+        continue;
+      }
+
+      const conditionMet = this.evaluateCondition(criterion.condition, context);
+
+      if (conditionMet) {
+        return {
+          should_surface: true,
+          criterion_id: criterion.id,
+          criterion_name: criterion.name || criterionKey,
+          action: criterion.action,
+          message: this.interpolateMessage(criterion.message, context),
+          severity: criterion.severity || 'info',
+          can_bypass: criterion.bypass !== false,
+        };
+      }
+    }
+
+    return noSurface;
+  }
+
+  /**
+   * Get action configuration for a given action name
+   * @param {string} actionName - Name of the action
+   * @returns {ActionConfig|null} Action configuration or null if not found
+   */
+  getActionConfig(actionName) {
+    this._ensureLoaded();
+
+    if (!this.criteria || !this.criteria.actions) {
+      return null;
+    }
+
+    return this.criteria.actions[actionName] || null;
+  }
+
+  /**
+   * Get all criteria definitions
+   * @returns {Object} Criteria definitions
+   */
+  getCriteria() {
+    this._ensureLoaded();
+    return this.criteria?.criteria || {};
+  }
+
+  /**
+   * Get the list of destructive actions
+   * @returns {string[]} List of destructive action types
+   */
+  getDestructiveActions() {
+    this._ensureLoaded();
+    return this.criteria?.criteria?.destructive_actions || [];
+  }
+
+  /**
+   * Check if an action type is destructive
+   * @param {string} actionType - Action type to check
+   * @returns {boolean} Whether the action is destructive
+   */
+  isDestructiveAction(actionType) {
+    const destructiveActions = this.getDestructiveActions();
+    return destructiveActions.includes(actionType);
+  }
+
+  /**
+   * Get criteria metadata
+   * @returns {Object} Metadata from criteria file
+   */
+  getMetadata() {
+    this._ensureLoaded();
+    return this.criteria?.metadata || {};
+  }
+
+  /**
+   * Validate that criteria file is properly formatted
+   * @returns {{valid: boolean, errors: string[]}} Validation result
+   */
+  validate() {
+    this._ensureLoaded();
+
+    const errors = [];
+
+    if (!this.criteria) {
+      errors.push('Criteria file not loaded');
+      return { valid: false, errors };
+    }
+
+    if (!this.criteria.version) {
+      errors.push('Missing version field');
+    }
+
+    if (!this.criteria.criteria) {
+      errors.push('Missing criteria section');
+    } else {
+      // Validate each criterion
+      const criteriaEntries = Object.entries(this.criteria.criteria);
+      for (const [key, criterion] of criteriaEntries) {
+        // Skip non-criterion entries (like destructive_actions list)
+        if (Array.isArray(criterion)) continue;
+        if (!criterion || typeof criterion !== 'object') continue;
+
+        if (!criterion.id) {
+          errors.push(`Criterion '${key}' missing id field`);
+        }
+        if (!criterion.condition) {
+          errors.push(`Criterion '${key}' missing condition field`);
+        }
+        if (!criterion.action) {
+          errors.push(`Criterion '${key}' missing action field`);
+        }
+        if (!criterion.message) {
+          errors.push(`Criterion '${key}' missing message field`);
+        }
+      }
+    }
+
+    if (!this.criteria.actions) {
+      errors.push('Missing actions section');
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+    };
+  }
+}
+
+/**
+ * Create a SurfaceChecker instance and load criteria
+ * @param {string} [criteriaPath] - Optional custom path to criteria file
+ * @returns {SurfaceChecker} Loaded SurfaceChecker instance
+ */
+function createSurfaceChecker(criteriaPath = null) {
+  const checker = new SurfaceChecker(criteriaPath);
+  checker.load();
+  return checker;
+}
+
+/**
+ * Convenience function to check if should surface
+ * @param {SurfaceContext} context - Execution context
+ * @param {string} [criteriaPath] - Optional custom path to criteria file
+ * @returns {SurfaceResult} Surface check result
+ */
+function shouldSurface(context, criteriaPath = null) {
+  const checker = createSurfaceChecker(criteriaPath);
+  return checker.shouldSurface(context);
+}
+
+module.exports = {
+  SurfaceChecker,
+  createSurfaceChecker,
+  shouldSurface,
+};

package/.grimoire/core/orchestration/task-complexity-classifier.js

@@ -0,0 +1,123 @@
+/**
+ * Task Complexity Classifier
+ * Story GEMINI-INT.16 - Dynamic Model Switching
+ *
+ * Classifies task complexity for model selection.
+ */
+
+/**
+ * Complexity indicators
+ */
+const COMPLEXITY_INDICATORS = {
+  simple: {
+    keywords: ['format', 'fix typo', 'rename', 'simple', 'quick', 'minor', 'lint'],
+    patterns: [/add\s+console\.log/i, /fix\s+import/i, /update\s+version/i],
+    maxLines: 50,
+  },
+  medium: {
+    keywords: ['implement', 'add feature', 'create', 'update', 'modify', 'refactor'],
+    patterns: [/add\s+function/i, /create\s+component/i, /implement\s+\w+/i],
+    maxLines: 200,
+  },
+  complex: {
+    keywords: [
+      'architecture',
+      'design',
+      'security',
+      'optimize',
+      'performance',
+      'complex',
+      'system',
+      'integration',
+      'migrate',
+    ],
+    patterns: [/design\s+system/i, /security\s+review/i, /architect/i, /optimize/i],
+    minLines: 200,
+  },
+};
+
+class TaskComplexityClassifier {
+  constructor(config = {}) {
+    this.thresholds = {
+      simple: config.simpleThreshold || 0.3,
+      complex: config.complexThreshold || 0.7,
+    };
+  }
+
+  /**
+   * Classify task complexity
+   * @param {Object} task - Task to classify
+   * @returns {Object} Classification result
+   */
+  classify(task) {
+    const description = (task.description || '').toLowerCase();
+    const files = task.files || [];
+    const criteria = task.acceptanceCriteria || [];
+
+    const scores = {
+      simple: this._scoreLevel('simple', description, files, criteria),
+      medium: this._scoreLevel('medium', description, files, criteria),
+      complex: this._scoreLevel('complex', description, files, criteria),
+    };
+
+    // Calculate weighted score (0-1, higher = more complex)
+    const weightedScore = scores.simple * 0 + scores.medium * 0.5 + scores.complex * 1;
+
+    const totalScore = scores.simple + scores.medium + scores.complex;
+    const normalizedScore = totalScore > 0 ? weightedScore / totalScore : 0.5;
+
+    // Determine level
+    let level = 'medium';
+    if (normalizedScore < this.thresholds.simple) {
+      level = 'simple';
+    } else if (normalizedScore > this.thresholds.complex) {
+      level = 'complex';
+    }
+
+    return {
+      level,
+      score: normalizedScore,
+      scores,
+      confidence: this._calculateConfidence(scores),
+    };
+  }
+
+  _scoreLevel(level, description, files, criteria) {
+    const indicators = COMPLEXITY_INDICATORS[level];
+    let score = 0;
+
+    // Check keywords
+    for (const keyword of indicators.keywords) {
+      if (description.includes(keyword)) {
+        score += 1;
+      }
+    }
+
+    // Check patterns
+    for (const pattern of indicators.patterns) {
+      if (pattern.test(description)) {
+        score += 2;
+      }
+    }
+
+    // Check file count
+    if (level === 'simple' && files.length <= 2) score += 1;
+    if (level === 'complex' && files.length >= 5) score += 2;
+
+    // Check criteria count
+    if (level === 'simple' && criteria.length <= 3) score += 1;
+    if (level === 'complex' && criteria.length >= 7) score += 2;
+
+    return score;
+  }
+
+  _calculateConfidence(scores) {
+    const total = scores.simple + scores.medium + scores.complex;
+    if (total === 0) return 0;
+
+    const max = Math.max(scores.simple, scores.medium, scores.complex);
+    return max / total;
+  }
+}
+
+module.exports = { TaskComplexityClassifier, COMPLEXITY_INDICATORS };