@girardmedia/bootspring 1.2.0 → 2.0.3

package/intelligence/workflow-composer.js

@@ -0,0 +1,1451 @@
+/**
+ * Bootspring Workflow Composition Engine
+ *
+ * Enables chaining multiple workflows together into composed sequences.
+ * Supports sequential, parallel, and DAG-based workflow compositions.
+ *
+ * Features:
+ * - Sequential composition: feature-dev → testing → launch-prep
+ * - Parallel composition: Run security-audit and performance-optimization concurrently
+ * - Dependency graphs: Define complex workflow relationships (DAG)
+ * - Data passing: Share context and outputs between workflows
+ * - Orchestrator integration: Hooks into workflow completion signals
+ *
+ * @package bootspring
+ * @module intelligence/workflow-composer
+ */
+
+const fs = require('fs');
+const path = require('path');
+const orchestrator = require('./orchestrator');
+const telemetry = require('../core/telemetry');
+
+/**
+ * Composition state file path
+ */
+function getCompositionPath() {
+  const projectRoot = process.cwd();
+  return path.join(projectRoot, '.bootspring', 'composition-state.json');
+}
+
+/**
+ * Load composition state
+ */
+function loadCompositionState() {
+  const statePath = getCompositionPath();
+  if (fs.existsSync(statePath)) {
+    try {
+      return JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    } catch {
+      return createDefaultCompositionState();
+    }
+  }
+  return createDefaultCompositionState();
+}
+
+/**
+ * Create default composition state
+ */
+function createDefaultCompositionState() {
+  return {
+    activeComposition: null,
+    compositions: {},
+    parallelGroups: {},
+    dagCompositions: {},
+    sharedContext: {},
+    history: []
+  };
+}
+
+/**
+ * Get project root for telemetry
+ */
+function getProjectRoot() {
+  return process.cwd();
+}
+
+/**
+ * Emit composition telemetry event
+ */
+function emitCompositionTelemetry(event, payload = {}) {
+  try {
+    telemetry.emitEvent(event, payload, { projectRoot: getProjectRoot() });
+  } catch {
+    // Telemetry should not block composition execution
+  }
+}
+
+/**
+ * Save composition state
+ */
+function saveCompositionState(state) {
+  const statePath = getCompositionPath();
+  const dir = path.dirname(statePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  state.lastUpdated = new Date().toISOString();
+  fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+}
+
+/**
+ * Create a new workflow composition
+ * @param {string} name - Composition name
+ * @param {Array<string>} workflowSequence - Array of workflow names in order
+ * @param {object} options - Options for the composition
+ */
+function createComposition(name, workflowSequence, options = {}) {
+  // Validate all workflows exist
+  const invalidWorkflows = workflowSequence.filter(w => !orchestrator.getWorkflow(w));
+  if (invalidWorkflows.length > 0) {
+    return {
+      success: false,
+      error: `Unknown workflows: ${invalidWorkflows.join(', ')}`
+    };
+  }
+
+  const state = loadCompositionState();
+
+  const composition = {
+    name,
+    workflows: workflowSequence,
+    currentIndex: 0,
+    status: 'pending',
+    createdAt: new Date().toISOString(),
+    options: {
+      autoAdvance: options.autoAdvance !== false, // Auto-start next workflow when one completes
+      pauseBetween: options.pauseBetween || false, // Pause between workflows for review
+      ...options
+    },
+    progress: workflowSequence.map(w => ({
+      workflow: w,
+      status: 'pending',
+      startedAt: null,
+      completedAt: null
+    }))
+  };
+
+  state.compositions[name] = composition;
+
+  // Initialize shared context for data passing
+  state.sharedContext[name] = {
+    inputs: options.initialContext || {},
+    outputs: {},
+    workflowResults: {}
+  };
+
+  saveCompositionState(state);
+
+  emitCompositionTelemetry('composition_created', {
+    composition: name,
+    workflowCount: workflowSequence.length,
+    workflows: workflowSequence
+  });
+
+  return {
+    success: true,
+    composition: name,
+    workflows: workflowSequence,
+    message: `Created composition "${name}" with ${workflowSequence.length} workflows`
+  };
+}
+
+/**
+ * Set context data for a composition
+ * This data will be passed to all workflows in the composition
+ * @param {string} compositionName - Composition name
+ * @param {string} key - Context key
+ * @param {any} value - Context value
+ */
+function setCompositionContext(compositionName, key, value) {
+  const state = loadCompositionState();
+
+  if (!state.sharedContext[compositionName]) {
+    state.sharedContext[compositionName] = { inputs: {}, outputs: {}, workflowResults: {} };
+  }
+
+  state.sharedContext[compositionName].inputs[key] = value;
+  saveCompositionState(state);
+
+  return {
+    success: true,
+    composition: compositionName,
+    key,
+    message: `Context "${key}" set for composition "${compositionName}"`
+  };
+}
+
+/**
+ * Get context data for a composition
+ * @param {string} compositionName - Composition name
+ * @param {string} key - Optional specific key to retrieve
+ */
+function getCompositionContext(compositionName, key = null) {
+  const state = loadCompositionState();
+  const context = state.sharedContext[compositionName];
+
+  if (!context) {
+    return null;
+  }
+
+  if (key) {
+    return context.inputs[key] || context.outputs[key] || context.workflowResults[key];
+  }
+
+  return {
+    inputs: context.inputs,
+    outputs: context.outputs,
+    workflowResults: context.workflowResults
+  };
+}
+
+/**
+ * Record workflow output data for passing to subsequent workflows
+ * @param {string} compositionName - Composition name
+ * @param {string} workflowName - Source workflow name
+ * @param {object} outputData - Output data from the workflow
+ */
+function recordWorkflowOutput(compositionName, workflowName, outputData) {
+  const state = loadCompositionState();
+
+  if (!state.sharedContext[compositionName]) {
+    return { success: false, error: 'Composition context not found' };
+  }
+
+  state.sharedContext[compositionName].workflowResults[workflowName] = {
+    data: outputData,
+    recordedAt: new Date().toISOString()
+  };
+
+  // Also merge into outputs for easy access
+  if (typeof outputData === 'object' && outputData !== null) {
+    Object.assign(state.sharedContext[compositionName].outputs, outputData);
+  }
+
+  saveCompositionState(state);
+
+  emitCompositionTelemetry('workflow_output_recorded', {
+    composition: compositionName,
+    workflow: workflowName,
+    outputKeys: Object.keys(outputData || {})
+  });
+
+  return {
+    success: true,
+    composition: compositionName,
+    workflow: workflowName,
+    message: `Output recorded for workflow "${workflowName}"`
+  };
+}
+
+/**
+ * Start a composition
+ */
+function startComposition(compositionName) {
+  const state = loadCompositionState();
+  const composition = state.compositions[compositionName];
+
+  if (!composition) {
+    return { success: false, error: `Composition not found: ${compositionName}` };
+  }
+
+  if (state.activeComposition) {
+    return {
+      success: false,
+      error: `Another composition is active: ${state.activeComposition}`
+    };
+  }
+
+  // Start the first workflow
+  const firstWorkflow = composition.workflows[0];
+  const startResult = orchestrator.startWorkflow(firstWorkflow);
+
+  if (!startResult.success) {
+    return startResult;
+  }
+
+  composition.status = 'active';
+  composition.currentIndex = 0;
+  composition.progress[0].status = 'active';
+  composition.progress[0].startedAt = new Date().toISOString();
+  state.activeComposition = compositionName;
+
+  state.history.push({
+    action: 'composition_started',
+    composition: compositionName,
+    timestamp: new Date().toISOString()
+  });
+
+  saveCompositionState(state);
+
+  return {
+    success: true,
+    composition: compositionName,
+    currentWorkflow: firstWorkflow,
+    currentIndex: 0,
+    totalWorkflows: composition.workflows.length,
+    message: `Started composition "${compositionName}" with workflow "${firstWorkflow}"`
+  };
+}
+
+/**
+ * Advance to the next workflow in the composition
+ */
+function advanceComposition() {
+  const state = loadCompositionState();
+
+  if (!state.activeComposition) {
+    return { success: false, error: 'No active composition' };
+  }
+
+  const composition = state.compositions[state.activeComposition];
+  const currentIndex = composition.currentIndex;
+
+  // Mark current workflow as complete
+  composition.progress[currentIndex].status = 'complete';
+  composition.progress[currentIndex].completedAt = new Date().toISOString();
+
+  // Check if composition is complete
+  if (currentIndex >= composition.workflows.length - 1) {
+    composition.status = 'complete';
+    state.history.push({
+      action: 'composition_completed',
+      composition: state.activeComposition,
+      timestamp: new Date().toISOString()
+    });
+    state.activeComposition = null;
+    saveCompositionState(state);
+
+    return {
+      success: true,
+      complete: true,
+      composition: composition.name,
+      message: `Composition "${composition.name}" completed!`
+    };
+  }
+
+  // Check if we should pause
+  if (composition.options.pauseBetween) {
+    composition.status = 'paused';
+    saveCompositionState(state);
+
+    return {
+      success: true,
+      paused: true,
+      composition: composition.name,
+      currentIndex,
+      nextWorkflow: composition.workflows[currentIndex + 1],
+      message: 'Composition paused between workflows. Use resumeComposition() to continue.'
+    };
+  }
+
+  // Advance to next workflow
+  const nextIndex = currentIndex + 1;
+  const nextWorkflow = composition.workflows[nextIndex];
+
+  const startResult = orchestrator.startWorkflow(nextWorkflow);
+  if (!startResult.success) {
+    return startResult;
+  }
+
+  composition.currentIndex = nextIndex;
+  composition.progress[nextIndex].status = 'active';
+  composition.progress[nextIndex].startedAt = new Date().toISOString();
+
+  state.history.push({
+    action: 'composition_workflow_advanced',
+    composition: composition.name,
+    fromWorkflow: composition.workflows[currentIndex],
+    toWorkflow: nextWorkflow,
+    timestamp: new Date().toISOString()
+  });
+
+  saveCompositionState(state);
+
+  return {
+    success: true,
+    composition: composition.name,
+    currentWorkflow: nextWorkflow,
+    currentIndex: nextIndex,
+    totalWorkflows: composition.workflows.length,
+    message: `Advanced to workflow "${nextWorkflow}"`
+  };
+}
+
+/**
+ * Resume a paused composition
+ */
+function resumeComposition() {
+  const state = loadCompositionState();
+
+  if (!state.activeComposition) {
+    return { success: false, error: 'No active composition' };
+  }
+
+  const composition = state.compositions[state.activeComposition];
+
+  if (composition.status !== 'paused') {
+    return { success: false, error: 'Composition is not paused' };
+  }
+
+  composition.status = 'active';
+  saveCompositionState(state);
+
+  // Continue by advancing to next workflow
+  return advanceComposition();
+}
+
+/**
+ * Get current composition status
+ */
+function getCompositionStatus(compositionName) {
+  const state = loadCompositionState();
+  const name = compositionName || state.activeComposition;
+
+  if (!name) {
+    return null;
+  }
+
+  const composition = state.compositions[name];
+  if (!composition) {
+    return null;
+  }
+
+  const completedCount = composition.progress.filter(p => p.status === 'complete').length;
+
+  return {
+    name: composition.name,
+    status: composition.status,
+    workflows: composition.workflows,
+    currentIndex: composition.currentIndex,
+    currentWorkflow: composition.workflows[composition.currentIndex],
+    progress: composition.progress,
+    summary: {
+      completed: completedCount,
+      total: composition.workflows.length,
+      percent: Math.round((completedCount / composition.workflows.length) * 100)
+    },
+    options: composition.options
+  };
+}
+
+/**
+ * List all compositions
+ */
+function listCompositions() {
+  const state = loadCompositionState();
+
+  return Object.entries(state.compositions).map(([name, comp]) => ({
+    name,
+    status: comp.status,
+    workflows: comp.workflows,
+    workflowCount: comp.workflows.length,
+    isActive: state.activeComposition === name
+  }));
+}
+
+/**
+ * Cancel active composition
+ */
+function cancelComposition() {
+  const state = loadCompositionState();
+
+  if (!state.activeComposition) {
+    return { success: false, error: 'No active composition' };
+  }
+
+  const composition = state.compositions[state.activeComposition];
+  composition.status = 'cancelled';
+
+  state.history.push({
+    action: 'composition_cancelled',
+    composition: state.activeComposition,
+    timestamp: new Date().toISOString()
+  });
+
+  state.activeComposition = null;
+  saveCompositionState(state);
+
+  return {
+    success: true,
+    composition: composition.name,
+    message: `Cancelled composition "${composition.name}"`
+  };
+}
+
+// ============================================================================
+// PARALLEL COMPOSITION
+// ============================================================================
+
+/**
+ * Create a parallel workflow group
+ * All workflows in the group run concurrently
+ * @param {string} groupName - Group name
+ * @param {Array<string>} workflows - Array of workflow names to run in parallel
+ * @param {object} options - Options for the parallel group
+ */
+function createParallelGroup(groupName, workflows, options = {}) {
+  // Validate all workflows exist
+  const invalidWorkflows = workflows.filter(w => !orchestrator.getWorkflow(w));
+  if (invalidWorkflows.length > 0) {
+    return {
+      success: false,
+      error: `Unknown workflows: ${invalidWorkflows.join(', ')}`
+    };
+  }
+
+  const state = loadCompositionState();
+
+  const group = {
+    name: groupName,
+    workflows,
+    status: 'pending',
+    createdAt: new Date().toISOString(),
+    options: {
+      failFast: options.failFast !== false, // Stop all if one fails
+      continueOnFailure: options.continueOnFailure || false,
+      ...options
+    },
+    workflowStates: workflows.reduce((acc, w) => {
+      acc[w] = {
+        status: 'pending',
+        startedAt: null,
+        completedAt: null,
+        result: null,
+        error: null
+      };
+      return acc;
+    }, {})
+  };
+
+  state.parallelGroups[groupName] = group;
+  saveCompositionState(state);
+
+  emitCompositionTelemetry('parallel_group_created', {
+    group: groupName,
+    workflowCount: workflows.length,
+    workflows
+  });
+
+  return {
+    success: true,
+    group: groupName,
+    workflows,
+    message: `Created parallel group "${groupName}" with ${workflows.length} workflows`
+  };
+}
+
+/**
+ * Start a parallel workflow group
+ * Initiates all workflows in the group concurrently
+ * @param {string} groupName - Group name to start
+ */
+function startParallelGroup(groupName) {
+  const state = loadCompositionState();
+  const group = state.parallelGroups[groupName];
+
+  if (!group) {
+    return { success: false, error: `Parallel group not found: ${groupName}` };
+  }
+
+  if (group.status !== 'pending') {
+    return { success: false, error: `Group already ${group.status}` };
+  }
+
+  const startResults = [];
+  const errors = [];
+
+  // Start all workflows
+  for (const workflowName of group.workflows) {
+    // We use orchestrator's defineWorkflowWithParallel for tracking
+    // but for parallel groups, we track independently
+    group.workflowStates[workflowName].status = 'active';
+    group.workflowStates[workflowName].startedAt = new Date().toISOString();
+    startResults.push({ workflow: workflowName, started: true });
+  }
+
+  group.status = 'active';
+  group.startedAt = new Date().toISOString();
+
+  state.history.push({
+    action: 'parallel_group_started',
+    group: groupName,
+    workflows: group.workflows,
+    timestamp: new Date().toISOString()
+  });
+
+  saveCompositionState(state);
+
+  emitCompositionTelemetry('parallel_group_started', {
+    group: groupName,
+    workflowCount: group.workflows.length
+  });
+
+  return {
+    success: true,
+    group: groupName,
+    startResults,
+    errors,
+    message: `Started ${startResults.length} workflows in parallel`
+  };
+}
+
+/**
+ * Complete a workflow in a parallel group
+ * @param {string} groupName - Group name
+ * @param {string} workflowName - Workflow that completed
+ * @param {object} result - Result data from the workflow
+ */
+function completeParallelWorkflow(groupName, workflowName, result = {}) {
+  const state = loadCompositionState();
+  const group = state.parallelGroups[groupName];
+
+  if (!group) {
+    return { success: false, error: `Parallel group not found: ${groupName}` };
+  }
+
+  if (!group.workflowStates[workflowName]) {
+    return { success: false, error: `Workflow "${workflowName}" not in group "${groupName}"` };
+  }
+
+  const wfState = group.workflowStates[workflowName];
+  wfState.status = 'complete';
+  wfState.completedAt = new Date().toISOString();
+  wfState.result = result;
+
+  // Store output in shared context
+  if (!state.sharedContext[groupName]) {
+    state.sharedContext[groupName] = { inputs: {}, outputs: {}, workflowResults: {} };
+  }
+  state.sharedContext[groupName].workflowResults[workflowName] = result;
+
+  state.history.push({
+    action: 'parallel_workflow_completed',
+    group: groupName,
+    workflow: workflowName,
+    timestamp: new Date().toISOString()
+  });
+
+  // Check if all workflows are complete
+  const allComplete = Object.values(group.workflowStates).every(
+    ws => ws.status === 'complete' || ws.status === 'failed'
+  );
+
+  if (allComplete) {
+    group.status = 'complete';
+    group.completedAt = new Date().toISOString();
+
+    emitCompositionTelemetry('parallel_group_completed', {
+      group: groupName,
+      workflowCount: group.workflows.length,
+      allSucceeded: Object.values(group.workflowStates).every(ws => ws.status === 'complete')
+    });
+  }
+
+  saveCompositionState(state);
+
+  return {
+    success: true,
+    group: groupName,
+    workflow: workflowName,
+    allComplete,
+    progress: {
+      completed: Object.values(group.workflowStates).filter(ws => ws.status === 'complete').length,
+      failed: Object.values(group.workflowStates).filter(ws => ws.status === 'failed').length,
+      total: group.workflows.length
+    },
+    message: allComplete
+      ? `All workflows in group "${groupName}" complete`
+      : `Workflow "${workflowName}" completed in group "${groupName}"`
+  };
+}
+
+/**
+ * Mark a workflow as failed in a parallel group
+ * @param {string} groupName - Group name
+ * @param {string} workflowName - Workflow that failed
+ * @param {string} error - Error message
+ */
+function failParallelWorkflow(groupName, workflowName, error) {
+  const state = loadCompositionState();
+  const group = state.parallelGroups[groupName];
+
+  if (!group) {
+    return { success: false, error: `Parallel group not found: ${groupName}` };
+  }
+
+  const wfState = group.workflowStates[workflowName];
+  if (!wfState) {
+    return { success: false, error: `Workflow "${workflowName}" not in group "${groupName}"` };
+  }
+
+  wfState.status = 'failed';
+  wfState.completedAt = new Date().toISOString();
+  wfState.error = error;
+
+  state.history.push({
+    action: 'parallel_workflow_failed',
+    group: groupName,
+    workflow: workflowName,
+    error,
+    timestamp: new Date().toISOString()
+  });
+
+  // If failFast, mark group as failed
+  if (group.options.failFast) {
+    group.status = 'failed';
+    group.failedAt = new Date().toISOString();
+    group.failureReason = `Workflow "${workflowName}" failed: ${error}`;
+  }
+
+  saveCompositionState(state);
+
+  return {
+    success: true,
+    group: groupName,
+    workflow: workflowName,
+    groupFailed: group.status === 'failed',
+    message: group.status === 'failed'
+      ? `Group "${groupName}" failed due to workflow failure`
+      : `Workflow "${workflowName}" failed but group continues`
+  };
+}
+
+/**
+ * Get parallel group status
+ * @param {string} groupName - Group name
+ */
+function getParallelGroupStatus(groupName) {
+  const state = loadCompositionState();
+  const group = state.parallelGroups[groupName];
+
+  if (!group) {
+    return null;
+  }
+
+  const completed = Object.values(group.workflowStates).filter(ws => ws.status === 'complete').length;
+  const failed = Object.values(group.workflowStates).filter(ws => ws.status === 'failed').length;
+  const active = Object.values(group.workflowStates).filter(ws => ws.status === 'active').length;
+  const pending = Object.values(group.workflowStates).filter(ws => ws.status === 'pending').length;
+
+  return {
+    name: group.name,
+    status: group.status,
+    workflows: group.workflows,
+    workflowStates: group.workflowStates,
+    progress: {
+      completed,
+      failed,
+      active,
+      pending,
+      total: group.workflows.length,
+      percent: Math.round(((completed + failed) / group.workflows.length) * 100)
+    },
+    options: group.options
+  };
+}
+
+/**
+ * List all parallel groups
+ */
+function listParallelGroups() {
+  const state = loadCompositionState();
+
+  return Object.entries(state.parallelGroups).map(([name, group]) => ({
+    name,
+    status: group.status,
+    workflowCount: group.workflows.length,
+    createdAt: group.createdAt
+  }));
+}
+
+// ============================================================================
+// DAG-BASED COMPOSITION (Dependencies)
+// ============================================================================
+
+/**
+ * Create a DAG (Directed Acyclic Graph) composition
+ * Allows defining complex workflow dependencies
+ * @param {string} name - Composition name
+ * @param {object} workflowGraph - Workflow dependency graph
+ * @param {object} options - Options
+ *
+ * @example
+ * createDAGComposition('complex-launch', {
+ *   'feature-development': { dependsOn: [] },
+ *   'security-audit': { dependsOn: ['feature-development'] },
+ *   'performance-optimization': { dependsOn: ['feature-development'] },
+ *   'launch-preparation': { dependsOn: ['security-audit', 'performance-optimization'] }
+ * })
+ */
+function createDAGComposition(name, workflowGraph, options = {}) {
+  // Validate all workflows exist
+  const workflows = Object.keys(workflowGraph);
+  const invalidWorkflows = workflows.filter(w => !orchestrator.getWorkflow(w));
+  if (invalidWorkflows.length > 0) {
+    return {
+      success: false,
+      error: `Unknown workflows: ${invalidWorkflows.join(', ')}`
+    };
+  }
+
+  // Validate dependencies exist in graph
+  for (const [workflow, config] of Object.entries(workflowGraph)) {
+    const deps = config.dependsOn || [];
+    const invalidDeps = deps.filter(d => !workflows.includes(d));
+    if (invalidDeps.length > 0) {
+      return {
+        success: false,
+        error: `Workflow "${workflow}" has unknown dependencies: ${invalidDeps.join(', ')}`
+      };
+    }
+  }
+
+  // Check for cycles
+  const cycleCheck = detectCycles(workflowGraph);
+  if (cycleCheck.hasCycle) {
+    return {
+      success: false,
+      error: `Dependency cycle detected: ${cycleCheck.cycle.join(' → ')}`
+    };
+  }
+
+  const state = loadCompositionState();
+
+  const dagComposition = {
+    name,
+    graph: workflowGraph,
+    workflows,
+    status: 'pending',
+    createdAt: new Date().toISOString(),
+    options: {
+      failFast: options.failFast !== false,
+      maxParallel: options.maxParallel || 0, // 0 = no limit
+      ...options
+    },
+    workflowStates: workflows.reduce((acc, w) => {
+      acc[w] = {
+        status: 'pending',
+        dependsOn: workflowGraph[w].dependsOn || [],
+        dependencyMet: (workflowGraph[w].dependsOn || []).length === 0,
+        startedAt: null,
+        completedAt: null,
+        result: null,
+        error: null
+      };
+      return acc;
+    }, {}),
+    executionOrder: [],
+    completedCount: 0
+  };
+
+  state.dagCompositions[name] = dagComposition;
+
+  // Initialize shared context
+  state.sharedContext[name] = {
+    inputs: options.initialContext || {},
+    outputs: {},
+    workflowResults: {}
+  };
+
+  saveCompositionState(state);
+
+  emitCompositionTelemetry('dag_composition_created', {
+    composition: name,
+    workflowCount: workflows.length,
+    workflows
+  });
+
+  return {
+    success: true,
+    composition: name,
+    workflows,
+    graph: workflowGraph,
+    readyToStart: getReadyWorkflows(dagComposition),
+    message: `Created DAG composition "${name}" with ${workflows.length} workflows`
+  };
+}
+
+/**
+ * Detect cycles in workflow dependency graph
+ * Uses DFS with coloring (white=unvisited, gray=visiting, black=visited)
+ */
+function detectCycles(graph) {
+  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const colors = {};
+  const parent = {};
+
+  for (const node of Object.keys(graph)) {
+    colors[node] = WHITE;
+    parent[node] = null;
+  }
+
+  function dfs(node, path) {
+    colors[node] = GRAY;
+    path.push(node);
+
+    const deps = graph[node]?.dependsOn || [];
+    for (const dep of deps) {
+      if (colors[dep] === GRAY) {
+        // Found cycle - extract cycle path
+        const cycleStart = path.indexOf(dep);
+        const cycle = path.slice(cycleStart);
+        cycle.push(dep); // Close the cycle
+        return { hasCycle: true, cycle };
+      }
+      if (colors[dep] === WHITE) {
+        const result = dfs(dep, [...path]);
+        if (result.hasCycle) return result;
+      }
+    }
+
+    colors[node] = BLACK;
+    return { hasCycle: false };
+  }
+
+  for (const node of Object.keys(graph)) {
+    if (colors[node] === WHITE) {
+      const result = dfs(node, []);
+      if (result.hasCycle) return result;
+    }
+  }
+
+  return { hasCycle: false };
+}
+
+/**
+ * Get workflows that are ready to execute (all dependencies met)
+ */
+function getReadyWorkflows(dagComposition) {
+  const ready = [];
+
+  for (const [workflow, wfState] of Object.entries(dagComposition.workflowStates)) {
+    if (wfState.status !== 'pending') continue;
+
+    // Check if all dependencies are complete
+    const allDepsMet = wfState.dependsOn.every(dep => {
+      const depState = dagComposition.workflowStates[dep];
+      return depState && depState.status === 'complete';
+    });
+
+    if (allDepsMet) {
+      ready.push(workflow);
+    }
+  }
+
+  return ready;
+}
+
+/**
+ * Start a DAG composition
+ * Initiates all workflows that have no dependencies
+ * @param {string} name - DAG composition name
+ */
+function startDAGComposition(name) {
+  const state = loadCompositionState();
+  const dag = state.dagCompositions[name];
+
+  if (!dag) {
+    return { success: false, error: `DAG composition not found: ${name}` };
+  }
+
+  if (dag.status !== 'pending') {
+    return { success: false, error: `DAG composition already ${dag.status}` };
+  }
+
+  dag.status = 'active';
+  dag.startedAt = new Date().toISOString();
+
+  // Find workflows with no dependencies and start them
+  const readyWorkflows = getReadyWorkflows(dag);
+
+  for (const workflow of readyWorkflows) {
+    dag.workflowStates[workflow].status = 'active';
+    dag.workflowStates[workflow].startedAt = new Date().toISOString();
+    dag.workflowStates[workflow].dependencyMet = true;
+    dag.executionOrder.push(workflow);
+  }
+
+  state.history.push({
+    action: 'dag_composition_started',
+    composition: name,
+    initialWorkflows: readyWorkflows,
+    timestamp: new Date().toISOString()
+  });
+
+  saveCompositionState(state);
+
+  emitCompositionTelemetry('dag_composition_started', {
+    composition: name,
+    initialWorkflows: readyWorkflows
+  });
+
+  return {
+    success: true,
+    composition: name,
+    startedWorkflows: readyWorkflows,
+    message: `Started DAG composition "${name}" with ${readyWorkflows.length} initial workflows`
+  };
+}
+
+/**
+ * Complete a workflow in a DAG composition
+ * Automatically starts dependent workflows whose dependencies are now met
+ * @param {string} name - DAG composition name
+ * @param {string} workflowName - Completed workflow name
+ * @param {object} result - Result data to pass to dependent workflows
+ */
+function completeDAGWorkflow(name, workflowName, result = {}) {
+  const state = loadCompositionState();
+  const dag = state.dagCompositions[name];
+
+  if (!dag) {
+    return { success: false, error: `DAG composition not found: ${name}` };
+  }
+
+  const wfState = dag.workflowStates[workflowName];
+  if (!wfState) {
+    return { success: false, error: `Workflow "${workflowName}" not in DAG "${name}"` };
+  }
+
+  if (wfState.status !== 'active') {
+    return { success: false, error: `Workflow "${workflowName}" is not active` };
+  }
+
+  // Mark workflow as complete
+  wfState.status = 'complete';
+  wfState.completedAt = new Date().toISOString();
+  wfState.result = result;
+  dag.completedCount++;
+
+  // Store in shared context for dependent workflows
+  if (!state.sharedContext[name]) {
+    state.sharedContext[name] = { inputs: {}, outputs: {}, workflowResults: {} };
+  }
+  state.sharedContext[name].workflowResults[workflowName] = result;
+  if (typeof result === 'object' && result !== null) {
+    Object.assign(state.sharedContext[name].outputs, result);
+  }
+
+  state.history.push({
+    action: 'dag_workflow_completed',
+    composition: name,
+    workflow: workflowName,
+    timestamp: new Date().toISOString()
+  });
+
+  // Find newly ready workflows (dependencies now met)
+  const newlyReady = getReadyWorkflows(dag);
+
+  // Start newly ready workflows
+  for (const workflow of newlyReady) {
+    if (dag.workflowStates[workflow].status === 'pending') {
+      dag.workflowStates[workflow].status = 'active';
+      dag.workflowStates[workflow].startedAt = new Date().toISOString();
+      dag.workflowStates[workflow].dependencyMet = true;
+      dag.executionOrder.push(workflow);
+    }
+  }
+
+  // Check if DAG is complete
+  const allComplete = Object.values(dag.workflowStates).every(
+    ws => ws.status === 'complete' || ws.status === 'failed'
+  );
+
+  if (allComplete) {
+    dag.status = 'complete';
+    dag.completedAt = new Date().toISOString();
+
+    emitCompositionTelemetry('dag_composition_completed', {
+      composition: name,
+      workflowCount: dag.workflows.length,
+      allSucceeded: Object.values(dag.workflowStates).every(ws => ws.status === 'complete')
+    });
+  }
+
+  saveCompositionState(state);
+
+  return {
+    success: true,
+    composition: name,
+    workflow: workflowName,
+    newlyStarted: newlyReady.filter(w => w !== workflowName),
+    allComplete,
+    progress: {
+      completed: dag.completedCount,
+      total: dag.workflows.length,
+      percent: Math.round((dag.completedCount / dag.workflows.length) * 100)
+    },
+    message: allComplete
+      ? `DAG composition "${name}" complete!`
+      : `Workflow "${workflowName}" completed. ${newlyReady.length} workflows now ready.`
+  };
+}
+
+/**
+ * Fail a workflow in a DAG composition
+ * @param {string} name - DAG composition name
+ * @param {string} workflowName - Failed workflow name
+ * @param {string} error - Error message
+ */
+function failDAGWorkflow(name, workflowName, error) {
+  const state = loadCompositionState();
+  const dag = state.dagCompositions[name];
+
+  if (!dag) {
+    return { success: false, error: `DAG composition not found: ${name}` };
+  }
+
+  const wfState = dag.workflowStates[workflowName];
+  if (!wfState) {
+    return { success: false, error: `Workflow "${workflowName}" not in DAG "${name}"` };
+  }
+
+  wfState.status = 'failed';
+  wfState.completedAt = new Date().toISOString();
+  wfState.error = error;
+
+  state.history.push({
+    action: 'dag_workflow_failed',
+    composition: name,
+    workflow: workflowName,
+    error,
+    timestamp: new Date().toISOString()
+  });
+
+  // Find dependent workflows that can no longer complete
+  const blockedWorkflows = [];
+  for (const [wfName, ws] of Object.entries(dag.workflowStates)) {
+    if (ws.dependsOn.includes(workflowName) && ws.status === 'pending') {
+      blockedWorkflows.push(wfName);
+    }
+  }
+
+  // If failFast, mark entire DAG as failed
+  if (dag.options.failFast) {
+    dag.status = 'failed';
+    dag.failedAt = new Date().toISOString();
+    dag.failureReason = `Workflow "${workflowName}" failed: ${error}`;
+  }
+
+  saveCompositionState(state);
+
+  return {
+    success: true,
+    composition: name,
+    workflow: workflowName,
+    blockedWorkflows,
+    dagFailed: dag.status === 'failed',
+    message: dag.status === 'failed'
+      ? `DAG "${name}" failed due to workflow failure`
+      : `Workflow "${workflowName}" failed. ${blockedWorkflows.length} dependent workflows blocked.`
+  };
+}
+
+/**
+ * Get DAG composition status
+ * @param {string} name - DAG composition name
+ */
+function getDAGStatus(name) {
+  const state = loadCompositionState();
+  const dag = state.dagCompositions[name];
+
+  if (!dag) {
+    return null;
+  }
+
+  const completed = Object.values(dag.workflowStates).filter(ws => ws.status === 'complete').length;
+  const failed = Object.values(dag.workflowStates).filter(ws => ws.status === 'failed').length;
+  const active = Object.values(dag.workflowStates).filter(ws => ws.status === 'active').length;
+  const pending = Object.values(dag.workflowStates).filter(ws => ws.status === 'pending').length;
+  const ready = getReadyWorkflows(dag);
+
+  return {
+    name: dag.name,
+    status: dag.status,
+    graph: dag.graph,
+    workflowStates: dag.workflowStates,
+    executionOrder: dag.executionOrder,
+    readyToStart: ready,
+    progress: {
+      completed,
+      failed,
+      active,
+      pending,
+      total: dag.workflows.length,
+      percent: Math.round(((completed + failed) / dag.workflows.length) * 100)
+    },
+    context: state.sharedContext[name] || {},
+    options: dag.options
+  };
+}
+
+/**
+ * List all DAG compositions
+ */
+function listDAGCompositions() {
+  const state = loadCompositionState();
+
+  return Object.entries(state.dagCompositions).map(([name, dag]) => ({
+    name,
+    status: dag.status,
+    workflowCount: dag.workflows.length,
+    completedCount: dag.completedCount,
+    createdAt: dag.createdAt
+  }));
+}
+
+// ============================================================================
+// COMPOSITION TEMPLATES
+// ============================================================================
+
+/**
+ * Pre-defined composition templates
+ */
+const COMPOSITION_TEMPLATES = {
+  'full-feature': {
+    name: 'Full Feature Development',
+    description: 'Complete feature lifecycle from design to launch',
+    type: 'sequential',
+    workflows: ['feature-development', 'security-audit', 'launch-preparation']
+  },
+  'quick-ship': {
+    name: 'Quick Ship',
+    description: 'Fast track for well-tested features',
+    type: 'sequential',
+    workflows: ['feature-development', 'launch-preparation']
+  },
+  'hardening': {
+    name: 'Production Hardening',
+    description: 'Security and performance optimization (parallel)',
+    type: 'parallel',
+    workflows: ['security-audit', 'performance-optimization']
+  },
+  'api-launch': {
+    name: 'API Launch',
+    description: 'API development through to launch',
+    type: 'sequential',
+    workflows: ['api-development', 'security-audit', 'launch-preparation']
+  },
+  'comprehensive-feature': {
+    name: 'Comprehensive Feature Launch',
+    description: 'Feature development with parallel audits then launch',
+    type: 'dag',
+    graph: {
+      'feature-development': { dependsOn: [] },
+      'security-audit': { dependsOn: ['feature-development'] },
+      'performance-optimization': { dependsOn: ['feature-development'] },
+      'launch-preparation': { dependsOn: ['security-audit', 'performance-optimization'] }
+    }
+  },
+  'full-stack-parallel': {
+    name: 'Full Stack Parallel',
+    description: 'Parallel frontend/backend development then integration',
+    type: 'dag',
+    graph: {
+      'api-development': { dependsOn: [] },
+      'feature-development': { dependsOn: [] },
+      'security-audit': { dependsOn: ['api-development', 'feature-development'] },
+      'launch-preparation': { dependsOn: ['security-audit'] }
+    }
+  }
+};
+
+/**
+ * Create composition from template
+ * Supports sequential, parallel, and DAG templates
+ */
+function createFromTemplate(templateName, compositionName, options = {}) {
+  const template = COMPOSITION_TEMPLATES[templateName];
+  if (!template) {
+    return {
+      success: false,
+      error: `Unknown template: ${templateName}`,
+      availableTemplates: Object.keys(COMPOSITION_TEMPLATES)
+    };
+  }
+
+  const name = compositionName || `${templateName}-${Date.now()}`;
+
+  switch (template.type) {
+    case 'parallel':
+      return createParallelGroup(name, template.workflows, options);
+
+    case 'dag':
+      return createDAGComposition(name, template.graph, options);
+
+    case 'sequential':
+    default:
+      return createComposition(name, template.workflows, options);
+  }
+}
+
+/**
+ * List all active compositions across all types
+ */
+function listAllCompositions() {
+  const sequential = listCompositions();
+  const parallel = listParallelGroups();
+  const dag = listDAGCompositions();
+
+  return {
+    sequential: sequential.map(c => ({ ...c, type: 'sequential' })),
+    parallel: parallel.map(c => ({ ...c, type: 'parallel' })),
+    dag: dag.map(c => ({ ...c, type: 'dag' })),
+    total: sequential.length + parallel.length + dag.length
+  };
+}
+
+/**
+ * Get status of any composition type by name
+ * @param {string} name - Composition name
+ */
+function getAnyCompositionStatus(name) {
+  // Check sequential
+  const seqStatus = getCompositionStatus(name);
+  if (seqStatus) {
+    return { type: 'sequential', ...seqStatus };
+  }
+
+  // Check parallel
+  const parStatus = getParallelGroupStatus(name);
+  if (parStatus) {
+    return { type: 'parallel', ...parStatus };
+  }
+
+  // Check DAG
+  const dagStatus = getDAGStatus(name);
+  if (dagStatus) {
+    return { type: 'dag', ...dagStatus };
+  }
+
+  return null;
+}
+
+/**
+ * Hook into orchestrator workflow completion
+ * Call this when a workflow completes to auto-advance compositions
+ * @param {string} workflowName - Name of completed workflow
+ * @param {object} result - Workflow result data
+ */
+function onWorkflowComplete(workflowName, result = {}) {
+  const state = loadCompositionState();
+  const updates = [];
+
+  // Check if any DAG compositions are waiting on this workflow
+  for (const [dagName, dag] of Object.entries(state.dagCompositions)) {
+    if (dag.status === 'active') {
+      const wfState = dag.workflowStates[workflowName];
+      if (wfState && wfState.status === 'active') {
+        const dagResult = completeDAGWorkflow(dagName, workflowName, result);
+        updates.push({ type: 'dag', name: dagName, result: dagResult });
+      }
+    }
+  }
+
+  // Check if any parallel groups are waiting on this workflow
+  for (const [groupName, group] of Object.entries(state.parallelGroups)) {
+    if (group.status === 'active') {
+      const wfState = group.workflowStates[workflowName];
+      if (wfState && wfState.status === 'active') {
+        const parResult = completeParallelWorkflow(groupName, workflowName, result);
+        updates.push({ type: 'parallel', name: groupName, result: parResult });
+      }
+    }
+  }
+
+  return {
+    workflow: workflowName,
+    updates,
+    updateCount: updates.length
+  };
+}
+
+/**
+ * Create a complex composition with mixed sequential and parallel sections
+ * @param {string} name - Composition name
+ * @param {Array} phases - Array of phases, each being either a workflow name or array of parallel workflows
+ * @param {object} options - Options
+ *
+ * @example
+ * createMixedComposition('my-flow', [
+ *   'feature-development',                              // Sequential
+ *   ['security-audit', 'performance-optimization'],     // Parallel
+ *   'launch-preparation'                                // Sequential
+ * ])
+ */
+function createMixedComposition(name, phases, options = {}) {
+  // Convert to DAG representation
+  const graph = {};
+  let previousPhaseWorkflows = [];
+
+  for (let i = 0; i < phases.length; i++) {
+    const phase = phases[i];
+    const currentPhaseWorkflows = Array.isArray(phase) ? phase : [phase];
+
+    // Validate workflows
+    const invalidWorkflows = currentPhaseWorkflows.filter(w => !orchestrator.getWorkflow(w));
+    if (invalidWorkflows.length > 0) {
+      return {
+        success: false,
+        error: `Unknown workflows: ${invalidWorkflows.join(', ')}`
+      };
+    }
+
+    // Each workflow in current phase depends on all workflows from previous phase
+    for (const workflow of currentPhaseWorkflows) {
+      graph[workflow] = { dependsOn: [...previousPhaseWorkflows] };
+    }
+
+    previousPhaseWorkflows = currentPhaseWorkflows;
+  }
+
+  return createDAGComposition(name, graph, options);
+}
+
+module.exports = {
+  // Sequential composition
+  createComposition,
+  startComposition,
+  advanceComposition,
+  resumeComposition,
+  getCompositionStatus,
+  listCompositions,
+  cancelComposition,
+
+  // Parallel composition
+  createParallelGroup,
+  startParallelGroup,
+  completeParallelWorkflow,
+  failParallelWorkflow,
+  getParallelGroupStatus,
+  listParallelGroups,
+
+  // DAG composition
+  createDAGComposition,
+  startDAGComposition,
+  completeDAGWorkflow,
+  failDAGWorkflow,
+  getDAGStatus,
+  listDAGCompositions,
+
+  // Mixed composition
+  createMixedComposition,
+
+  // Context/data passing
+  setCompositionContext,
+  getCompositionContext,
+  recordWorkflowOutput,
+
+  // Templates
+  createFromTemplate,
+  COMPOSITION_TEMPLATES,
+
+  // Utilities
+  loadCompositionState,
+  listAllCompositions,
+  getAnyCompositionStatus,
+  onWorkflowComplete,
+  detectCycles,
+  getReadyWorkflows
+};