@girardmedia/bootspring 2.0.36 → 2.0.37

package/core/planning/adaptive-engine.js

@@ -0,0 +1,958 @@
+/**
+ * Adaptive Planning Engine
+ *
+ * Living planning system that monitors code changes and keeps plans synchronized.
+ * Implements continuous plan awareness with drift detection and auto-refresh.
+ *
+ * @package bootspring
+ * @module core/planning/adaptive-engine
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const EventEmitter = require('events');
+
+/**
+ * Plan refresh triggers
+ */
+const REFRESH_TRIGGERS = {
+  codeChange: {
+    threshold: 10, // Number of significant changes before refresh
+    priority: 'medium',
+    documents: ['tasks', 'sprint', 'technical-spec']
+  },
+  modelChange: {
+    threshold: 1, // Any model change triggers
+    priority: 'high',
+    documents: ['prd', 'technical-spec', 'api']
+  },
+  newFeature: {
+    threshold: 1,
+    priority: 'high',
+    documents: ['prd', 'roadmap', 'tasks']
+  },
+  bugAccumulation: {
+    threshold: 5, // Number of bug fixes
+    priority: 'medium',
+    documents: ['health', 'tech-debt']
+  },
+  dependencyUpdate: {
+    threshold: 3, // Major dependency updates
+    priority: 'low',
+    documents: ['technical-spec', 'security']
+  },
+  testCoverageChange: {
+    threshold: 10, // Percentage change in coverage
+    priority: 'medium',
+    documents: ['health', 'quality']
+  },
+  securityIssue: {
+    threshold: 1, // Any security issue
+    priority: 'critical',
+    documents: ['security', 'technical-spec']
+  }
+};
+
+/**
+ * Planning layer types
+ */
+const PLANNING_LAYERS = {
+  strategic: {
+    name: 'Strategic',
+    horizon: '6-12 months',
+    documents: ['vision', 'roadmap', 'milestones'],
+    refreshCadence: 'monthly',
+    metrics: ['revenue', 'users', 'marketShare']
+  },
+  tactical: {
+    name: 'Tactical',
+    horizon: '2-6 weeks',
+    documents: ['sprint', 'tasks', 'priorities'],
+    refreshCadence: 'weekly',
+    metrics: ['velocity', 'burndown', 'blockers']
+  },
+  operational: {
+    name: 'Operational',
+    horizon: '1-7 days',
+    documents: ['daily', 'blockers', 'progress'],
+    refreshCadence: 'daily',
+    metrics: ['tasksCompleted', 'hoursLogged', 'blockers']
+  }
+};
+
+/**
+ * Drift severity levels
+ */
+const DRIFT_SEVERITY = {
+  none: { threshold: 0, action: 'none', label: 'In Sync' },
+  minor: { threshold: 0.15, action: 'suggest', label: 'Minor Drift' },
+  moderate: { threshold: 0.35, action: 'warn', label: 'Moderate Drift' },
+  significant: { threshold: 0.55, action: 'alert', label: 'Significant Drift' },
+  critical: { threshold: 0.75, action: 'require', label: 'Critical Drift' }
+};
+
+/**
+ * AdaptivePlanningEngine class
+ *
+ * Monitors codebase changes and maintains living plans
+ */
+class AdaptivePlanningEngine extends EventEmitter {
+  /**
+   * @param {Object} options - Configuration options
+   */
+  constructor(options = {}) {
+    super();
+    this.projectRoot = options.projectRoot || process.cwd();
+    this.planningDir = options.planningDir || path.join(this.projectRoot, 'planning');
+    this.stateFile = path.join(this.planningDir, '.planning-state.json');
+    this.state = null;
+    this.changeBuffer = [];
+    this.isWatching = false;
+  }
+
+  /**
+   * Initialize the adaptive planning engine
+   */
+  async initialize() {
+    await this.loadState();
+    return this;
+  }
+
+  /**
+   * Load planning state from disk
+   */
+  async loadState() {
+    try {
+      const content = await fs.readFile(this.stateFile, 'utf-8');
+      this.state = JSON.parse(content);
+    } catch {
+      this.state = this.createInitialState();
+    }
+    return this.state;
+  }
+
+  /**
+   * Create initial planning state
+   */
+  createInitialState() {
+    return {
+      version: '1.0',
+      createdAt: new Date().toISOString(),
+      lastRefresh: null,
+      currentStage: 'discovery',
+      documents: {},
+      changeLog: [],
+      driftMetrics: {},
+      triggers: {},
+      layers: {
+        strategic: { lastUpdated: null, health: 'unknown' },
+        tactical: { lastUpdated: null, health: 'unknown' },
+        operational: { lastUpdated: null, health: 'unknown' }
+      }
+    };
+  }
+
+  /**
+   * Save planning state to disk
+   */
+  async saveState() {
+    try {
+      await fs.mkdir(this.planningDir, { recursive: true });
+      await fs.writeFile(this.stateFile, JSON.stringify(this.state, null, 2));
+    } catch (error) {
+      this.emit('error', { type: 'save-state', error });
+    }
+  }
+
+  /**
+   * Record a code change for drift analysis
+   * @param {Object} change - Change details
+   */
+  async recordChange(change) {
+    const normalizedChange = {
+      timestamp: new Date().toISOString(),
+      type: change.type || 'unknown',
+      file: change.file,
+      category: this.categorizeChange(change),
+      impact: this.assessChangeImpact(change),
+      affectedDocuments: this.identifyAffectedDocuments(change)
+    };
+
+    this.changeBuffer.push(normalizedChange);
+    this.state.changeLog.push(normalizedChange);
+
+    // Keep changelog trimmed
+    if (this.state.changeLog.length > 1000) {
+      this.state.changeLog = this.state.changeLog.slice(-500);
+    }
+
+    // Check triggers
+    const triggered = await this.checkTriggers(normalizedChange);
+    if (triggered.length > 0) {
+      this.emit('refresh-needed', {
+        triggers: triggered,
+        documents: this.getTriggeredDocuments(triggered)
+      });
+    }
+
+    await this.saveState();
+    return normalizedChange;
+  }
+
+  /**
+   * Categorize a code change
+   * @param {Object} change - Change details
+   */
+  categorizeChange(change) {
+    const file = change.file || '';
+    const ext = path.extname(file);
+
+    // Model/schema changes
+    if (file.includes('prisma') || file.includes('schema') || file.includes('model')) {
+      return 'model';
+    }
+
+    // API changes
+    if (file.includes('/api/') || file.includes('routes') || file.includes('endpoints')) {
+      return 'api';
+    }
+
+    // UI changes
+    if (file.includes('components') || file.includes('pages') || file.includes('views')) {
+      return 'ui';
+    }
+
+    // Test changes
+    if (file.includes('test') || file.includes('spec') || file.includes('__tests__')) {
+      return 'test';
+    }
+
+    // Config changes
+    if (file.includes('config') || ext === '.json' || ext === '.yml' || ext === '.yaml') {
+      return 'config';
+    }
+
+    // Documentation changes
+    if (ext === '.md' || file.includes('docs')) {
+      return 'documentation';
+    }
+
+    return 'code';
+  }
+
+  /**
+   * Assess the impact of a change
+   * @param {Object} change - Change details
+   */
+  assessChangeImpact(change) {
+    const category = this.categorizeChange(change);
+    const linesChanged = change.linesChanged || 0;
+
+    // Base impact by category
+    const categoryImpact = {
+      model: 0.8,
+      api: 0.7,
+      config: 0.6,
+      ui: 0.4,
+      code: 0.3,
+      test: 0.2,
+      documentation: 0.1
+    };
+
+    let impact = categoryImpact[category] || 0.3;
+
+    // Adjust by lines changed
+    if (linesChanged > 100) impact += 0.2;
+    else if (linesChanged > 50) impact += 0.1;
+    else if (linesChanged < 10) impact -= 0.1;
+
+    // Adjust by change type
+    if (change.type === 'add') impact += 0.1;
+    if (change.type === 'delete') impact += 0.15;
+
+    return Math.min(1.0, Math.max(0.0, impact));
+  }
+
+  /**
+   * Identify documents affected by a change
+   * @param {Object} change - Change details
+   */
+  identifyAffectedDocuments(change) {
+    const category = this.categorizeChange(change);
+
+    const documentMapping = {
+      model: ['prd', 'technical-spec', 'api'],
+      api: ['api', 'technical-spec', 'prd'],
+      ui: ['prd', 'design', 'user-stories'],
+      config: ['technical-spec', 'deployment'],
+      code: ['technical-spec'],
+      test: ['health', 'quality'],
+      documentation: []
+    };
+
+    return documentMapping[category] || ['technical-spec'];
+  }
+
+  /**
+   * Check if any refresh triggers have been hit
+   * @param {Object} change - Recent change
+   */
+  async checkTriggers(change) {
+    const triggeredList = [];
+
+    // Count changes by category in recent history
+    const recentChanges = this.state.changeLog.filter(c => {
+      const changeTime = new Date(c.timestamp).getTime();
+      const dayAgo = Date.now() - (24 * 60 * 60 * 1000);
+      return changeTime > dayAgo;
+    });
+
+    const changeCounts = {};
+    for (const c of recentChanges) {
+      changeCounts[c.category] = (changeCounts[c.category] || 0) + 1;
+    }
+
+    // Check model changes
+    if (change.category === 'model') {
+      this.state.triggers.modelChange = (this.state.triggers.modelChange || 0) + 1;
+      if (this.state.triggers.modelChange >= REFRESH_TRIGGERS.modelChange.threshold) {
+        triggeredList.push({ type: 'modelChange', ...REFRESH_TRIGGERS.modelChange });
+        this.state.triggers.modelChange = 0;
+      }
+    }
+
+    // Check code changes accumulation
+    if (changeCounts.code >= REFRESH_TRIGGERS.codeChange.threshold) {
+      triggeredList.push({ type: 'codeChange', ...REFRESH_TRIGGERS.codeChange });
+    }
+
+    // Check for bug accumulation (look for "fix" in commits)
+    if (change.message && change.message.toLowerCase().includes('fix')) {
+      this.state.triggers.bugAccumulation = (this.state.triggers.bugAccumulation || 0) + 1;
+      if (this.state.triggers.bugAccumulation >= REFRESH_TRIGGERS.bugAccumulation.threshold) {
+        triggeredList.push({ type: 'bugAccumulation', ...REFRESH_TRIGGERS.bugAccumulation });
+        this.state.triggers.bugAccumulation = 0;
+      }
+    }
+
+    return triggeredList;
+  }
+
+  /**
+   * Get documents that need updating based on triggers
+   * @param {Array} triggers - List of triggered refresh types
+   */
+  getTriggeredDocuments(triggers) {
+    const documents = new Set();
+    for (const trigger of triggers) {
+      for (const doc of trigger.documents) {
+        documents.add(doc);
+      }
+    }
+    return Array.from(documents);
+  }
+
+  /**
+   * Calculate drift between code and documentation
+   * @param {Object} options - Analysis options
+   */
+  async calculateDrift(options = {}) {
+    const analysis = {
+      timestamp: new Date().toISOString(),
+      overall: 0,
+      byDocument: {},
+      byLayer: {},
+      recommendations: []
+    };
+
+    // Analyze changes since last refresh
+    const lastRefresh = this.state.lastRefresh
+      ? new Date(this.state.lastRefresh).getTime()
+      : 0;
+
+    const changesSinceRefresh = this.state.changeLog.filter(c => {
+      return new Date(c.timestamp).getTime() > lastRefresh;
+    });
+
+    // Calculate impact-weighted drift
+    let totalImpact = 0;
+    const documentDrift = {};
+
+    for (const change of changesSinceRefresh) {
+      totalImpact += change.impact;
+
+      for (const doc of change.affectedDocuments) {
+        documentDrift[doc] = (documentDrift[doc] || 0) + change.impact;
+      }
+    }
+
+    // Normalize drift scores
+    const maxDrift = Math.max(1, changesSinceRefresh.length * 0.5);
+    analysis.overall = Math.min(1.0, totalImpact / maxDrift);
+
+    for (const [doc, drift] of Object.entries(documentDrift)) {
+      analysis.byDocument[doc] = {
+        drift: Math.min(1.0, drift / maxDrift),
+        severity: this.getDriftSeverity(drift / maxDrift),
+        changesAffecting: changesSinceRefresh.filter(c =>
+          c.affectedDocuments.includes(doc)
+        ).length
+      };
+    }
+
+    // Analyze by layer
+    for (const [layerName, layer] of Object.entries(PLANNING_LAYERS)) {
+      const layerDocs = layer.documents;
+      const layerDrift = layerDocs.reduce((sum, doc) => {
+        return sum + (analysis.byDocument[doc]?.drift || 0);
+      }, 0) / layerDocs.length;
+
+      analysis.byLayer[layerName] = {
+        drift: layerDrift,
+        severity: this.getDriftSeverity(layerDrift),
+        documents: layerDocs.map(doc => ({
+          name: doc,
+          drift: analysis.byDocument[doc]?.drift || 0
+        }))
+      };
+    }
+
+    // Generate recommendations
+    analysis.recommendations = this.generateDriftRecommendations(analysis);
+
+    // Store drift metrics
+    this.state.driftMetrics = analysis;
+    await this.saveState();
+
+    return analysis;
+  }
+
+  /**
+   * Get drift severity level
+   * @param {number} drift - Drift score (0-1)
+   */
+  getDriftSeverity(drift) {
+    for (const [level, config] of Object.entries(DRIFT_SEVERITY).reverse()) {
+      if (drift >= config.threshold) {
+        return { level, ...config };
+      }
+    }
+    return { level: 'none', ...DRIFT_SEVERITY.none };
+  }
+
+  /**
+   * Generate recommendations based on drift analysis
+   * @param {Object} analysis - Drift analysis results
+   */
+  generateDriftRecommendations(analysis) {
+    const recommendations = [];
+
+    // High drift documents
+    for (const [doc, data] of Object.entries(analysis.byDocument)) {
+      if (data.severity.level === 'critical') {
+        recommendations.push({
+          priority: 'critical',
+          document: doc,
+          action: `Immediately update ${doc.toUpperCase()}.md - critical drift detected`,
+          drift: data.drift
+        });
+      } else if (data.severity.level === 'significant') {
+        recommendations.push({
+          priority: 'high',
+          document: doc,
+          action: `Update ${doc.toUpperCase()}.md soon - significant drift detected`,
+          drift: data.drift
+        });
+      }
+    }
+
+    // Layer-level recommendations
+    for (const [layerName, data] of Object.entries(analysis.byLayer)) {
+      if (data.drift > 0.5) {
+        const layer = PLANNING_LAYERS[layerName];
+        recommendations.push({
+          priority: 'high',
+          layer: layerName,
+          action: `${layer.name} planning layer needs refresh - ${Math.round(data.drift * 100)}% drift`,
+          documents: data.documents.filter(d => d.drift > 0.3).map(d => d.name)
+        });
+      }
+    }
+
+    // Overall recommendation
+    if (analysis.overall > 0.7) {
+      recommendations.unshift({
+        priority: 'critical',
+        action: 'Full planning refresh recommended - overall drift is critical',
+        suggestedCommand: 'bootspring plan refresh --all'
+      });
+    } else if (analysis.overall > 0.4) {
+      recommendations.unshift({
+        priority: 'medium',
+        action: 'Consider partial planning refresh',
+        suggestedCommand: 'bootspring plan refresh'
+      });
+    }
+
+    return recommendations.sort((a, b) => {
+      const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+      return priorityOrder[a.priority] - priorityOrder[b.priority];
+    });
+  }
+
+  /**
+   * Refresh planning documents
+   * @param {Object} options - Refresh options
+   */
+  async refresh(options = {}) {
+    const refreshResult = {
+      timestamp: new Date().toISOString(),
+      documentsRefreshed: [],
+      changes: [],
+      errors: []
+    };
+
+    // Determine what to refresh
+    const drift = await this.calculateDrift();
+    const documentsToRefresh = options.all
+      ? Object.keys(drift.byDocument)
+      : options.documents || drift.recommendations
+          .filter(r => r.priority === 'critical' || r.priority === 'high')
+          .flatMap(r => r.document ? [r.document] : (r.documents || []));
+
+    const uniqueDocs = [...new Set(documentsToRefresh)];
+
+    for (const doc of uniqueDocs) {
+      try {
+        const result = await this.refreshDocument(doc, options);
+        refreshResult.documentsRefreshed.push(doc);
+        refreshResult.changes.push(result);
+      } catch (error) {
+        refreshResult.errors.push({ document: doc, error: error.message });
+      }
+    }
+
+    // Update state
+    this.state.lastRefresh = refreshResult.timestamp;
+    await this.saveState();
+
+    // Emit refresh complete event
+    this.emit('refresh-complete', refreshResult);
+
+    return refreshResult;
+  }
+
+  /**
+   * Refresh a single document
+   * @param {string} docName - Document name
+   * @param {Object} options - Refresh options
+   */
+  async refreshDocument(docName, options = {}) {
+    const docPath = path.join(this.planningDir, `${docName.toUpperCase()}.md`);
+
+    // Read current content
+    let currentContent = '';
+    try {
+      currentContent = await fs.readFile(docPath, 'utf-8');
+    } catch {
+      // Document doesn't exist yet
+    }
+
+    // Get changes affecting this document
+    const lastRefresh = this.state.documents[docName]?.lastRefresh
+      ? new Date(this.state.documents[docName].lastRefresh).getTime()
+      : 0;
+
+    const relevantChanges = this.state.changeLog.filter(c => {
+      return new Date(c.timestamp).getTime() > lastRefresh &&
+             c.affectedDocuments.includes(docName);
+    });
+
+    // Update document state
+    this.state.documents[docName] = {
+      lastRefresh: new Date().toISOString(),
+      version: (this.state.documents[docName]?.version || 0) + 1,
+      changeCount: relevantChanges.length
+    };
+
+    return {
+      document: docName,
+      path: docPath,
+      previousVersion: this.state.documents[docName].version - 1,
+      newVersion: this.state.documents[docName].version,
+      changesIncorporated: relevantChanges.length,
+      hadContent: !!currentContent
+    };
+  }
+
+  /**
+   * Get current planning status
+   */
+  async getStatus() {
+    const drift = await this.calculateDrift();
+
+    return {
+      initialized: true,
+      stage: this.state.currentStage,
+      lastRefresh: this.state.lastRefresh,
+      drift: {
+        overall: drift.overall,
+        severity: this.getDriftSeverity(drift.overall)
+      },
+      layers: Object.entries(PLANNING_LAYERS).map(([name, config]) => ({
+        name: config.name,
+        horizon: config.horizon,
+        health: this.state.layers[name]?.health || 'unknown',
+        lastUpdated: this.state.layers[name]?.lastUpdated,
+        drift: drift.byLayer[name]?.drift || 0
+      })),
+      pendingChanges: this.state.changeLog.filter(c => {
+        const lastRefresh = this.state.lastRefresh
+          ? new Date(this.state.lastRefresh).getTime()
+          : 0;
+        return new Date(c.timestamp).getTime() > lastRefresh;
+      }).length,
+      recommendations: drift.recommendations.slice(0, 5)
+    };
+  }
+
+  /**
+   * Simulate plan execution
+   * @param {Object} scenario - Scenario to simulate
+   */
+  async simulate(scenario) {
+    const simulation = {
+      timestamp: new Date().toISOString(),
+      scenario: scenario,
+      outcomes: [],
+      risks: [],
+      recommendations: []
+    };
+
+    // Analyze scenario type
+    if (scenario.type === 'feature') {
+      simulation.outcomes = this.simulateFeature(scenario);
+    } else if (scenario.type === 'refactor') {
+      simulation.outcomes = this.simulateRefactor(scenario);
+    } else if (scenario.type === 'timeline') {
+      simulation.outcomes = this.simulateTimeline(scenario);
+    } else if (scenario.type === 'resource') {
+      simulation.outcomes = this.simulateResource(scenario);
+    }
+
+    // Identify risks
+    simulation.risks = this.identifySimulationRisks(scenario, simulation.outcomes);
+
+    // Generate recommendations
+    simulation.recommendations = this.generateSimulationRecommendations(
+      scenario,
+      simulation.outcomes,
+      simulation.risks
+    );
+
+    return simulation;
+  }
+
+  /**
+   * Simulate feature addition
+   * @param {Object} scenario - Feature scenario
+   */
+  simulateFeature(scenario) {
+    const outcomes = [];
+    const feature = scenario.feature || 'Unknown Feature';
+
+    // Document impact
+    outcomes.push({
+      type: 'documents',
+      affected: ['prd', 'technical-spec', 'roadmap'],
+      impact: 'high',
+      description: `Adding "${feature}" will require updates to PRD, technical spec, and roadmap`
+    });
+
+    // Timeline impact
+    const estimatedDays = scenario.complexity === 'high' ? 14 :
+                          scenario.complexity === 'medium' ? 7 : 3;
+    outcomes.push({
+      type: 'timeline',
+      impact: estimatedDays > 7 ? 'high' : 'medium',
+      estimatedDays,
+      description: `Feature implementation estimated at ${estimatedDays} days`
+    });
+
+    // Dependencies
+    outcomes.push({
+      type: 'dependencies',
+      newDependencies: scenario.dependencies || [],
+      impact: scenario.dependencies?.length > 2 ? 'high' : 'low',
+      description: `Feature may introduce ${scenario.dependencies?.length || 0} new dependencies`
+    });
+
+    return outcomes;
+  }
+
+  /**
+   * Simulate refactoring
+   * @param {Object} scenario - Refactor scenario
+   */
+  simulateRefactor(scenario) {
+    const outcomes = [];
+
+    outcomes.push({
+      type: 'risk',
+      level: 'medium',
+      description: 'Refactoring may introduce temporary instability'
+    });
+
+    outcomes.push({
+      type: 'testing',
+      impact: 'high',
+      description: 'Comprehensive testing required after refactor'
+    });
+
+    outcomes.push({
+      type: 'documentation',
+      impact: 'medium',
+      description: 'Technical documentation will need updating'
+    });
+
+    return outcomes;
+  }
+
+  /**
+   * Simulate timeline changes
+   * @param {Object} scenario - Timeline scenario
+   */
+  simulateTimeline(scenario) {
+    const outcomes = [];
+    const change = scenario.change || 'compression';
+
+    if (change === 'compression') {
+      outcomes.push({
+        type: 'scope',
+        impact: 'high',
+        description: 'Timeline compression may require scope reduction'
+      });
+
+      outcomes.push({
+        type: 'quality',
+        risk: 'medium',
+        description: 'Quality may be impacted by accelerated timeline'
+      });
+    } else if (change === 'extension') {
+      outcomes.push({
+        type: 'scope',
+        impact: 'positive',
+        description: 'Extended timeline allows for additional features'
+      });
+
+      outcomes.push({
+        type: 'budget',
+        impact: 'high',
+        description: 'Extended timeline increases resource costs'
+      });
+    }
+
+    return outcomes;
+  }
+
+  /**
+   * Simulate resource changes
+   * @param {Object} scenario - Resource scenario
+   */
+  simulateResource(scenario) {
+    const outcomes = [];
+
+    if (scenario.action === 'add') {
+      outcomes.push({
+        type: 'velocity',
+        impact: 'positive',
+        description: 'Additional resources should increase velocity after onboarding'
+      });
+
+      outcomes.push({
+        type: 'coordination',
+        impact: 'negative',
+        description: 'More resources increase coordination overhead'
+      });
+    } else if (scenario.action === 'remove') {
+      outcomes.push({
+        type: 'velocity',
+        impact: 'negative',
+        description: 'Reduced resources will decrease velocity'
+      });
+
+      outcomes.push({
+        type: 'scope',
+        impact: 'high',
+        description: 'May need to reduce scope or extend timeline'
+      });
+    }
+
+    return outcomes;
+  }
+
+  /**
+   * Identify risks from simulation
+   * @param {Object} scenario - Simulation scenario
+   * @param {Array} outcomes - Simulation outcomes
+   */
+  identifySimulationRisks(scenario, outcomes) {
+    const risks = [];
+
+    // High impact outcomes become risks
+    for (const outcome of outcomes) {
+      if (outcome.impact === 'high' || outcome.risk === 'high') {
+        risks.push({
+          source: outcome.type,
+          severity: 'high',
+          description: outcome.description,
+          mitigation: this.suggestMitigation(outcome)
+        });
+      }
+    }
+
+    // Scenario-specific risks
+    if (scenario.type === 'feature' && scenario.complexity === 'high') {
+      risks.push({
+        source: 'complexity',
+        severity: 'high',
+        description: 'High complexity features have higher failure risk',
+        mitigation: 'Consider breaking into smaller deliverables'
+      });
+    }
+
+    return risks;
+  }
+
+  /**
+   * Suggest mitigation for a risk
+   * @param {Object} outcome - Outcome that creates risk
+   */
+  suggestMitigation(outcome) {
+    const mitigations = {
+      documents: 'Create document update plan before starting implementation',
+      timeline: 'Build in buffer time and identify scope reduction options',
+      dependencies: 'Evaluate alternatives and lock dependency versions',
+      risk: 'Create rollback plan and increase testing',
+      scope: 'Prioritize features and identify what can be deferred',
+      quality: 'Increase code review coverage and add automated checks',
+      coordination: 'Establish clear communication channels and handoff points'
+    };
+
+    return mitigations[outcome.type] || 'Review and plan accordingly';
+  }
+
+  /**
+   * Generate recommendations from simulation
+   * @param {Object} scenario - Simulation scenario
+   * @param {Array} outcomes - Simulation outcomes
+   * @param {Array} risks - Identified risks
+   */
+  generateSimulationRecommendations(scenario, outcomes, risks) {
+    const recommendations = [];
+
+    // Risk-based recommendations
+    const highRisks = risks.filter(r => r.severity === 'high');
+    if (highRisks.length > 0) {
+      recommendations.push({
+        priority: 'high',
+        action: 'Address high-severity risks before proceeding',
+        details: highRisks.map(r => r.mitigation)
+      });
+    }
+
+    // Scenario-specific recommendations
+    if (scenario.type === 'feature') {
+      recommendations.push({
+        priority: 'medium',
+        action: 'Create feature decomposition',
+        command: `bootspring plan decompose "${scenario.feature}"`
+      });
+    }
+
+    // Document update recommendations
+    const affectedDocs = outcomes
+      .filter(o => o.type === 'documents')
+      .flatMap(o => o.affected || []);
+
+    if (affectedDocs.length > 0) {
+      recommendations.push({
+        priority: 'medium',
+        action: 'Update affected planning documents',
+        documents: [...new Set(affectedDocs)]
+      });
+    }
+
+    return recommendations;
+  }
+
+  /**
+   * Transition to a new planning stage
+   * @param {string} newStage - Stage to transition to
+   * @param {Object} options - Transition options
+   */
+  async transitionStage(newStage, options = {}) {
+    const validStages = ['discovery', 'definition', 'execution', 'iteration', 'scale'];
+
+    if (!validStages.includes(newStage)) {
+      throw new Error(`Invalid stage: ${newStage}. Valid stages: ${validStages.join(', ')}`);
+    }
+
+    const previousStage = this.state.currentStage;
+    this.state.currentStage = newStage;
+
+    const transition = {
+      timestamp: new Date().toISOString(),
+      from: previousStage,
+      to: newStage,
+      reason: options.reason || 'Manual transition'
+    };
+
+    // Record transition
+    if (!this.state.stageHistory) {
+      this.state.stageHistory = [];
+    }
+    this.state.stageHistory.push(transition);
+
+    await this.saveState();
+
+    // Emit stage change event
+    this.emit('stage-change', transition);
+
+    return transition;
+  }
+
+  /**
+   * Get planning context for AI prompts
+   */
+  async getAIContext() {
+    const status = await this.getStatus();
+    const drift = await this.calculateDrift();
+
+    return {
+      projectStage: this.state.currentStage,
+      planningLayers: PLANNING_LAYERS,
+      currentDrift: {
+        overall: drift.overall,
+        severity: drift.recommendations[0]?.priority || 'none'
+      },
+      recentChanges: this.state.changeLog.slice(-10).map(c => ({
+        type: c.type,
+        category: c.category,
+        impact: c.impact
+      })),
+      refreshNeeded: drift.overall > 0.4,
+      documentsNeedingAttention: Object.entries(drift.byDocument)
+        .filter(([, data]) => data.drift > 0.3)
+        .map(([doc]) => doc),
+      suggestedActions: status.recommendations
+    };
+  }
+}
+
+module.exports = {
+  AdaptivePlanningEngine,
+  REFRESH_TRIGGERS,
+  PLANNING_LAYERS,
+  DRIFT_SEVERITY
+};