scene-capability-engine 3.3.15 → 3.3.17

package/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.17] - 2026-02-26
+
+### Added
+- Orchestrator rate-limit profile management commands:
+  - `sce orchestrate profile list`
+  - `sce orchestrate profile show`
+  - `sce orchestrate profile set <conservative|balanced|aggressive> [--reset-overrides]`
+- Runtime one-shot profile override:
+  - `sce orchestrate run --rate-limit-profile <profile>`
+- New anti-429 regression shortcut:
+  - `npm run test:orchestrator-429`
+- Added default orchestrator baseline config files:
+  - `.sce/config/orchestrator.json`
+  - `template/.sce/config/orchestrator.json`
+- Added profile runbook:
+  - `docs/agent-runtime/orchestrator-rate-limit-profiles.md`
+
+### Changed
+- Orchestration engine now supports runtime config overrides for one execution without mutating persisted config.
+- Command reference updated with profile workflow and recommended anti-429 usage.
+
+## [3.3.16] - 2026-02-26
+
+### Added
+- Studio strict gate profiles:
+  - `sce studio verify --profile strict`
+  - `sce studio release --profile strict`
+- Release preflight default gates now include:
+  - `scene package-publish-batch --dry-run` ontology thresholds (`average >= 70`, `valid-rate >= 100`)
+  - `auto handoff capability-matrix --fail-on-gap`
+
+### Changed
+- Strict profiles now fail when any required gate step is skipped.
+- Orchestration rate-limit handling now adapts launch budget under sustained `429` spikes and recovers budget gradually after cooldown.
+- Command reference updated for strict Studio profiles and required gate behavior.
+
 ## [3.3.13] - 2026-02-25
 
 ### Changed

package/README.md

@@ -775,6 +775,6 @@ A deep conversation about AI development trends, Neo-Confucian philosophy, and s
 
 ---
 
-**Version**: 3.3.15  
+**Version**: 3.3.17  
 **Last Updated**: 2026-02-26
 

package/README.zh.md

@@ -636,7 +636,7 @@ sce spec bootstrap --name 01-00-my-first-feature --non-interactive
 
 ---
 
-**版本**：3.3.15  
+**版本**：3.3.17  
 **最后更新**：2026-02-26
 
 

package/bin/scene-capability-engine.js

@@ -817,6 +817,10 @@ registerLockCommands(program);
 const { registerKnowledgeCommands } = require('../lib/commands/knowledge');
 registerKnowledgeCommands(program);
 
+// Studio orchestration commands
+const { registerStudioCommands } = require('../lib/commands/studio');
+registerStudioCommands(program);
+
 // Orchestration commands
 const { registerOrchestrateCommands } = require('../lib/commands/orchestrate');
 registerOrchestrateCommands(program);

package/docs/agent-runtime/orchestrator-rate-limit-profiles.md

@@ -0,0 +1,66 @@
+# Orchestrator Rate-Limit Profiles
+
+This document defines the default anti-429 presets used by SCE multi-agent orchestration.
+
+## Profiles
+
+| Profile | Positioning | Best for |
+|---|---|---|
+| `conservative` | strongest throttling, safest | unstable provider quota windows, repeated `429` spikes |
+| `balanced` | default baseline | normal daily multi-agent runs |
+| `aggressive` | higher throughput, lower safety margin | stable quota windows with strict delivery deadlines |
+
+## Effective Preset Values
+
+| Key | conservative | balanced | aggressive |
+|---|---:|---:|---:|
+| `rateLimitMaxRetries` | 10 | 8 | 6 |
+| `rateLimitBackoffBaseMs` | 2200 | 1500 | 1000 |
+| `rateLimitBackoffMaxMs` | 90000 | 60000 | 30000 |
+| `rateLimitCooldownMs` | 60000 | 45000 | 20000 |
+| `rateLimitLaunchBudgetPerMinute` | 4 | 8 | 16 |
+| `rateLimitSignalWindowMs` | 45000 | 30000 | 20000 |
+| `rateLimitSignalThreshold` | 2 | 3 | 4 |
+| `rateLimitSignalExtraHoldMs` | 5000 | 3000 | 2000 |
+| `rateLimitDynamicBudgetFloor` | 1 | 1 | 2 |
+
+## Usage
+
+Persistent (writes `.sce/config/orchestrator.json`):
+
+```bash
+sce orchestrate profile set conservative
+sce orchestrate profile set balanced --reset-overrides
+```
+
+One-shot for a single run (does not change file):
+
+```bash
+sce orchestrate run --specs "spec-a,spec-b,spec-c" --rate-limit-profile conservative
+```
+
+Inspect current effective state:
+
+```bash
+sce orchestrate profile show --json
+```
+
+## Validation Checklist
+
+Run anti-429 regression:
+
+```bash
+npm run test:orchestrator-429
+```
+
+Run full suite before release:
+
+```bash
+npm test -- --runInBand
+```
+
+Release readiness criteria:
+
+1. No failing test in orchestrator/rate-limit scope.
+2. `orchestrate profile show --json` returns expected profile and effective values.
+3. Multi-agent run no longer stalls under sustained `429`; launch budget and hold telemetry progress over time.

package/docs/architecture.md

@@ -227,7 +227,7 @@ This document provides detailed architecture diagrams and explanations for Scene
 │                    version.json                              │
 │  {                                                           │
 │    "version": "1.2.0",                                       │
-│    "kseVersion": "1.2.0",                                    │
+│    "sceVersion": "1.2.0",                                    │
 │    "createdAt": "2026-01-23T00:00:00.000Z",                 │
 │    "updatedAt": "2026-01-23T00:00:00.000Z",                 │
 │    "upgradeHistory": [                                       │
@@ -235,7 +235,7 @@ This document provides detailed architecture diagrams and explanations for Scene
 │        "from": "1.0.0",                                      │
 │        "to": "1.1.0",                                        │
 │        "timestamp": "2026-01-23T00:00:00.000Z",             │
-│        "kseVersion": "1.1.0"                                 │
+│        "sceVersion": "1.1.0"                                 │
 │      }                                                       │
 │    ]                                                         │
 │  }                                                           │

package/docs/command-reference.md

@@ -3,7 +3,7 @@
 > Quick reference for all `sce` commands
 
 **Version**: 2.0.0
-**Last Updated**: 2026-02-18
+**Last Updated**: 2026-02-26
 
 ---
 
@@ -295,15 +295,89 @@ sce repo health [--json]
 # Start orchestration for multiple specs
 sce orchestrate run --specs "spec-a,spec-b,spec-c" --max-parallel 3
 
+# One-shot anti-429 profile override (without editing orchestrator.json)
+sce orchestrate run --specs "spec-a,spec-b,spec-c" --rate-limit-profile conservative
+
 # Show orchestration status
 sce orchestrate status [--json]
 
 # Stop all running sub-agents
 sce orchestrate stop
+
+# List/show/set persistent rate-limit profile
+sce orchestrate profile list
+sce orchestrate profile show --json
+sce orchestrate profile set conservative
+sce orchestrate profile set balanced --reset-overrides
 ```
 
 When you pass `--specs` to `sce spec bootstrap|pipeline run|gate run`, sce now defaults to this orchestrate mode automatically.
 
+Rate-limit profiles:
+- `conservative`: strongest anti-429 throttling (recommended for unstable quota windows)
+- `balanced`: default profile for normal multi-agent runs
+- `aggressive`: higher throughput with lower protection margins
+
+### Studio Workflow
+
+```bash
+# Build a plan from chat/session context
+sce studio plan --from-chat session-20260226 --goal "customer+order+inventory demo" --json
+
+# Generate patch bundle metadata for a target scene
+sce studio generate --scene scene.customer-order-inventory --target 331 --json
+
+# Apply generated patch metadata
+sce studio apply --patch-bundle patch-scene.customer-order-inventory-<timestamp> --json
+
+# Record verification result
+sce studio verify --profile standard --json
+sce studio verify --profile strict --json
+
+# Record release event
+sce studio release --channel dev --profile standard --json
+sce studio release --channel dev --profile strict --json
+
+# Resume from latest or explicit job
+sce studio resume --job <job-id> --json
+
+# Inspect recent stage events
+sce studio events --job <job-id> --limit 50 --json
+
+# Rollback a job after apply/release
+sce studio rollback --job <job-id> --reason "manual-check-failed" --json
+
+# Enforce authorization for a protected action
+SCE_STUDIO_REQUIRE_AUTH=1 SCE_STUDIO_AUTH_PASSWORD=top-secret sce studio apply --job <job-id> --auth-password top-secret --json
+```
+
+Stage guardrails are enforced by default:
+- `generate` requires `plan`
+- `apply` requires `generate`
+- `verify` requires `apply`
+- `release` requires `verify`
+
+Studio gate execution defaults:
+- `verify --profile standard` runs executable gates (unit test script when available, interactive governance report when present, scene package publish-batch dry-run when handoff manifest exists)
+- `release --profile standard` runs executable release preflight (npm pack dry-run, weekly ops gate when summary exists, release asset integrity when evidence directory exists, scene package publish-batch ontology gate, handoff capability matrix gate)
+- `verify/release --profile strict` fails when any required gate step is skipped (for example missing manifest/evidence/scripts)
+
+Authorization model (optional, policy-driven):
+- Enable policy: `SCE_STUDIO_REQUIRE_AUTH=1`
+- Secret env key: `SCE_STUDIO_AUTH_PASSWORD` (or override key name with `SCE_STUDIO_PASSWORD_ENV`)
+- Protected actions: `apply`, `release`, `rollback`
+- Per-command hard requirement: add `--require-auth`
+
+Default policy file (recommended to commit): `.sce/config/studio-security.json`
+
+```json
+{
+  "enabled": false,
+  "require_auth_for": ["apply", "release", "rollback"],
+  "password_env": "SCE_STUDIO_AUTH_PASSWORD"
+}
+```
+
 ### Capability Matrix Utilities
 
 ```bash
@@ -348,6 +422,7 @@ Contract/baseline files:
 - `docs/agent-runtime/capability-mapping-report.schema.json`
 - `docs/agent-runtime/agent-result-summary-contract.schema.json`
 - `docs/agent-runtime/multi-agent-coordination-policy-baseline.json`
+- `docs/agent-runtime/orchestrator-rate-limit-profiles.md`
 
 Multi-agent merge governance default:
 - `sce orchestrate run` loads `docs/agent-runtime/multi-agent-coordination-policy-baseline.json`.
@@ -1267,6 +1342,7 @@ Recommended `.sce/config/orchestrator.json`:
   "maxParallel": 3,
   "timeoutSeconds": 900,
   "maxRetries": 2,
+  "rateLimitProfile": "balanced",
   "rateLimitMaxRetries": 8,
   "rateLimitBackoffBaseMs": 1500,
   "rateLimitBackoffMaxMs": 60000,
@@ -1275,13 +1351,25 @@ Recommended `.sce/config/orchestrator.json`:
   "rateLimitCooldownMs": 45000,
   "rateLimitLaunchBudgetPerMinute": 8,
   "rateLimitLaunchBudgetWindowMs": 60000,
+  "rateLimitSignalWindowMs": 30000,
+  "rateLimitSignalThreshold": 3,
+  "rateLimitSignalExtraHoldMs": 3000,
+  "rateLimitDynamicBudgetFloor": 1,
   "apiKeyEnvVar": "CODEX_API_KEY",
   "codexArgs": ["--skip-git-repo-check"],
   "codexCommand": "npx @openai/codex"
 }
 ```
 
-`rateLimit*` settings provide dedicated retry/backoff and adaptive parallel throttling when providers return 429 / too-many-requests errors. Engine retry honors `Retry-After` / `try again in ...` hints from provider error messages and clamps final retry waits by `rateLimitBackoffMaxMs` to avoid unbounded pause windows. During active backoff windows, new pending spec launches are paused to reduce request bursts (launch hold remains active even if adaptive parallel throttling is disabled). `orchestrate stop` now interrupts pending retry waits immediately so long backoff does not look like a deadlock.
+`rateLimitProfile` applies preset anti-429 behavior (`conservative|balanced|aggressive`). Any explicit `rateLimit*` field in `orchestrator.json` overrides the selected profile value.
+
+`rateLimit*` settings provide dedicated retry/backoff and adaptive throttling when providers return 429 / too-many-requests errors. Engine retry honors `Retry-After` / `try again in ...` hints from provider error messages and clamps final retry waits by `rateLimitBackoffMaxMs` to avoid unbounded pause windows. During active backoff windows, new pending spec launches are paused to reduce request bursts (launch hold remains active even if adaptive parallel throttling is disabled). Sustained 429 spikes are additionally controlled by:
+- `rateLimitSignalWindowMs`: rolling signal window for spike detection
+- `rateLimitSignalThreshold`: signals required inside window before escalation
+- `rateLimitSignalExtraHoldMs`: extra launch hold per escalation unit
+- `rateLimitDynamicBudgetFloor`: lowest dynamic launch budget allowed during sustained pressure
+
+`orchestrate stop` interrupts pending retry waits immediately so long backoff windows do not look like deadlocks.
 
 Codex sub-agent permission defaults:
 - `--sandbox danger-full-access` is always injected by orchestrator runtime.

package/docs/developer-guide.md

@@ -441,7 +441,7 @@ Reads version.json from project.
 ```javascript
 {
   version: '1.2.0',
-  kseVersion: '1.2.0',
+  sceVersion: '1.2.0',
   createdAt: '2026-01-23T00:00:00.000Z',
   updatedAt: '2026-01-23T00:00:00.000Z',
   upgradeHistory: []

package/lib/adoption/adoption-strategy.js

@@ -73,6 +73,7 @@ class AdoptionStrategy {
     await ensureDirectory(path.join(kiroPath, 'specs'));
     await ensureDirectory(path.join(kiroPath, 'steering'));
     await ensureDirectory(path.join(kiroPath, 'tools'));
+    await ensureDirectory(path.join(kiroPath, 'config'));
     await ensureDirectory(path.join(kiroPath, 'backups'));
     await ensureDirectory(path.join(kiroPath, 'hooks'));
   }
@@ -111,6 +112,7 @@ class AdoptionStrategy {
       'steering/ENVIRONMENT.md',
       'steering/CURRENT_CONTEXT.md',
       'steering/RULES_GUIDE.md',
+      'config/studio-security.json',
       'specs/SPEC_WORKFLOW_GUIDE.md',
       'hooks/sync-tasks-on-edit.sce.hook',
       'hooks/check-spec-on-create.sce.hook',
@@ -189,7 +191,7 @@ class FreshAdoption extends AdoptionStrategy {
    * @returns {Promise<AdoptionResult>}
    */
   async execute(projectPath, mode, options = {}) {
-    const { kseVersion = '1.0.0', dryRun = false } = options;
+    const { sceVersion = '1.0.0', dryRun = false } = options;
     
     const filesCreated = [];
     const filesUpdated = [];
@@ -225,6 +227,7 @@ class FreshAdoption extends AdoptionStrategy {
       filesCreated.push('.sce/specs/');
       filesCreated.push('.sce/steering/');
       filesCreated.push('.sce/tools/');
+      filesCreated.push('.sce/config/');
       filesCreated.push('.sce/backups/');
       filesCreated.push('.sce/hooks/');
       
@@ -235,7 +238,7 @@ class FreshAdoption extends AdoptionStrategy {
       filesSkipped.push(...copyResult.skipped);
       
       // Create version.json
-      const versionInfo = this.versionManager.createVersionInfo(kseVersion);
+      const versionInfo = this.versionManager.createVersionInfo(sceVersion);
       await this.versionManager.writeVersion(projectPath, versionInfo);
       filesCreated.push('version.json');
       
@@ -279,7 +282,7 @@ class PartialAdoption extends AdoptionStrategy {
    * @returns {Promise<AdoptionResult>}
    */
   async execute(projectPath, mode, options = {}) {
-    const { kseVersion = '1.0.0', dryRun = false, backupId = null, force = false, resolutionMap = {} } = options;
+    const { sceVersion = '1.0.0', dryRun = false, backupId = null, force = false, resolutionMap = {} } = options;
     
     const filesCreated = [];
     const filesUpdated = [];
@@ -320,6 +323,7 @@ class PartialAdoption extends AdoptionStrategy {
       const specsPath = path.join(kiroPath, 'specs');
       const steeringPath = path.join(kiroPath, 'steering');
       const toolsPath = path.join(kiroPath, 'tools');
+      const configPath = path.join(kiroPath, 'config');
       const backupsPath = path.join(kiroPath, 'backups');
       const hooksPath = path.join(kiroPath, 'hooks');
       
@@ -337,6 +341,11 @@ class PartialAdoption extends AdoptionStrategy {
         await ensureDirectory(toolsPath);
         filesCreated.push('tools/');
       }
+
+      if (!await pathExists(configPath)) {
+        await ensureDirectory(configPath);
+        filesCreated.push('config/');
+      }
       
       if (!await pathExists(backupsPath)) {
         await ensureDirectory(backupsPath);
@@ -356,15 +365,15 @@ class PartialAdoption extends AdoptionStrategy {
       
       // Create or update version.json
       if (!versionExists) {
-        const versionInfo = this.versionManager.createVersionInfo(kseVersion);
+        const versionInfo = this.versionManager.createVersionInfo(sceVersion);
         await this.versionManager.writeVersion(projectPath, versionInfo);
         filesCreated.push('version.json');
       } else {
         // Update existing version.json
         const versionInfo = await this.versionManager.readVersion(projectPath);
         if (versionInfo) {
-          versionInfo['sce-version'] = kseVersion;
-          versionInfo['template-version'] = kseVersion;
+          versionInfo['sce-version'] = sceVersion;
+          versionInfo['template-version'] = sceVersion;
           versionInfo['last-upgraded'] = new Date().toISOString();
           await this.versionManager.writeVersion(projectPath, versionInfo);
           filesUpdated.push('version.json');
@@ -411,7 +420,7 @@ class FullAdoption extends AdoptionStrategy {
    * @returns {Promise<AdoptionResult>}
    */
   async execute(projectPath, mode, options = {}) {
-    const { kseVersion = '1.0.0', dryRun = false, backupId = null } = options;
+    const { sceVersion = '1.0.0', dryRun = false, backupId = null } = options;
     
     const filesCreated = [];
     const filesUpdated = [];
@@ -437,8 +446,8 @@ class FullAdoption extends AdoptionStrategy {
       const currentVersion = existingVersion['sce-version'];
       
       // Check if upgrade is needed
-      if (!this.versionManager.needsUpgrade(currentVersion, kseVersion)) {
-        warnings.push(`Already at version ${kseVersion} - no upgrade needed`);
+      if (!this.versionManager.needsUpgrade(currentVersion, sceVersion)) {
+        warnings.push(`Already at version ${sceVersion} - no upgrade needed`);
         return {
           success: true,
           mode: 'full',
@@ -456,7 +465,7 @@ class FullAdoption extends AdoptionStrategy {
           success: true,
           mode: 'full',
           filesCreated: [],
-          filesUpdated: [`(dry-run) Would upgrade from ${currentVersion} to ${kseVersion}`],
+          filesUpdated: [`(dry-run) Would upgrade from ${currentVersion} to ${sceVersion}`],
           filesSkipped: [],
           backupId,
           errors: [],
@@ -478,7 +487,7 @@ class FullAdoption extends AdoptionStrategy {
       const updatedVersion = this.versionManager.addUpgradeHistory(
         existingVersion,
         currentVersion,
-        kseVersion,
+        sceVersion,
         true
       );
       await this.versionManager.writeVersion(projectPath, updatedVersion);

package/lib/adoption/backup-manager.js

@@ -315,6 +315,7 @@ class BackupManager {
     const criticalPatterns = [
       'steering/CORE_PRINCIPLES.md',
       'steering/ENVIRONMENT.md',
+      'config/studio-security.json',
       'version.json',
       'adoption-config.json'
     ];

package/lib/adoption/detection-engine.js

@@ -161,6 +161,7 @@ class DetectionEngine {
         'steering/CURRENT_CONTEXT.md',
         'steering/RULES_GUIDE.md',
         'tools/ultrawork_enhancer.py',
+        'config/studio-security.json',
         'README.md',
         'ultrawork-application-guide.md',
         'ultrawork-integration-summary.md',

package/lib/adoption/file-classifier.js

@@ -14,7 +14,7 @@ const path = require('path');
 const FileCategory = {
   TEMPLATE: 'template',           // steering/, tools/, README.md
   USER_CONTENT: 'user-content',   // specs/, custom files
-  CONFIG: 'config',               // version.json, adoption-config.json
+  CONFIG: 'config',               // version.json, adoption-config.json, config/*.json
   GENERATED: 'generated'          // backups/, logs/, node_modules/
 };
 
@@ -62,7 +62,8 @@ class FileClassifier {
     // Config file patterns
     this.configPatterns = [
       'version.json',
-      'adoption-config.json'
+      'adoption-config.json',
+      'config/studio-security.json'
     ];
 
     // Generated directory patterns

package/lib/adoption/smart-orchestrator.js

@@ -282,6 +282,7 @@ class SmartOrchestrator {
       'steering/ENVIRONMENT.md',
       'steering/RULES_GUIDE.md',
       'tools/ultrawork_enhancer.py',
+      'config/studio-security.json',
       'README.md'
     ];
 
@@ -299,6 +300,7 @@ class SmartOrchestrator {
         '.sce/specs/',
         '.sce/steering/',
         '.sce/tools/',
+        '.sce/config/',
         '.sce/backups/',
         ...templateFiles.map(f => `.sce/${f}`),
         '.sce/version.json'
@@ -380,7 +382,7 @@ class SmartOrchestrator {
       });
 
       const result = await strategy.execute(projectPath, strategyMode, {
-        kseVersion: packageJson.version,
+        sceVersion: packageJson.version,
         dryRun: false,
         force: !skipUpdate,
         resolutionMap

package/lib/adoption/strategy-selector.js

@@ -109,6 +109,7 @@ class StrategySelector {
         'steering/ENVIRONMENT.md',
         'steering/RULES_GUIDE.md',
         'tools/ultrawork_enhancer.py',
+        'config/studio-security.json',
         'README.md'
       ];
 

package/lib/adoption/template-sync.js

@@ -28,6 +28,7 @@ class TemplateSync {
       'steering/ENVIRONMENT.md',
       'steering/RULES_GUIDE.md',
       'tools/ultrawork_enhancer.py',
+      'config/studio-security.json',
       'README.md',
       'ultrawork-application-guide.md',
       'ultrawork-integration-summary.md',

package/lib/commands/adopt.js

@@ -285,7 +285,7 @@ async function adoptInteractive(projectPath, options) {
       const packageJson = require('../../package.json');
       
       const result = await adoptionStrategy.execute(projectPath, strategy, {
-        kseVersion: packageJson.version,
+        sceVersion: packageJson.version,
         dryRun: true,
         force
       });
@@ -494,7 +494,7 @@ async function adoptInteractive(projectPath, options) {
     const packageJson = require('../../package.json');
     
     const result = await adoptionStrategy.execute(projectPath, strategy, {
-      kseVersion: packageJson.version,
+      sceVersion: packageJson.version,
       dryRun: false,
       backupId,
       force,