scene-capability-engine 3.3.4 → 3.3.10

package/lib/orchestrator/orchestration-engine.js

@@ -15,7 +15,7 @@ const { EventEmitter } = require('events');
 const path = require('path');
 const fsUtils = require('../utils/fs-utils');
 
-const SPECS_DIR = '.kiro/specs';
+const SPECS_DIR = '.sce/specs';
 const DEFAULT_RATE_LIMIT_MAX_RETRIES = 8;
 const DEFAULT_RATE_LIMIT_BACKOFF_BASE_MS = 1500;
 const DEFAULT_RATE_LIMIT_BACKOFF_MAX_MS = 60000;
@@ -39,6 +39,25 @@ const RATE_LIMIT_ERROR_PATTERNS = [
   /requests per minute/i,
   /tokens per minute/i,
 ];
+const DEFAULT_COORDINATION_POLICY_RELATIVE_PATH = path.join(
+  'docs',
+  'agent-runtime',
+  'multi-agent-coordination-policy-baseline.json'
+);
+const DEFAULT_RESULT_SUMMARY_REQUIRED_FIELDS = [
+  'spec_id',
+  'changed_files',
+  'tests_run',
+  'tests_passed',
+  'risk_level',
+  'open_issues'
+];
+const DEFAULT_COORDINATION_RULES = {
+  require_result_summary: false,
+  block_merge_on_failed_tests: true,
+  block_merge_on_unresolved_conflicts: true
+};
+const VALID_RESULT_RISK_LEVELS = new Set(['low', 'medium', 'high', 'unknown']);
 
 class OrchestrationEngine extends EventEmitter {
   /**
@@ -115,6 +134,14 @@ class OrchestrationEngine extends EventEmitter {
     this._random = typeof options.random === 'function' ? options.random : Math.random;
     /** @type {() => number} */
     this._now = typeof options.now === 'function' ? options.now : Date.now;
+    /** @type {{ require_result_summary: boolean, block_merge_on_failed_tests: boolean, block_merge_on_unresolved_conflicts: boolean }} */
+    this._coordinationRules = { ...DEFAULT_COORDINATION_RULES };
+    /** @type {string[]} */
+    this._resultSummaryRequiredFields = [...DEFAULT_RESULT_SUMMARY_REQUIRED_FIELDS];
+    /** @type {Map<string, object>} */
+    this._resultSummaries = new Map();
+    /** @type {string} */
+    this._coordinationPolicyPath = DEFAULT_COORDINATION_POLICY_RELATIVE_PATH;
   }
 
   // ---------------------------------------------------------------------------
@@ -197,6 +224,7 @@ class OrchestrationEngine extends EventEmitter {
       // Get config for maxParallel and maxRetries
       const config = await this._orchestratorConfig.getConfig();
       this._applyRetryPolicyConfig(config);
+      await this._applyCoordinationPolicyConfig(config);
       this._agentWaitTimeoutMs = this._resolveAgentWaitTimeoutMs(config);
       const maxParallel = options.maxParallel || config.maxParallel || 3;
       const maxRetries = config.maxRetries || 2;
@@ -486,6 +514,33 @@ class OrchestrationEngine extends EventEmitter {
    * @private
    */
   async _handleSpecCompleted(specName, agentId) {
+    const summaryValidation = this._resolveAndValidateResultSummary(specName, agentId);
+    if (!summaryValidation.valid) {
+      await this._handleSummaryContractViolation(
+        specName,
+        agentId,
+        summaryValidation.message,
+        summaryValidation
+      );
+      return;
+    }
+
+    const mergeDecision = this._evaluateMergeDecision(summaryValidation.summary);
+    if (!mergeDecision.allowed) {
+      await this._handleSummaryContractViolation(
+        specName,
+        agentId,
+        `merge blocked by result summary policy: ${mergeDecision.reasons.join('; ')}`,
+        {
+          valid: true,
+          summary: summaryValidation.summary,
+          issues: mergeDecision.reasons
+        }
+      );
+      return;
+    }
+
+    this._resultSummaries.set(specName, { ...summaryValidation.summary });
     this._completedSpecs.add(specName);
     this._statusMonitor.updateSpecStatus(specName, 'completed', agentId);
 
@@ -495,7 +550,12 @@ class OrchestrationEngine extends EventEmitter {
     // Sync external status (Req 8.5)
     await this._syncExternalSafe(specName, 'completed');
 
-    this.emit('spec:complete', { specName, agentId });
+    this.emit('spec:complete', {
+      specName,
+      agentId,
+      result_summary: summaryValidation.summary,
+      merge_decision: 'accepted'
+    });
   }
 
   /**
@@ -673,6 +733,277 @@ class OrchestrationEngine extends EventEmitter {
     }
   }
 
+  /**
+   * Resolve coordination policy from baseline file and runtime config.
+   *
+   * @param {object} config
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _applyCoordinationPolicyConfig(config) {
+    const baseline = await this._loadCoordinationPolicyBaseline(config);
+    const baselineRules = baseline && baseline.coordination_rules
+      ? baseline.coordination_rules
+      : {};
+    const runtimeRules = config && config.coordinationRules && typeof config.coordinationRules === 'object'
+      ? config.coordinationRules
+      : {};
+    const requireFields = baseline
+      && baseline.result_summary_contract
+      && Array.isArray(baseline.result_summary_contract.required_fields)
+      ? baseline.result_summary_contract.required_fields
+      : DEFAULT_RESULT_SUMMARY_REQUIRED_FIELDS;
+    const overrideFields = Array.isArray(config && config.resultSummaryRequiredFields)
+      ? config.resultSummaryRequiredFields
+      : null;
+
+    this._coordinationRules = {
+      require_result_summary: this._toBoolean(
+        runtimeRules.require_result_summary,
+        this._toBoolean(baselineRules.require_result_summary, DEFAULT_COORDINATION_RULES.require_result_summary)
+      ),
+      block_merge_on_failed_tests: this._toBoolean(
+        runtimeRules.block_merge_on_failed_tests,
+        this._toBoolean(
+          baselineRules.block_merge_on_failed_tests,
+          DEFAULT_COORDINATION_RULES.block_merge_on_failed_tests
+        )
+      ),
+      block_merge_on_unresolved_conflicts: this._toBoolean(
+        runtimeRules.block_merge_on_unresolved_conflicts,
+        this._toBoolean(
+          baselineRules.block_merge_on_unresolved_conflicts,
+          DEFAULT_COORDINATION_RULES.block_merge_on_unresolved_conflicts
+        )
+      )
+    };
+
+    const selectedFields = overrideFields || requireFields;
+    const normalizedFields = selectedFields
+      .map((field) => `${field || ''}`.trim())
+      .filter(Boolean);
+    this._resultSummaryRequiredFields = normalizedFields.length > 0
+      ? normalizedFields
+      : [...DEFAULT_RESULT_SUMMARY_REQUIRED_FIELDS];
+  }
+
+  /**
+   * @param {object} config
+   * @returns {Promise<object>}
+   * @private
+   */
+  async _loadCoordinationPolicyBaseline(config) {
+    const relativePath = (
+      config
+      && typeof config.coordinationPolicyFile === 'string'
+      && config.coordinationPolicyFile.trim()
+    )
+      ? config.coordinationPolicyFile.trim()
+      : this._coordinationPolicyPath;
+    const policyPath = path.resolve(this._workspaceRoot, relativePath);
+    const exists = await fsUtils.pathExists(policyPath);
+    if (!exists) {
+      return {};
+    }
+    try {
+      return await fsUtils.readJSON(policyPath);
+    } catch (err) {
+      console.warn(`[OrchestrationEngine] Failed to parse coordination policy: ${err.message}`);
+      return {};
+    }
+  }
+
+  /**
+   * @param {string} specName
+   * @param {string} agentId
+   * @returns {{ valid: boolean, summary: object|null, issues: string[], message: string }}
+   * @private
+   */
+  _resolveAndValidateResultSummary(specName, agentId) {
+    const requireSummary = this._coordinationRules
+      && this._coordinationRules.require_result_summary === true;
+    if (!requireSummary) {
+      return {
+        valid: true,
+        summary: {
+          spec_id: specName,
+          changed_files: [],
+          tests_run: 0,
+          tests_passed: 0,
+          risk_level: 'unknown',
+          open_issues: []
+        },
+        issues: [],
+        message: ''
+      };
+    }
+
+    const summary = this._readResultSummaryFromSpawner(agentId);
+    if (!summary) {
+      return {
+        valid: false,
+        summary: null,
+        issues: ['missing result summary payload'],
+        message: 'result summary contract missing'
+      };
+    }
+
+    const normalizedSummary = this._normalizeResultSummary(summary, specName);
+    const issues = this._validateResultSummary(normalizedSummary);
+    return {
+      valid: issues.length === 0,
+      summary: normalizedSummary,
+      issues,
+      message: issues.length === 0 ? '' : `result summary contract invalid: ${issues.join('; ')}`
+    };
+  }
+
+  /**
+   * @param {string} agentId
+   * @returns {object|null}
+   * @private
+   */
+  _readResultSummaryFromSpawner(agentId) {
+    if (!this._agentSpawner || typeof this._agentSpawner.getResultSummary !== 'function') {
+      return null;
+    }
+    try {
+      return this._agentSpawner.getResultSummary(agentId);
+    } catch (_err) {
+      return null;
+    }
+  }
+
+  /**
+   * @param {object} summary
+   * @param {string} fallbackSpecName
+   * @returns {object}
+   * @private
+   */
+  _normalizeResultSummary(summary, fallbackSpecName) {
+    const changedFiles = Array.isArray(summary.changed_files)
+      ? summary.changed_files.map((item) => `${item || ''}`.trim()).filter(Boolean)
+      : [];
+    const openIssues = Array.isArray(summary.open_issues)
+      ? summary.open_issues.map((item) => `${item || ''}`.trim()).filter(Boolean)
+      : [];
+    const testsRun = Number(summary.tests_run);
+    const testsPassed = Number(summary.tests_passed);
+    const normalizedRisk = `${summary.risk_level || 'unknown'}`.trim().toLowerCase();
+
+    return {
+      spec_id: `${summary.spec_id || fallbackSpecName || ''}`.trim(),
+      changed_files: changedFiles,
+      tests_run: Number.isFinite(testsRun) ? Math.max(0, Math.floor(testsRun)) : NaN,
+      tests_passed: Number.isFinite(testsPassed) ? Math.max(0, Math.floor(testsPassed)) : NaN,
+      risk_level: normalizedRisk || 'unknown',
+      open_issues: openIssues
+    };
+  }
+
+  /**
+   * @param {object} summary
+   * @returns {string[]}
+   * @private
+   */
+  _validateResultSummary(summary) {
+    const issues = [];
+    const requiredFields = Array.isArray(this._resultSummaryRequiredFields)
+      ? this._resultSummaryRequiredFields
+      : [];
+    for (const field of requiredFields) {
+      if (!Object.prototype.hasOwnProperty.call(summary, field)) {
+        issues.push(`missing field '${field}'`);
+      }
+    }
+
+    if (!summary.spec_id) {
+      issues.push('spec_id must be non-empty');
+    }
+    if (!Array.isArray(summary.changed_files)) {
+      issues.push('changed_files must be an array');
+    }
+    if (!Number.isFinite(summary.tests_run)) {
+      issues.push('tests_run must be a non-negative integer');
+    }
+    if (!Number.isFinite(summary.tests_passed)) {
+      issues.push('tests_passed must be a non-negative integer');
+    }
+    if (
+      Number.isFinite(summary.tests_run)
+      && Number.isFinite(summary.tests_passed)
+      && summary.tests_passed > summary.tests_run
+    ) {
+      issues.push('tests_passed cannot exceed tests_run');
+    }
+    if (!VALID_RESULT_RISK_LEVELS.has(summary.risk_level)) {
+      issues.push(`risk_level must be one of: ${[...VALID_RESULT_RISK_LEVELS].join(', ')}`);
+    }
+    if (!Array.isArray(summary.open_issues)) {
+      issues.push('open_issues must be an array');
+    }
+
+    return issues;
+  }
+
+  /**
+   * @param {object} summary
+   * @returns {{ allowed: boolean, reasons: string[] }}
+   * @private
+   */
+  _evaluateMergeDecision(summary) {
+    const reasons = [];
+    const coordinationRules = this._coordinationRules || DEFAULT_COORDINATION_RULES;
+    if (
+      coordinationRules.block_merge_on_failed_tests
+      && Number.isFinite(summary.tests_run)
+      && Number.isFinite(summary.tests_passed)
+      && summary.tests_run > summary.tests_passed
+    ) {
+      reasons.push(
+        `tests failed (${summary.tests_passed}/${summary.tests_run} passed)`
+      );
+    }
+
+    if (coordinationRules.block_merge_on_unresolved_conflicts) {
+      const hasConflictIssue = Array.isArray(summary.open_issues)
+        && summary.open_issues.some((issue) => /conflict|unresolved/i.test(`${issue}`));
+      if (hasConflictIssue) {
+        reasons.push('open issues contain unresolved conflict');
+      }
+    }
+
+    return {
+      allowed: reasons.length === 0,
+      reasons
+    };
+  }
+
+  /**
+   * @param {string} specName
+   * @param {string} agentId
+   * @param {string} errorMessage
+   * @param {object} validation
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _handleSummaryContractViolation(specName, agentId, errorMessage, validation = {}) {
+    this._completedSpecs.delete(specName);
+    this._failedSpecs.add(specName);
+    this._statusMonitor.updateSpecStatus(specName, 'failed', agentId, errorMessage);
+    await this._syncExternalSafe(specName, 'failed');
+
+    this.emit('spec:failed', {
+      specName,
+      agentId,
+      error: errorMessage,
+      summary_contract_violation: true,
+      summary_validation: validation
+    });
+
+    this._propagateFailure(specName);
+  }
+
   // ---------------------------------------------------------------------------
   // Validation & Helpers
   // ---------------------------------------------------------------------------
@@ -1342,12 +1673,20 @@ class OrchestrationEngine extends EventEmitter {
    * @private
    */
   _buildResult(status, error = null) {
+    const resultSummaries = {};
+    if (this._resultSummaries && typeof this._resultSummaries.entries === 'function') {
+      for (const [specName, summary] of this._resultSummaries.entries()) {
+        resultSummaries[specName] = { ...summary };
+      }
+    }
     return {
       status,
       plan: this._executionPlan,
       completed: [...this._completedSpecs],
       failed: [...this._failedSpecs],
       skipped: [...this._skippedSpecs],
+      result_summaries: resultSummaries,
+      coordination_rules: { ...(this._coordinationRules || DEFAULT_COORDINATION_RULES) },
       error,
     };
   }
@@ -1363,6 +1702,11 @@ class OrchestrationEngine extends EventEmitter {
     this._failedSpecs.clear();
     this._skippedSpecs.clear();
     this._completedSpecs.clear();
+    if (this._resultSummaries && typeof this._resultSummaries.clear === 'function') {
+      this._resultSummaries.clear();
+    } else {
+      this._resultSummaries = new Map();
+    }
     this._executionPlan = null;
     this._stopped = false;
     this._baseMaxParallel = null;

package/lib/orchestrator/orchestrator-config.js

@@ -1,7 +1,7 @@
 /**
  * Orchestrator Configuration Manager
  *
- * Manages `.kiro/config/orchestrator.json` for the Agent Orchestrator.
+ * Manages `.sce/config/orchestrator.json` for the Agent Orchestrator.
  * When the config file does not exist or contains invalid JSON,
  * returns a default configuration so that orchestration can proceed
  * with sensible defaults.
@@ -16,7 +16,7 @@ const fs = require('fs-extra');
 const fsUtils = require('../utils/fs-utils');
 
 const CONFIG_FILENAME = 'orchestrator.json';
-const CONFIG_DIR = '.kiro/config';
+const CONFIG_DIR = '.sce/config';
 
 /** Known configuration keys — anything else is silently ignored. */
 const KNOWN_KEYS = new Set([

package/lib/repo/config-manager.js

@@ -28,7 +28,7 @@ class ConfigManager {
    * @returns {string} Absolute path to the configuration file
    */
   getConfigPath() {
-    return path.join(this.projectRoot, '.kiro', this.configFileName);
+    return path.join(this.projectRoot, '.sce', this.configFileName);
   }
 
   /**
@@ -130,7 +130,7 @@ class ConfigManager {
     const configPath = this.getConfigPath();
 
     try {
-      // Ensure .kiro directory exists
+      // Ensure .sce directory exists
       const kiroDir = path.dirname(configPath);
       await fs.mkdir(kiroDir, { recursive: true });
 
@@ -471,7 +471,7 @@ class ConfigManager {
   _isValidRepoName(name) {
     // Allow alphanumeric, hyphens, underscores, dots, and names starting with dots (hidden directories)
     // Must not contain spaces or special characters like @, #, $, etc.
-    // Examples: "backend", ".github", ".kiro", "my-repo", "repo_name", "repo.name"
+    // Examples: "backend", ".github", ".sce", "my-repo", "repo_name", "repo.name"
     const validPattern = /^\.?[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
     return validPattern.test(name);
   }

package/lib/repo/handlers/init-handler.js

@@ -31,7 +31,7 @@ class InitHandler {
    * @returns {Promise<Object>} Initialization result
    */
   async execute(options = {}) {
-    const { yes = false, maxDepth = 3, exclude = ['.kiro'], nested = true } = options;
+    const { yes = false, maxDepth = 3, exclude = ['.sce'], nested = true } = options;
 
     // Check if configuration already exists
     const configExists = await this.configManager.configExists();

package/lib/repo/repo-manager.js

@@ -29,13 +29,13 @@ class RepoManager {
    * @param {string} rootPath - Root path to scan
    * @param {Object} options - Scan options
    * @param {number} options.maxDepth - Maximum depth to scan (default: 3)
-   * @param {string[]} options.exclude - Directories to exclude (default: ['.kiro'])
+   * @param {string[]} options.exclude - Directories to exclude (default: ['.sce'])
    * @param {boolean} options.nested - Enable nested repository scanning (default: true)
    * @returns {Promise<Array<{path: string, name: string, remote: string|null, branch: string, hasRemote: boolean, parent: string|null}>>}
    */
   async discoverRepositories(rootPath, options = {}) {
     const maxDepth = options.maxDepth || 3;
-    const exclude = options.exclude || ['.kiro'];
+    const exclude = options.exclude || ['.sce'];
     const nested = options.nested !== false; // Default to true
     
     const discovered = [];