scene-capability-engine 3.6.8 → 3.6.10

package/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.10] - 2026-03-05
+
+### Added
+- Capability iteration CLI for scene/spec/task history:
+  - `sce capability extract`
+  - `sce capability score`
+  - `sce capability map`
+  - `sce capability register`
+- Extracted capability candidates now include task summaries and scene/spec provenance for UI governance workflows.
+- Added schema references for capability iteration UI contract and ontology mapping.
+- Magicball capability iteration docs:
+  - `docs/magicball-capability-iteration-ui.md`
+  - `docs/magicball-capability-iteration-api.md`
+
+## [3.6.9] - 2026-03-05
+
+### Added
+- Orchestration runtime now emits machine-readable `rate-limit:decision` telemetry events for retry/throttle/hold/recovery transitions.
+- New anti-429 runtime config knobs in `.sce/config/orchestrator.json`:
+  - `rateLimitRetrySpreadMs`
+  - `rateLimitLaunchHoldPollMs`
+  - `rateLimitDecisionEventThrottleMs`
+
+### Changed
+- Rate-limit retries now apply deterministic per-spec retry spread to reduce synchronized 429 bursts under high parallelism.
+- Launch-hold polling interval is now configurable, so anti-429 pause loops can be tuned for responsiveness vs overhead.
+
 ## [3.6.8] - 2026-03-05
 
 ### Added

package/README.md

@@ -121,6 +121,7 @@ SCE is tool-agnostic and works with Codex, Claude Code, Cursor, Windsurf, VS Cod
 - Session governance is scene-first: `1 scene = 1 primary session`.
 - Spec work is attached as child sessions and auto-archived.
 - Startup now auto-detects adopted projects and aligns takeover baseline defaults automatically.
+- Multi-agent anti-429 runtime now supports deterministic retry spread and machine-readable `rate-limit:decision` telemetry (`rateLimitRetrySpreadMs`, `rateLimitLaunchHoldPollMs`, `rateLimitDecisionEventThrottleMs`).
 - Problem evaluation policy is enabled by default (`.sce/config/problem-eval-policy.json`) and evaluates every Studio stage.
 - Problem closure policy is enabled by default (`.sce/config/problem-closure-policy.json`) and blocks verify/release bypass when required domain/problem evidence is missing.
 - Error handling now follows a full incident loop by default: every record attempt is staged first and auto-closed on verified/promoted outcomes.
@@ -217,5 +218,5 @@ MIT. See [LICENSE](LICENSE).
 
 ---
 
-**Version**: 3.6.3  
+**Version**: 3.6.10  
 **Last Updated**: 2026-03-05

package/README.zh.md

@@ -121,6 +121,7 @@ SCE 对工具无锁定，可接入 Codex、Claude Code、Cursor、Windsurf、VS
 - 会话治理默认场景优先：`1 scene = 1 primary session`。
 - Spec 执行作为子会话自动归档，支持跨轮次追踪。
 - 启动时会自动识别已接管项目并对齐接管基线默认配置。
+- 多 Agent 抗 429 运行时新增“确定性重试错峰 + 机器可读 `rate-limit:decision` 事件”，可通过 `rateLimitRetrySpreadMs`、`rateLimitLaunchHoldPollMs`、`rateLimitDecisionEventThrottleMs` 调优。
 - 问题评估策略默认启用（`.sce/config/problem-eval-policy.json`），Studio 各阶段都会执行评估。
 - 问题闭环策略默认启用（`.sce/config/problem-closure-policy.json`），缺失必要问题/领域证据时会在 verify/release 阶段阻断。
 - 错误处理默认进入完整 incident 闭环：每次记录先落到 staging 试错链路，verified/promoted 后自动收束归档。
@@ -217,5 +218,5 @@ MIT，见 [LICENSE](LICENSE)。
 
 ---
 
-**版本**：3.6.3  
+**版本**：3.6.10  
 **最后更新**：2026-03-05

package/bin/scene-capability-engine.js

@@ -26,6 +26,7 @@ const { registerValueCommands } = require('../lib/commands/value');
 const { registerTaskCommands } = require('../lib/commands/task');
 const { registerAuthCommands } = require('../lib/commands/auth');
 const { registerStateCommands } = require('../lib/commands/state');
+const { registerCapabilityCommands } = require('../lib/commands/capability');
 const VersionChecker = require('../lib/version/version-checker');
 const {
   findLegacyKiroDirectories,
@@ -976,6 +977,7 @@ registerValueCommands(program);
 registerTaskCommands(program);
 registerAuthCommands(program);
 registerStateCommands(program);
+registerCapabilityCommands(program);
 
 // Template management commands
 const templatesCommand = require('../lib/commands/templates');

package/docs/agent-runtime/capability-iteration-ui.schema.json

@@ -0,0 +1,226 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://scene-capability-engine.dev/contracts/capability-iteration-ui.schema.json",
+  "title": "Capability Iteration UI Contract",
+  "type": "object",
+  "required": [
+    "candidate",
+    "score",
+    "mapping",
+    "registry"
+  ],
+  "properties": {
+    "candidate": {
+      "$ref": "#/definitions/candidate"
+    },
+    "score": {
+      "$ref": "#/definitions/score"
+    },
+    "mapping": {
+      "$ref": "#/definitions/mapping"
+    },
+    "registry": {
+      "$ref": "#/definitions/registry"
+    }
+  },
+  "definitions": {
+    "candidate": {
+      "type": "object",
+      "required": [
+        "mode",
+        "scene_id",
+        "generated_at",
+        "source",
+        "specs",
+        "summary"
+      ],
+      "properties": {
+        "mode": {
+          "const": "capability-extract"
+        },
+        "scene_id": { "type": "string" },
+        "generated_at": { "type": "string" },
+        "output_file": { "type": "string" },
+        "source": {
+          "type": "object",
+          "required": ["scene_index_source", "spec_count"],
+          "properties": {
+            "scene_index_source": { "type": "string" },
+            "spec_count": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        "specs": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["spec_id", "tasks_path", "task_summary"],
+            "properties": {
+              "spec_id": { "type": "string" },
+              "tasks_path": { "type": "string" },
+              "task_error": { "type": "string" },
+              "task_summary": {
+                "type": "object",
+                "required": [
+                  "total",
+                  "completed",
+                  "in_progress",
+                  "queued",
+                  "not_started",
+                  "unknown"
+                ],
+                "properties": {
+                  "total": { "type": "integer", "minimum": 0 },
+                  "completed": { "type": "integer", "minimum": 0 },
+                  "in_progress": { "type": "integer", "minimum": 0 },
+                  "queued": { "type": "integer", "minimum": 0 },
+                  "not_started": { "type": "integer", "minimum": 0 },
+                  "unknown": { "type": "integer", "minimum": 0 }
+                },
+                "additionalProperties": false
+              },
+              "task_sample": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["id", "title", "status"],
+                  "properties": {
+                    "id": { "type": "string" },
+                    "title": { "type": "string" },
+                    "status": { "type": "string" }
+                  },
+                  "additionalProperties": false
+                }
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "summary": {
+          "type": "object",
+          "required": ["spec_count", "task_total", "task_completed", "task_pending"],
+          "properties": {
+            "spec_count": { "type": "integer", "minimum": 0 },
+            "task_total": { "type": "integer", "minimum": 0 },
+            "task_completed": { "type": "integer", "minimum": 0 },
+            "task_pending": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "score": {
+      "type": "object",
+      "required": [
+        "mode",
+        "scene_id",
+        "generated_at",
+        "input",
+        "scores"
+      ],
+      "properties": {
+        "mode": { "const": "capability-score" },
+        "scene_id": { "type": "string" },
+        "generated_at": { "type": "string" },
+        "input": { "type": "string" },
+        "output_file": { "type": "string" },
+        "scores": {
+          "type": "object",
+          "required": [
+            "completion_rate",
+            "reuse_score",
+            "stability_score",
+            "risk_score",
+            "value_score"
+          ],
+          "properties": {
+            "completion_rate": { "type": "number", "minimum": 0, "maximum": 1 },
+            "reuse_score": { "type": "integer", "minimum": 0, "maximum": 100 },
+            "stability_score": { "type": "integer", "minimum": 0, "maximum": 100 },
+            "risk_score": { "type": "integer", "minimum": 0, "maximum": 100 },
+            "value_score": { "type": "integer", "minimum": 0, "maximum": 100 }
+          },
+          "additionalProperties": false
+        },
+        "summary": { "type": ["object", "null"] }
+      },
+      "additionalProperties": false
+    },
+    "mapping": {
+      "type": "object",
+      "required": [
+        "mode",
+        "scene_id",
+        "generated_at",
+        "input",
+        "template"
+      ],
+      "properties": {
+        "mode": { "const": "capability-map" },
+        "scene_id": { "type": "string" },
+        "generated_at": { "type": "string" },
+        "input": { "type": "string" },
+        "mapping": { "type": ["string", "null"] },
+        "output_file": { "type": "string" },
+        "template": {
+          "type": "object",
+          "required": [
+            "mode",
+            "template_id",
+            "name",
+            "description",
+            "category",
+            "template_type",
+            "scene_id",
+            "ontology_scope",
+            "created_at"
+          ],
+          "properties": {
+            "mode": { "const": "capability-template" },
+            "template_id": { "type": "string" },
+            "name": { "type": "string" },
+            "description": { "type": "string" },
+            "category": { "type": "string" },
+            "template_type": { "const": "capability-template" },
+            "scene_id": { "type": "string" },
+            "tags": { "type": "array", "items": { "type": "string" } },
+            "ontology_scope": {
+              "type": "object",
+              "required": ["domains", "entities", "relations", "business_rules", "decisions"],
+              "properties": {
+                "domains": { "type": "array", "items": { "type": "string" } },
+                "entities": { "type": "array", "items": { "type": "string" } },
+                "relations": { "type": "array", "items": { "type": "string" } },
+                "business_rules": { "type": "array", "items": { "type": "string" } },
+                "decisions": { "type": "array", "items": { "type": "string" } }
+              },
+              "additionalProperties": false
+            },
+            "created_at": { "type": "string" },
+            "source_candidate": { "type": ["object", "null"] }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "registry": {
+      "type": "object",
+      "required": [
+        "mode",
+        "template_id",
+        "output_dir",
+        "files"
+      ],
+      "properties": {
+        "mode": { "const": "capability-register" },
+        "template_id": { "type": "string" },
+        "output_dir": { "type": "string" },
+        "files": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

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

@@ -23,6 +23,9 @@ This document defines the default anti-429 presets used by SCE multi-agent orche
 | `rateLimitSignalThreshold` | 2 | 3 | 4 |
 | `rateLimitSignalExtraHoldMs` | 5000 | 3000 | 2000 |
 | `rateLimitDynamicBudgetFloor` | 1 | 1 | 2 |
+| `rateLimitRetrySpreadMs` | 1200 | 600 | 250 |
+| `rateLimitLaunchHoldPollMs` | 1000 | 1000 | 1000 |
+| `rateLimitDecisionEventThrottleMs` | 1000 | 1000 | 1000 |
 
 ## Usage
 
@@ -64,3 +67,4 @@ 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.
+4. `rate-limit:decision` events are emitted as machine-readable telemetry for retry/throttle/recovery transitions.

package/docs/command-reference.md

@@ -1796,6 +1796,9 @@ Recommended `.sce/config/orchestrator.json`:
   "rateLimitSignalThreshold": 3,
   "rateLimitSignalExtraHoldMs": 3000,
   "rateLimitDynamicBudgetFloor": 1,
+  "rateLimitRetrySpreadMs": 600,
+  "rateLimitLaunchHoldPollMs": 1000,
+  "rateLimitDecisionEventThrottleMs": 1000,
   "apiKeyEnvVar": "CODEX_API_KEY",
   "codexArgs": ["--skip-git-repo-check"],
   "codexCommand": "npx @openai/codex"
@@ -1809,9 +1812,14 @@ Recommended `.sce/config/orchestrator.json`:
 - `rateLimitSignalThreshold`: signals required inside window before escalation
 - `rateLimitSignalExtraHoldMs`: extra launch hold per escalation unit
 - `rateLimitDynamicBudgetFloor`: lowest dynamic launch budget allowed during sustained pressure
+- `rateLimitRetrySpreadMs`: deterministic retry spread (per spec/retry round) to reduce synchronized retry bursts
+- `rateLimitLaunchHoldPollMs`: polling interval while launch hold is active (lower values react faster, higher values reduce loop overhead)
+- `rateLimitDecisionEventThrottleMs`: de-dup interval for repeated `rate-limit:decision` telemetry events
 
 `orchestrate stop` interrupts pending retry waits immediately so long backoff windows do not look like deadlocks.
 
+Runtime emits machine-readable `rate-limit:decision` events for retry/throttle/hold/recovery transitions, so UI or controller layers can surface anti-429 actions directly.
+
 Codex sub-agent permission defaults:
 - `--sandbox danger-full-access` is always injected by orchestrator runtime.
 - `--ask-for-approval never` is injected by default when `codexArgs` does not explicitly set approval mode.
@@ -1839,6 +1847,27 @@ sce scene template-render --package <name> --values <json-or-path> --out <dir>
 sce scene template-render --package scene-erp --values '{"entity_name":"Order"}' --out ./output --json
 ```
 
+### Capability Iteration (scene -> template -> ontology)
+
+```bash
+# 1) Extract capability candidate from scene history
+sce capability extract --scene scene.customer-order --json
+
+# 2) Score candidate value/reuse/risk
+sce capability score --input .sce/reports/capability-iteration/scene.customer-order.candidate.json --json
+
+# 3) Attach ontology mapping
+sce capability map --input .sce/reports/capability-iteration/scene.customer-order.candidate.json \
+  --mapping .sce/ontology/capability-mapping.json --json
+
+# 4) Export registry-ready capability template package
+sce capability register --input .sce/reports/capability-iteration/scene.customer-order.template.json --json
+```
+
+Schema references:
+- UI contract: `docs/agent-runtime/capability-iteration-ui.schema.json`
+- Ontology mapping: `docs/ontology/capability-mapping.schema.json`
+
 ### Scene Package Batch Publish
 
 ```bash

package/docs/magicball-capability-iteration-api.md

@@ -0,0 +1,154 @@
+# Magicball 能力迭代 API 封装建议（基于 SCE CLI）
+
+> 目标：把 SCE CLI 统一封装成 Magicball 内部 API，方便前端用标准 JSON 调用。
+
+---
+
+## 1. API 设计原则
+
+- **一处封装**：统一执行 CLI，屏蔽差异
+- **JSON 输出**：所有调用带 `--json`
+- **可回放**：每一步的输出落盘并在 UI 可复用
+- **错误可读**：将 stderr 错误结构化返回
+
+---
+
+## 2. 建议 API 列表
+
+### 2.1 Extract
+
+```
+POST /api/capability/extract
+```
+
+请求：
+```json
+{
+  "scene_id": "scene.customer-order",
+  "specs": ["01-00-order", "01-01-inventory"],
+  "sample_limit": 5
+}
+```
+
+执行 CLI：
+```bash
+sce capability extract --scene <scene_id> --specs <specs> --sample-limit <n> --json
+```
+
+响应：
+- 返回 `capability-extract` payload
+
+---
+
+### 2.2 Score
+
+```
+POST /api/capability/score
+```
+
+请求：
+```json
+{
+  "candidate_file": ".sce/reports/capability-iteration/scene.customer-order.candidate.json"
+}
+```
+
+执行 CLI：
+```bash
+sce capability score --input <candidate_file> --json
+```
+
+响应：
+- 返回 `capability-score` payload
+
+---
+
+### 2.3 Map
+
+```
+POST /api/capability/map
+```
+
+请求：
+```json
+{
+  "candidate_file": ".sce/reports/capability-iteration/scene.customer-order.candidate.json",
+  "ontology_file": ".sce/ontology/capability-mapping.json",
+  "template_id": "scene.customer-order",
+  "name": "Capability template: scene.customer-order",
+  "description": "Derived from scene.customer-order"
+}
+```
+
+执行 CLI：
+```bash
+sce capability map --input <candidate_file> --mapping <ontology_file> \
+  --template-id <template_id> --name "<name>" --description "<desc>" --json
+```
+
+响应：
+- 返回 `capability-map` payload
+
+---
+
+### 2.4 Register
+
+```
+POST /api/capability/register
+```
+
+请求：
+```json
+{
+  "template_file": ".sce/reports/capability-iteration/scene.customer-order.template.json",
+  "risk_level": "medium",
+  "difficulty": "intermediate"
+}
+```
+
+执行 CLI：
+```bash
+sce capability register --input <template_file> --risk-level <level> --difficulty <level> --json
+```
+
+响应：
+- 返回 `capability-register` payload
+
+---
+
+## 3. 通用返回结构（建议）
+
+```json
+{
+  "success": true,
+  "data": { ...sce_payload },
+  "stderr": null
+}
+```
+
+失败：
+```json
+{
+  "success": false,
+  "data": null,
+  "stderr": "error message from sce"
+}
+```
+
+---
+
+## 4. 前端调用建议
+
+- 每一步 UI 都展示对应 `data.output_file`（如有）
+- 支持“重新执行”按钮（调用同一 API）
+- 失败时提示 `stderr`，并保留上一步数据可继续
+
+---
+
+## 5. 推荐顺序
+
+1. `/api/capability/extract`
+2. `/api/capability/score`
+3. `/api/capability/map`
+4. `/api/capability/register`
+