scene-capability-engine 3.3.3 → 3.3.5

package/lib/orchestrator/orchestration-engine.js

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scene-capability-engine",
-  "version": "3.3.3",
+  "version": "3.3.5",
   "description": "SCE (Scene Capability Engine) - A CLI tool and npm package for spec-driven development with AI coding assistants.",
   "main": "index.js",
   "bin": {
@@ -43,6 +43,9 @@
     "gate:matrix-regression": "node scripts/matrix-regression-gate.js --json",
     "report:moqui-baseline": "node scripts/moqui-template-baseline-report.js --json",
     "report:moqui-summary": "node scripts/moqui-release-summary.js --json",
+    "report:symbol-evidence": "node scripts/symbol-evidence-locate.js --query \"approve order\" --json",
+    "report:failure-attribution": "node scripts/failure-attribution-repair.js --error \"Cannot find module\" --json",
+    "report:capability-mapping": "node scripts/capability-mapping-report.js --input '{\"changes\":[],\"templates\":[],\"ontology\":{}}' --json",
     "report:matrix-remediation-queue": "node scripts/moqui-matrix-remediation-queue.js --json",
     "run:matrix-remediation-phased": "node scripts/moqui-matrix-remediation-phased-runner.js",
     "run:matrix-remediation-from-baseline": "node scripts/moqui-matrix-remediation-phased-runner.js --baseline .kiro/reports/release-evidence/moqui-template-baseline.json",