scene-capability-engine 3.3.14 → 3.3.16

package/lib/orchestrator/orchestration-engine.js

@@ -24,6 +24,10 @@ const DEFAULT_RATE_LIMIT_PARALLEL_FLOOR = 1;
 const DEFAULT_RATE_LIMIT_COOLDOWN_MS = 45000;
 const DEFAULT_RATE_LIMIT_LAUNCH_BUDGET_PER_MINUTE = 8;
 const DEFAULT_RATE_LIMIT_LAUNCH_BUDGET_WINDOW_MS = 60000;
+const DEFAULT_RATE_LIMIT_SIGNAL_WINDOW_MS = 30000;
+const DEFAULT_RATE_LIMIT_SIGNAL_THRESHOLD = 3;
+const DEFAULT_RATE_LIMIT_SIGNAL_EXTRA_HOLD_MS = 3000;
+const DEFAULT_RATE_LIMIT_DYNAMIC_BUDGET_FLOOR = 1;
 const DEFAULT_AGENT_WAIT_TIMEOUT_SECONDS = 600;
 const AGENT_WAIT_TIMEOUT_GRACE_MS = 30000;
 const RATE_LIMIT_BACKOFF_JITTER_RATIO = 0.5;
@@ -120,6 +124,14 @@ class OrchestrationEngine extends EventEmitter {
     this._rateLimitLaunchBudgetPerMinute = DEFAULT_RATE_LIMIT_LAUNCH_BUDGET_PER_MINUTE;
     /** @type {number} rolling window size for launch-budget throttling */
     this._rateLimitLaunchBudgetWindowMs = DEFAULT_RATE_LIMIT_LAUNCH_BUDGET_WINDOW_MS;
+    /** @type {number|null} dynamic launch budget per minute derived from recent rate-limit pressure */
+    this._dynamicLaunchBudgetPerMinute = null;
+    /** @type {number[]} timestamps (ms) of recent rate-limit signals for spike detection */
+    this._rateLimitSignalTimestamps = [];
+    /** @type {number} rolling window for rate-limit spike detection */
+    this._rateLimitSignalWindowMs = DEFAULT_RATE_LIMIT_SIGNAL_WINDOW_MS;
+    /** @type {number} number of rate-limit signals inside window that triggers escalation */
+    this._rateLimitSignalThreshold = DEFAULT_RATE_LIMIT_SIGNAL_THRESHOLD;
     /** @type {number[]} timestamps (ms) of recent spec launches for rolling budget accounting */
     this._rateLimitLaunchTimestamps = [];
     /** @type {number} last launch-budget hold telemetry emission timestamp (ms) */
@@ -1081,6 +1093,8 @@ class OrchestrationEngine extends EventEmitter {
     this._rateLimitCooldownUntil = 0;
     this._rateLimitLaunchHoldUntil = 0;
     this._rateLimitLaunchTimestamps = [];
+    this._rateLimitSignalTimestamps = [];
+    this._dynamicLaunchBudgetPerMinute = null;
     this._launchBudgetLastHoldSignalAt = 0;
     this._launchBudgetLastHoldMs = 0;
     this._updateStatusMonitorParallelTelemetry({
@@ -1147,11 +1161,14 @@ class OrchestrationEngine extends EventEmitter {
   _onRateLimitSignal(retryDelayMs = 0) {
     const now = this._getNow();
     const launchHoldMs = this._toNonNegativeInteger(retryDelayMs, 0);
+    this._recordRateLimitSignal(now);
     if (launchHoldMs > 0) {
       const currentHoldUntil = this._toNonNegativeInteger(this._rateLimitLaunchHoldUntil, 0);
       this._rateLimitLaunchHoldUntil = Math.max(currentHoldUntil, now + launchHoldMs);
     }
 
+    this._applyRateLimitEscalation(now);
+
     if (!this._isAdaptiveParallelEnabled()) {
       return;
     }
@@ -1192,6 +1209,8 @@ class OrchestrationEngine extends EventEmitter {
    * @private
    */
   _maybeRecoverParallelLimit(maxParallel) {
+    this._maybeRecoverLaunchBudget();
+
     if (!this._isAdaptiveParallelEnabled()) {
       return;
     }
@@ -1261,11 +1280,16 @@ class OrchestrationEngine extends EventEmitter {
    * @private
    */
   _getLaunchBudgetConfig() {
+    const configuredBudget = this._toNonNegativeInteger(
+      this._rateLimitLaunchBudgetPerMinute,
+      DEFAULT_RATE_LIMIT_LAUNCH_BUDGET_PER_MINUTE
+    );
+    const dynamicBudget = this._dynamicLaunchBudgetPerMinute === null
+      || this._dynamicLaunchBudgetPerMinute === undefined
+      ? configuredBudget
+      : this._toNonNegativeInteger(this._dynamicLaunchBudgetPerMinute, configuredBudget);
     return {
-      budgetPerMinute: this._toNonNegativeInteger(
-        this._rateLimitLaunchBudgetPerMinute,
-        DEFAULT_RATE_LIMIT_LAUNCH_BUDGET_PER_MINUTE
-      ),
+      budgetPerMinute: Math.min(configuredBudget, dynamicBudget),
       windowMs: this._toPositiveInteger(
         this._rateLimitLaunchBudgetWindowMs,
         DEFAULT_RATE_LIMIT_LAUNCH_BUDGET_WINDOW_MS
@@ -1487,6 +1511,168 @@ class OrchestrationEngine extends EventEmitter {
     return Math.max(1, Math.round(cappedBaseDelay * jitterFactor));
   }
 
+  /**
+   * @param {number} now
+   * @private
+   */
+  _recordRateLimitSignal(now) {
+    const signalAt = Number.isFinite(now) ? now : this._getNow();
+    const windowMs = this._toPositiveInteger(
+      this._rateLimitSignalWindowMs,
+      DEFAULT_RATE_LIMIT_SIGNAL_WINDOW_MS
+    );
+    if (!Array.isArray(this._rateLimitSignalTimestamps)) {
+      this._rateLimitSignalTimestamps = [];
+    }
+    this._rateLimitSignalTimestamps = this._rateLimitSignalTimestamps
+      .filter((timestamp) => Number.isFinite(timestamp) && timestamp > (signalAt - windowMs));
+    this._rateLimitSignalTimestamps.push(signalAt);
+  }
+
+  /**
+   * @returns {number}
+   * @private
+   */
+  _getRecentRateLimitSignalCount() {
+    const now = this._getNow();
+    const windowMs = this._toPositiveInteger(
+      this._rateLimitSignalWindowMs,
+      DEFAULT_RATE_LIMIT_SIGNAL_WINDOW_MS
+    );
+    if (!Array.isArray(this._rateLimitSignalTimestamps)) {
+      this._rateLimitSignalTimestamps = [];
+      return 0;
+    }
+    this._rateLimitSignalTimestamps = this._rateLimitSignalTimestamps
+      .filter((timestamp) => Number.isFinite(timestamp) && timestamp > (now - windowMs));
+    return this._rateLimitSignalTimestamps.length;
+  }
+
+  /**
+   * @param {number} now
+   * @private
+   */
+  _applyRateLimitEscalation(now) {
+    const signalCount = this._getRecentRateLimitSignalCount();
+    const threshold = this._toPositiveInteger(
+      this._rateLimitSignalThreshold,
+      DEFAULT_RATE_LIMIT_SIGNAL_THRESHOLD
+    );
+
+    if (signalCount < threshold) {
+      return;
+    }
+
+    const maxHoldMs = this._toPositiveInteger(
+      this._rateLimitBackoffMaxMs,
+      DEFAULT_RATE_LIMIT_BACKOFF_MAX_MS
+    );
+    const escalationUnits = signalCount - threshold + 1;
+    const extraHoldMs = Math.min(
+      maxHoldMs,
+      escalationUnits * DEFAULT_RATE_LIMIT_SIGNAL_EXTRA_HOLD_MS
+    );
+    if (extraHoldMs > 0) {
+      const currentHoldUntil = this._toNonNegativeInteger(this._rateLimitLaunchHoldUntil, 0);
+      this._rateLimitLaunchHoldUntil = Math.max(currentHoldUntil, now + extraHoldMs);
+    }
+
+    const configuredBudget = this._toNonNegativeInteger(
+      this._rateLimitLaunchBudgetPerMinute,
+      DEFAULT_RATE_LIMIT_LAUNCH_BUDGET_PER_MINUTE
+    );
+    if (configuredBudget <= 0) {
+      return;
+    }
+
+    const currentBudget = this._toPositiveInteger(
+      this._dynamicLaunchBudgetPerMinute == null
+        ? configuredBudget
+        : this._dynamicLaunchBudgetPerMinute,
+      configuredBudget
+    );
+    const budgetFloor = Math.max(
+      1,
+      Math.min(configuredBudget, DEFAULT_RATE_LIMIT_DYNAMIC_BUDGET_FLOOR)
+    );
+    const nextBudget = Math.max(budgetFloor, Math.floor(currentBudget / 2));
+    if (nextBudget >= currentBudget) {
+      return;
+    }
+
+    this._dynamicLaunchBudgetPerMinute = nextBudget;
+    const launchBudgetConfig = this._getLaunchBudgetConfig();
+    const holdMs = this._getLaunchBudgetHoldRemainingMs();
+    this._updateStatusMonitorLaunchBudget({
+      event: 'throttled',
+      budgetPerMinute: launchBudgetConfig.budgetPerMinute,
+      windowMs: launchBudgetConfig.windowMs,
+      used: Array.isArray(this._rateLimitLaunchTimestamps) ? this._rateLimitLaunchTimestamps.length : 0,
+      holdMs,
+    });
+    this.emit('launch:budget-throttled', {
+      reason: 'rate-limit-spike',
+      signalCount,
+      budgetPerMinute: launchBudgetConfig.budgetPerMinute,
+      windowMs: launchBudgetConfig.windowMs,
+      holdMs,
+    });
+  }
+
+  /**
+   * @private
+   */
+  _maybeRecoverLaunchBudget() {
+    const configuredBudget = this._toNonNegativeInteger(
+      this._rateLimitLaunchBudgetPerMinute,
+      DEFAULT_RATE_LIMIT_LAUNCH_BUDGET_PER_MINUTE
+    );
+    if (configuredBudget <= 0) {
+      this._dynamicLaunchBudgetPerMinute = null;
+      return;
+    }
+
+    const currentBudget = this._toPositiveInteger(
+      this._dynamicLaunchBudgetPerMinute == null
+        ? configuredBudget
+        : this._dynamicLaunchBudgetPerMinute,
+      configuredBudget
+    );
+    if (currentBudget >= configuredBudget) {
+      this._dynamicLaunchBudgetPerMinute = null;
+      return;
+    }
+
+    if (this._getNow() < this._rateLimitCooldownUntil) {
+      return;
+    }
+
+    if (this._getRecentRateLimitSignalCount() > 0) {
+      return;
+    }
+
+    const nextBudget = Math.min(configuredBudget, currentBudget + 1);
+    this._dynamicLaunchBudgetPerMinute = nextBudget >= configuredBudget
+      ? null
+      : nextBudget;
+
+    const launchBudgetConfig = this._getLaunchBudgetConfig();
+    const holdMs = this._getLaunchBudgetHoldRemainingMs();
+    this._updateStatusMonitorLaunchBudget({
+      event: 'recovered',
+      budgetPerMinute: launchBudgetConfig.budgetPerMinute,
+      windowMs: launchBudgetConfig.windowMs,
+      used: Array.isArray(this._rateLimitLaunchTimestamps) ? this._rateLimitLaunchTimestamps.length : 0,
+      holdMs,
+    });
+    this.emit('launch:budget-recovered', {
+      reason: 'rate-limit-cooldown',
+      budgetPerMinute: launchBudgetConfig.budgetPerMinute,
+      windowMs: launchBudgetConfig.windowMs,
+      holdMs,
+    });
+  }
+
   /**
    * Resolve final retry delay for rate-limit failures.
    * Uses larger of computed backoff and retry-after hint, then clamps to configured max.
@@ -1714,6 +1900,8 @@ class OrchestrationEngine extends EventEmitter {
     this._rateLimitCooldownUntil = 0;
     this._rateLimitLaunchHoldUntil = 0;
     this._rateLimitLaunchTimestamps = [];
+    this._rateLimitSignalTimestamps = [];
+    this._dynamicLaunchBudgetPerMinute = null;
     this._launchBudgetLastHoldSignalAt = 0;
     this._launchBudgetLastHoldMs = 0;
   }

package/lib/templates/registry-parser.js

@@ -155,7 +155,8 @@ class RegistryParser {
     // Required fields
     const requiredFields = [
       'id', 'name', 'category', 'description',
-      'difficulty', 'tags', 'files'
+      'difficulty', 'tags', 'applicable_scenarios', 'files',
+      'template_type', 'min_sce_version', 'risk_level', 'rollback_contract'
     ];
 
     for (const field of requiredFields) {
@@ -213,23 +214,31 @@ class RegistryParser {
       }
     }
 
-    if (template.risk_level !== undefined && template.risk_level !== null) {
-      if (!this.validRiskLevels.includes(template.risk_level)) {
-        errors.push(`${prefix}: Invalid risk_level "${template.risk_level}". Must be one of: ${this.validRiskLevels.join(', ')}`);
+    if (!this.validRiskLevels.includes(template.risk_level)) {
+      errors.push(`${prefix}: Invalid risk_level "${template.risk_level}". Must be one of: ${this.validRiskLevels.join(', ')}`);
+    }
+
+    if (!this._isPlainObject(template.rollback_contract)) {
+      errors.push(`${prefix}: Field "rollback_contract" must be an object`);
+    } else {
+      if (typeof template.rollback_contract.supported !== 'boolean') {
+        errors.push(`${prefix}: Field "rollback_contract.supported" must be boolean`);
+      }
+      if (typeof template.rollback_contract.strategy !== 'string' ||
+        template.rollback_contract.strategy.trim().length === 0) {
+        errors.push(`${prefix}: Field "rollback_contract.strategy" must be a non-empty string`);
       }
     }
 
-    if (template.rollback_contract !== undefined && template.rollback_contract !== null) {
-      if (!this._isPlainObject(template.rollback_contract)) {
-        errors.push(`${prefix}: Field "rollback_contract" must be an object`);
+    if (templateType === 'capability-template') {
+      const ontologyScope = template.ontology_scope;
+      if (!this._isPlainObject(ontologyScope)) {
+        errors.push(`${prefix}: capability-template requires "ontology_scope" object`);
       } else {
-        if (typeof template.rollback_contract.supported !== 'boolean') {
-          errors.push(`${prefix}: Field "rollback_contract.supported" must be boolean`);
-        }
-        if (template.rollback_contract.strategy !== undefined &&
-          template.rollback_contract.strategy !== null &&
-          typeof template.rollback_contract.strategy !== 'string') {
-          errors.push(`${prefix}: Field "rollback_contract.strategy" must be a string when present`);
+        const hasAnyScope = ['domains', 'entities', 'relations', 'business_rules', 'decisions']
+          .some((fieldName) => Array.isArray(ontologyScope[fieldName]) && ontologyScope[fieldName].length > 0);
+        if (!hasAnyScope) {
+          errors.push(`${prefix}: capability-template ontology_scope must include at least one non-empty scope array`);
         }
       }
     }

package/lib/version/version-checker.js

@@ -42,20 +42,20 @@ class VersionChecker {
       
       // Get current sce version
       const packageJson = require('../../package.json');
-      const kseVersion = packageJson.version;
+      const sceVersion = packageJson.version;
       
       // Check if upgrade is needed
-      const needsUpgrade = this.versionManager.needsUpgrade(projectVersion, kseVersion);
+      const needsUpgrade = this.versionManager.needsUpgrade(projectVersion, sceVersion);
       
       if (needsUpgrade) {
-        this.displayWarning(projectVersion, kseVersion);
+        this.displayWarning(projectVersion, sceVersion);
       }
       
       return {
         mismatch: needsUpgrade,
         shouldUpgrade: needsUpgrade,
         projectVersion,
-        kseVersion
+        sceVersion
       };
     } catch (error) {
       // Silently fail - don't block commands if version check fails
@@ -67,13 +67,13 @@ class VersionChecker {
    * Displays version mismatch warning
    * 
    * @param {string} projectVersion - Project version
-   * @param {string} kseVersion - Current sce version
+   * @param {string} sceVersion - Current sce version
    */
-  displayWarning(projectVersion, kseVersion) {
+  displayWarning(projectVersion, sceVersion) {
     console.log();
     console.log(chalk.yellow('⚠️  Version Mismatch Detected'));
     console.log(chalk.gray('  Project initialized with sce'), chalk.cyan(`v${projectVersion}`));
-    console.log(chalk.gray('  Current sce version:'), chalk.cyan(`v${kseVersion}`));
+    console.log(chalk.gray('  Current sce version:'), chalk.cyan(`v${sceVersion}`));
     console.log();
     console.log(chalk.blue('💡 Tip:'), chalk.gray('Run'), chalk.cyan('sce upgrade'), chalk.gray('to update project templates'));
     console.log(chalk.gray('  Or use'), chalk.cyan('--no-version-check'), chalk.gray('to suppress this warning'));
@@ -98,7 +98,7 @@ class VersionChecker {
       }
       
       const packageJson = require('../../package.json');
-      const kseVersion = packageJson.version;
+      const sceVersion = packageJson.version;
       
       console.log(chalk.blue('📦 Version Information'));
       console.log();
@@ -110,7 +110,7 @@ class VersionChecker {
       
       console.log();
       console.log(chalk.gray('Installed:'));
-      console.log(`  sce version: ${chalk.cyan(kseVersion)}`);
+      console.log(`  sce version: ${chalk.cyan(sceVersion)}`);
       
       if (projectVersionInfo['upgrade-history'].length > 0) {
         console.log();
@@ -129,12 +129,12 @@ class VersionChecker {
       
       const needsUpgrade = this.versionManager.needsUpgrade(
         projectVersionInfo['sce-version'],
-        kseVersion
+        sceVersion
       );
       
       if (needsUpgrade) {
         console.log(chalk.yellow('⚠️  Upgrade available'));
-        console.log(chalk.gray('  Run'), chalk.cyan('sce upgrade'), chalk.gray('to update to'), chalk.cyan(`v${kseVersion}`));
+        console.log(chalk.gray('  Run'), chalk.cyan('sce upgrade'), chalk.gray('to update to'), chalk.cyan(`v${sceVersion}`));
       } else {
         console.log(chalk.green('✅ Project is up to date'));
       }

package/lib/version/version-manager.js

@@ -88,16 +88,16 @@ class VersionManager {
   /**
    * Creates initial version info for a new project
    * 
-   * @param {string} kseVersion - Current sce version
+   * @param {string} sceVersion - Current sce version
    * @param {string} templateVersion - Template version (default: same as sce)
    * @returns {VersionInfo}
    */
-  createVersionInfo(kseVersion, templateVersion = null) {
+  createVersionInfo(sceVersion, templateVersion = null) {
     const now = new Date().toISOString();
     
     return {
-      'sce-version': kseVersion,
-      'template-version': templateVersion || kseVersion,
+      'sce-version': sceVersion,
+      'template-version': templateVersion || sceVersion,
       'created': now,
       'last-upgraded': now,
       'upgrade-history': []
@@ -141,20 +141,20 @@ class VersionManager {
    * Checks if upgrade is needed
    * 
    * @param {string} projectVersion - Current project version
-   * @param {string} kseVersion - Installed sce version
+   * @param {string} sceVersion - Installed sce version
    * @returns {boolean}
    */
-  needsUpgrade(projectVersion, kseVersion) {
-    if (!projectVersion || !kseVersion) {
+  needsUpgrade(projectVersion, sceVersion) {
+    if (!projectVersion || !sceVersion) {
       return false;
     }
     
     try {
       // Use semver for comparison
-      return semver.lt(projectVersion, kseVersion);
+      return semver.lt(projectVersion, sceVersion);
     } catch (error) {
       // If semver comparison fails, do string comparison
-      return projectVersion !== kseVersion;
+      return projectVersion !== sceVersion;
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scene-capability-engine",
-  "version": "3.3.14",
+  "version": "3.3.16",
   "description": "SCE (Scene Capability Engine) - A CLI tool and npm package for spec-driven development with AI coding assistants.",
   "main": "index.js",
   "bin": {

package/template/.sce/config/studio-security.json

@@ -0,0 +1,9 @@
+{
+  "enabled": false,
+  "require_auth_for": [
+    "apply",
+    "release",
+    "rollback"
+  ],
+  "password_env": "SCE_STUDIO_AUTH_PASSWORD"
+}

package/template/.sce/hooks/{sync-tasks-on-edit.kiro.hook → sync-tasks-on-edit.sce.hook}

@@ -11,6 +11,6 @@
   },
   "then": {
     "type": "askAgent",
-    "prompt": "The tasks.md file has been updated. Please review the changes and update the workspace status if needed. Run `kse workspace sync` to synchronize."
+    "prompt": "The tasks.md file has been updated. Please review the changes and update workspace status if needed. Run `sce workspace sync` to synchronize."
   }
 }