scene-capability-engine 3.0.0

package/lib/collab/spec-lifecycle-manager.js

@@ -0,0 +1,304 @@
+/**
+ * SpecLifecycleManager - Manages Spec lifecycle state machine
+ *
+ * Tracks Spec status through: planned → assigned → in-progress → completed → released.
+ * Persists state to `.kiro/specs/{specName}/lifecycle.json`.
+ * On completion, triggers ContextSyncManager update and AgentRegistry notification.
+ * In single-Agent mode, all operations are no-ops.
+ *
+ * Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 6.3
+ */
+
+const path = require('path');
+const fs = require('fs-extra');
+const fsUtils = require('../utils/fs-utils');
+const { MultiAgentConfig } = require('./multi-agent-config');
+
+const SPECS_DIR = '.kiro/specs';
+
+const VALID_TRANSITIONS = {
+  planned: ['assigned'],
+  assigned: ['in-progress', 'planned'],
+  'in-progress': ['completed', 'assigned'],
+  completed: ['released'],
+  released: [],
+};
+
+const DEFAULT_STATUS = 'planned';
+
+class SpecLifecycleManager {
+  /**
+   * @param {string} workspaceRoot - Absolute path to the project root
+   * @param {import('../steering/context-sync-manager').ContextSyncManager} contextSyncManager
+   * @param {import('./agent-registry').AgentRegistry} agentRegistry
+   */
+  constructor(workspaceRoot, contextSyncManager, agentRegistry) {
+    this._workspaceRoot = workspaceRoot;
+    this._contextSyncManager = contextSyncManager;
+    this._agentRegistry = agentRegistry;
+    this._multiAgentConfig = new MultiAgentConfig(workspaceRoot);
+  }
+
+  /**
+   * Get the lifecycle.json path for a Spec.
+   * @param {string} specName
+   * @returns {string}
+   * @private
+   */
+  _lifecyclePath(specName) {
+    return path.join(this._workspaceRoot, SPECS_DIR, specName, 'lifecycle.json');
+  }
+
+  /**
+   * Get the current lifecycle status of a Spec.
+   * Single-Agent mode: returns 'planned' (default).
+   *
+   * @param {string} specName
+   * @returns {Promise<string>}
+   */
+  async getStatus(specName) {
+    const enabled = await this._multiAgentConfig.isEnabled();
+    if (!enabled) {
+      return DEFAULT_STATUS;
+    }
+
+    const lifecycle = await this.readLifecycle(specName);
+    return lifecycle.status;
+  }
+
+  /**
+   * Transition a Spec to a new status.
+   * Validates the transition against VALID_TRANSITIONS.
+   * Single-Agent mode: returns success without persisting.
+   *
+   * @param {string} specName
+   * @param {string} newStatus
+   * @returns {Promise<{success: boolean, oldStatus: string, newStatus: string, error?: string}>}
+   */
+  async transition(specName, newStatus) {
+    const enabled = await this._multiAgentConfig.isEnabled();
+    if (!enabled) {
+      return { success: true, oldStatus: DEFAULT_STATUS, newStatus };
+    }
+
+    const lifecycle = await this.readLifecycle(specName);
+    const oldStatus = lifecycle.status;
+
+    // Validate transition
+    const allowed = VALID_TRANSITIONS[oldStatus];
+    if (!allowed || !allowed.includes(newStatus)) {
+      return {
+        success: false,
+        oldStatus,
+        newStatus,
+        error: `Invalid transition: ${oldStatus} → ${newStatus}. Allowed: [${(allowed || []).join(', ')}]`,
+      };
+    }
+
+    // Record transition
+    lifecycle.status = newStatus;
+    lifecycle.transitions.push({
+      from: oldStatus,
+      to: newStatus,
+      timestamp: new Date().toISOString(),
+      agentId: null, // Will be set by caller if needed
+    });
+
+    await this.writeLifecycle(specName, lifecycle);
+
+    // On completion: trigger ContextSyncManager update and AgentRegistry notification
+    if (newStatus === 'completed') {
+      await this._onCompleted(specName);
+    }
+
+    return { success: true, oldStatus, newStatus };
+  }
+
+  /**
+   * Check if all tasks in a Spec are completed and auto-transition to 'completed'.
+   * Only transitions if current status is 'in-progress'.
+   * Single-Agent mode: returns {completed: false, transitioned: false}.
+   *
+   * @param {string} specName
+   * @returns {Promise<{completed: boolean, transitioned: boolean}>}
+   */
+  async checkCompletion(specName) {
+    const enabled = await this._multiAgentConfig.isEnabled();
+    if (!enabled) {
+      return { completed: false, transitioned: false };
+    }
+
+    const tasksPath = path.join(this._workspaceRoot, SPECS_DIR, specName, 'tasks.md');
+    const exists = await fs.pathExists(tasksPath);
+    if (!exists) {
+      return { completed: false, transitioned: false };
+    }
+
+    let content;
+    try {
+      content = await fs.readFile(tasksPath, 'utf8');
+    } catch (err) {
+      console.warn(`[SpecLifecycleManager] Failed to read ${tasksPath}: ${err.message}`);
+      return { completed: false, transitioned: false };
+    }
+
+    const allCompleted = this._areAllLeafTasksCompleted(content);
+    if (!allCompleted) {
+      return { completed: false, transitioned: false };
+    }
+
+    // Only transition if currently in-progress
+    const lifecycle = await this.readLifecycle(specName);
+    if (lifecycle.status !== 'in-progress') {
+      return { completed: true, transitioned: false };
+    }
+
+    const result = await this.transition(specName, 'completed');
+    return { completed: true, transitioned: result.success };
+  }
+
+  /**
+   * Read lifecycle.json for a Spec.
+   * Returns default lifecycle if file doesn't exist or is corrupted.
+   *
+   * @param {string} specName
+   * @returns {Promise<{specName: string, status: string, transitions: Array}>}
+   */
+  async readLifecycle(specName) {
+    const filePath = this._lifecyclePath(specName);
+    const exists = await fs.pathExists(filePath);
+
+    if (!exists) {
+      return { specName, status: DEFAULT_STATUS, transitions: [] };
+    }
+
+    try {
+      const data = await fsUtils.readJSON(filePath);
+      if (!data || typeof data.status !== 'string' || !Array.isArray(data.transitions)) {
+        console.warn(`[SpecLifecycleManager] Corrupted lifecycle.json for ${specName}, rebuilding`);
+        return { specName, status: DEFAULT_STATUS, transitions: [] };
+      }
+      return {
+        specName: data.specName || specName,
+        status: data.status,
+        transitions: data.transitions,
+      };
+    } catch (err) {
+      console.warn(`[SpecLifecycleManager] Failed to read lifecycle.json for ${specName}: ${err.message}`);
+      return { specName, status: DEFAULT_STATUS, transitions: [] };
+    }
+  }
+
+  /**
+   * Write lifecycle.json for a Spec (atomic write).
+   *
+   * @param {string} specName
+   * @param {{specName?: string, status: string, transitions: Array}} lifecycle
+   * @returns {Promise<void>}
+   */
+  async writeLifecycle(specName, lifecycle) {
+    const filePath = this._lifecyclePath(specName);
+    const dir = path.dirname(filePath);
+    await fsUtils.ensureDirectory(dir);
+
+    const data = {
+      specName: lifecycle.specName || specName,
+      status: lifecycle.status,
+      transitions: lifecycle.transitions || [],
+    };
+
+    await fsUtils.writeJSON(filePath, data);
+  }
+
+  // ── Private helpers ──────────────────────────────────────────────
+
+  /**
+   * Handle completion side-effects: update ContextSyncManager and notify via AgentRegistry.
+   *
+   * @param {string} specName
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _onCompleted(specName) {
+    // Update ContextSyncManager with completed status
+    if (this._contextSyncManager) {
+      try {
+        await this._contextSyncManager.updateSpecProgress(specName, {
+          status: 'completed',
+          progress: 100,
+          summary: `Spec ${specName} completed`,
+        });
+      } catch (err) {
+        console.warn(`[SpecLifecycleManager] Failed to update context for ${specName}: ${err.message}`);
+      }
+    }
+
+    // Notify active agents via AgentRegistry (log for now)
+    if (this._agentRegistry) {
+      try {
+        const activeAgents = await this._agentRegistry.getActiveAgents();
+        if (activeAgents.length > 0) {
+          console.log(
+            `[SpecLifecycleManager] Spec ${specName} completed. Notifying ${activeAgents.length} active agent(s): ${activeAgents.map(a => a.agentId).join(', ')}`
+          );
+        }
+      } catch (err) {
+        console.warn(`[SpecLifecycleManager] Failed to notify agents for ${specName}: ${err.message}`);
+      }
+    }
+  }
+
+  /**
+   * Check if all leaf tasks in tasks.md content are completed.
+   * Leaf tasks are checkbox lines with no deeper-indented sub-tasks following them.
+   * A task is completed when its checkbox is [x].
+   *
+   * @param {string} content
+   * @returns {boolean}
+   * @private
+   */
+  _areAllLeafTasksCompleted(content) {
+    const lines = content.split('\n');
+    const taskPattern = /^(\s*)- \[([ x\-~])\]\*?\s/;
+
+    // First pass: identify all task lines with their indentation levels
+    const tasks = [];
+    for (let i = 0; i < lines.length; i++) {
+      const match = lines[i].match(taskPattern);
+      if (match) {
+        tasks.push({
+          index: i,
+          indent: match[1].length,
+          status: match[2],
+        });
+      }
+    }
+
+    if (tasks.length === 0) {
+      return false;
+    }
+
+    // Second pass: identify leaf tasks and check completion
+    let total = 0;
+    let completed = 0;
+
+    for (let i = 0; i < tasks.length; i++) {
+      const current = tasks[i];
+      const next = tasks[i + 1];
+
+      // A task is a leaf if the next task is not more indented
+      const isLeaf = !next || next.indent <= current.indent;
+
+      if (isLeaf) {
+        total++;
+        if (current.status === 'x') {
+          completed++;
+        }
+      }
+    }
+
+    return total > 0 && completed === total;
+  }
+}
+
+module.exports = { SpecLifecycleManager, VALID_TRANSITIONS, DEFAULT_STATUS };

package/lib/collab/sync-barrier.js

@@ -0,0 +1,88 @@
+/**
+ * SyncBarrier - Agent 切换 Spec 时的同步屏障
+ *
+ * 确保 Agent 切换 Spec 时基于一致的代码库和 Steering 工作。
+ * - 检查工作区是否有未提交的更改（git status --porcelain）
+ * - 重新加载所有层级的 Steering 约束
+ * - 单 Agent 模式下为 no-op（返回 {ready: true}）
+ *
+ * Requirements: 5.1, 5.2, 5.3, 5.4
+ */
+
+const { execSync } = require('child_process');
+const { MultiAgentConfig } = require('./multi-agent-config');
+
+class SyncBarrier {
+  /**
+   * @param {string} workspaceRoot - Absolute path to the project root
+   * @param {import('../steering/steering-loader').SteeringLoader} steeringLoader
+   */
+  constructor(workspaceRoot, steeringLoader) {
+    this._workspaceRoot = workspaceRoot;
+    this._steeringLoader = steeringLoader;
+    this._multiAgentConfig = new MultiAgentConfig(workspaceRoot);
+  }
+
+  /**
+   * 执行 Spec 切换前的同步检查。
+   * 单 Agent 模式下为 no-op（返回 {ready: true}）。
+   *
+   * @param {string} specName - 目标 Spec
+   * @returns {Promise<{ready: boolean, error?: string, steering?: object}>}
+   */
+  async prepareSwitch(specName) {
+    const enabled = await this._multiAgentConfig.isEnabled();
+    if (!enabled) {
+      return { ready: true };
+    }
+
+    // Check for uncommitted changes
+    try {
+      const hasChanges = await this.hasUncommittedChanges();
+      if (hasChanges) {
+        return {
+          ready: false,
+          error: 'Uncommitted changes detected. Please commit or stash your changes before switching Spec.',
+        };
+      }
+    } catch (err) {
+      return {
+        ready: false,
+        error: `Failed to check git status: ${err.message}`,
+      };
+    }
+
+    // Reload steering for the target Spec
+    try {
+      const steering = await this._steeringLoader.loadMerged(specName);
+      return { ready: true, steering };
+    } catch (err) {
+      return {
+        ready: false,
+        error: `Failed to reload steering for ${specName}: ${err.message}`,
+      };
+    }
+  }
+
+  /**
+   * 检查工作区是否有未提交的更改。
+   * Git 命令失败时返回 false（优雅降级）。
+   *
+   * @returns {Promise<boolean>}
+   */
+  async hasUncommittedChanges() {
+    try {
+      const output = execSync('git status --porcelain', {
+        encoding: 'utf8',
+        cwd: this._workspaceRoot,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      return output.trim().length > 0;
+    } catch (_err) {
+      // Git command failed — graceful degradation
+      return false;
+    }
+  }
+}
+
+module.exports = { SyncBarrier };

package/lib/collab/visualizer.js

@@ -0,0 +1,208 @@
+/**
+ * Visualizer generates dependency graph visualizations
+ */
+class Visualizer {
+  /**
+   * Generate text-based dependency graph
+   * @param {Object} graph - Graph with nodes and edges
+   * @param {Object} options - Visualization options
+   * @returns {string} Text-based graph
+   */
+  generateTextGraph(graph, options = {}) {
+    const lines = [];
+    const { showCriticalPath = false } = options;
+    
+    // Get critical path if requested
+    let criticalPath = [];
+    if (showCriticalPath) {
+      criticalPath = this._getCriticalPath(graph);
+    }
+
+    // Group by master specs
+    const masterSpecs = graph.nodes.filter(n => n.type === 'master');
+    const subSpecs = graph.nodes.filter(n => n.type === 'sub');
+    
+    if (masterSpecs.length > 0) {
+      for (const master of masterSpecs) {
+        lines.push(this._formatNode(master, criticalPath));
+        
+        // Find sub-specs of this master
+        const children = this._getChildren(master.id, graph);
+        for (const child of children) {
+          lines.push(`  ${this._formatNode(child, criticalPath)}`);
+          
+          // Show dependencies
+          const deps = graph.edges.filter(e => e.from === child.id);
+          for (const dep of deps) {
+            lines.push(`    └─ requires: ${dep.to} (${dep.type})`);
+          }
+        }
+        lines.push('');
+      }
+    }
+
+    // Show standalone specs
+    const standalone = subSpecs.filter(s => {
+      const hasParent = graph.edges.some(e => e.to === s.id && graph.nodes.find(n => n.id === e.from && n.type === 'master'));
+      return !hasParent;
+    });
+
+    if (standalone.length > 0) {
+      lines.push('Standalone Specs:');
+      for (const spec of standalone) {
+        lines.push(this._formatNode(spec, criticalPath));
+        
+        const deps = graph.edges.filter(e => e.from === spec.id);
+        for (const dep of deps) {
+          lines.push(`  └─ requires: ${dep.to} (${dep.type})`);
+        }
+      }
+    }
+
+    if (showCriticalPath && criticalPath.length > 0) {
+      lines.push('');
+      lines.push(`Critical Path: ${criticalPath.join(' → ')}`);
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate Mermaid format graph
+   * @param {Object} graph - Graph with nodes and edges
+   * @returns {string} Mermaid graph definition
+   */
+  generateMermaidGraph(graph) {
+    const lines = ['graph TD'];
+    
+    // Add nodes
+    for (const node of graph.nodes) {
+      const symbol = this._getStatusSymbol(node.status);
+      const label = `${node.id} ${symbol}`;
+      const nodeId = this._sanitizeId(node.id);
+      
+      // Use different shapes for different types
+      if (node.type === 'master') {
+        lines.push(`  ${nodeId}[["${label}"]]`);
+      } else {
+        lines.push(`  ${nodeId}["${label}"]`);
+      }
+    }
+
+    // Add edges
+    for (const edge of edges) {
+      const fromId = this._sanitizeId(edge.from);
+      const toId = this._sanitizeId(edge.to);
+      const label = edge.type === 'requires-completion' ? 'requires' : edge.type;
+      lines.push(`  ${fromId} -->|${label}| ${toId}`);
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Highlight critical path in graph
+   * @param {Object} graph - Graph with nodes and edges
+   * @returns {Array<string>} Critical path node IDs
+   */
+  highlightCriticalPath(graph) {
+    return this._getCriticalPath(graph);
+  }
+
+  /**
+   * Format a spec node for display
+   * @param {Object} node - Node to format
+   * @param {Array<string>} criticalPath - Critical path nodes
+   * @returns {string} Formatted node string
+   */
+  _formatNode(node, criticalPath = []) {
+    const symbol = this._getStatusSymbol(node.status);
+    const assignment = node.kiroInstance ? ` (${node.kiroInstance})` : ' (unassigned)';
+    const critical = criticalPath.includes(node.id) ? ' [CRITICAL]' : '';
+    
+    return `${symbol} ${node.id}${assignment}${critical}`;
+  }
+
+  /**
+   * Get status symbol for a node
+   * @param {string} status - Node status
+   * @returns {string} Symbol
+   */
+  _getStatusSymbol(status) {
+    const symbols = {
+      'completed': '✓',
+      'in-progress': '⧗',
+      'not-started': '○',
+      'blocked': '✗'
+    };
+    return symbols[status] || '?';
+  }
+
+  /**
+   * Get children of a master spec
+   * @param {string} masterId - Master spec ID
+   * @param {Object} graph - Graph
+   * @returns {Array<Object>} Child nodes
+   */
+  _getChildren(masterId, graph) {
+    // In our model, children reference parent via metadata
+    // For visualization, we can infer from naming or metadata
+    // For now, return empty array (would need metadata access)
+    return [];
+  }
+
+  /**
+   * Get critical path (longest dependency chain)
+   * @param {Object} graph - Graph
+   * @returns {Array<string>} Node IDs in critical path
+   */
+  _getCriticalPath(graph) {
+    const memo = new Map();
+
+    const getLongestPath = (nodeId) => {
+      if (memo.has(nodeId)) {
+        return memo.get(nodeId);
+      }
+
+      const incoming = graph.edges.filter(e => e.to === nodeId);
+      
+      if (incoming.length === 0) {
+        memo.set(nodeId, [nodeId]);
+        return [nodeId];
+      }
+
+      let longestPath = [];
+      for (const edge of incoming) {
+        const path = getLongestPath(edge.from);
+        if (path.length > longestPath.length) {
+          longestPath = path;
+        }
+      }
+
+      const result = [...longestPath, nodeId];
+      memo.set(nodeId, result);
+      return result;
+    };
+
+    let criticalPath = [];
+    for (const node of graph.nodes) {
+      const path = getLongestPath(node.id);
+      if (path.length > criticalPath.length) {
+        criticalPath = path;
+      }
+    }
+
+    return criticalPath;
+  }
+
+  /**
+   * Sanitize ID for Mermaid
+   * @param {string} id - Node ID
+   * @returns {string} Sanitized ID
+   */
+  _sanitizeId(id) {
+    return id.replace(/[^a-zA-Z0-9]/g, '_');
+  }
+}
+
+module.exports = Visualizer;