scene-capability-engine 3.6.9 → 3.6.10

package/CHANGELOG.md

@@ -7,6 +7,20 @@ 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

package/README.md

@@ -218,5 +218,5 @@ MIT. See [LICENSE](LICENSE).
 
 ---
 
-**Version**: 3.6.9  
+**Version**: 3.6.10  
 **Last Updated**: 2026-03-05

package/README.zh.md

@@ -218,5 +218,5 @@ MIT，见 [LICENSE](LICENSE)。
 
 ---
 
-**版本**：3.6.9  
+**版本**：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/command-reference.md

@@ -1847,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`
+

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

@@ -0,0 +1,172 @@
+# Magicball 能力迭代管理（SCE 对接说明）
+
+> 适用于：Magicball AI 助手页面新增顶部图标入口，内部用页签切换。
+> 目标：从历史 `scene/spec/task` 中提炼可复用能力模板，并完成本体映射，形成可发布的能力资产。
+
+---
+
+## 1. 目标与范围
+
+- 目标：从历史 `scene/spec/task` 中提炼能力模板，并完成 ontology 映射闭环。
+- 范围：Magicball UI 新增「能力迭代」入口（顶部图标），内部用页签完成全流程。
+
+---
+
+## 2. UI 草图（文字版）
+
+### 2.1 能力迭代首页（Scene 盘点）
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 能力迭代                                                    │
+│ [筛选：时间 | 完成率 | 风险] [搜索：scene id]                │
+├─────────────────────────────────────────────────────────────┤
+│ Scene卡片：scene.customer-order                              │
+│ - spec: 3  tasks: 42  completed: 36  pending: 6             │
+│ - score: 未评估                                              │
+│ [进入评估]                                                   │
+├─────────────────────────────────────────────────────────────┤
+│ Scene卡片：scene.inventory-reconcile                          │
+│ - spec: 2  tasks: 18  completed: 18  pending: 0             │
+│ [进入评估]                                                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 评估页（Spec/Task + 评分卡）
+```
+┌───────────────┬─────────────────────────────────────────────┐
+│ Spec列表      │ 评分卡                                        │
+│ - 01-00-demo  │ value: 78  reuse: 66  stability: 85  risk: 20 │
+│ - 01-01-check │ completion: 0.86                              │
+│ - 01-02-order │                                               │
+├───────────────┼─────────────────────────────────────────────┤
+│ Task摘要      │ [生成模板候选]                                │
+│ total: 42     │                                               │
+│ completed:36  │                                               │
+│ pending: 6    │                                               │
+└───────────────┴─────────────────────────────────────────────┘
+```
+
+### 2.3 模板构建页（元信息 + 本体映射）
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 模板信息                                                    │
+│ name: [Capability template: scene.customer-order]            │
+│ desc: [模板描述 ...]                                         │
+│ tags: [order, customer, inventory]                           │
+├─────────────────────────────────────────────────────────────┤
+│ 本体映射                                                     │
+│ domains: [commerce]                                          │
+│ entities: [Order, Customer]                                  │
+│ relations: [Order->Customer]                                 │
+│ business_rules: [OrderApproval]                              │
+│ decisions: [RiskPolicy]                                      │
+├─────────────────────────────────────────────────────────────┤
+│ [保存映射] [进入发布]                                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 2.4 发布页（模板包生成）
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 发布结果                                                    │
+│ template_id: scene.customer-order                             │
+│ output_dir: .sce/templates/exports/capability-scene_customer… │
+│ files:                                                      │
+│ - capability-template.json                                  │
+│ - template-registry.json                                    │
+│ [复制路径] [推送模板库]                                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. 推荐 UI 架构（顶部图标 + 页签）
+
+顶部图标入口：`能力迭代`
+
+内部页签建议：
+1. `Scene 盘点`
+2. `评估`
+3. `模板构建`
+4. `发布`
+
+状态机建议：
+`extract -> score -> map -> register`
+
+---
+
+## 4. SCE 接口参数（CLI 可封装）
+
+### 4.1 提取候选能力
+```bash
+sce capability extract --scene <sceneId> --json
+```
+可选参数：
+- `--specs <spec-id, spec-id>`
+- `--out <path>`
+- `--sample-limit <n>`
+
+### 4.2 评分
+```bash
+sce capability score --input <candidate.json> --json
+```
+
+### 4.3 本体映射
+```bash
+sce capability map --input <candidate.json> --mapping <ontology.json> --json
+```
+可选参数：
+- `--template-id <id>`
+- `--name <name>`
+- `--description <desc>`
+- `--category <category>`
+- `--tags <tag1,tag2>`
+
+### 4.4 发布模板包
+```bash
+sce capability register --input <template.json> --json
+```
+可选参数：
+- `--out <dir>`
+- `--risk-level <low|medium|high|critical>`
+- `--difficulty <beginner|intermediate|advanced>`
+- `--tags <tag1,tag2>`
+- `--applicable-scenarios <scene1,scene2>`
+
+---
+
+## 5. 数据契约（前端对接）
+
+- UI 契约：`docs/agent-runtime/capability-iteration-ui.schema.json`
+- 本体映射 schema：`docs/ontology/capability-mapping.schema.json`
+
+---
+
+## 6. 前端适配建议
+
+### 6.1 状态管理
+- 采用步骤式状态机：`extract -> score -> map -> register`
+- 每一步输出的 JSON 都持久化，便于回放/复用
+
+### 6.2 体验优化
+- Scene 首页显示完成率、待处理数、评分卡入口
+- 评分卡统一可视化（value/reuse/stability/risk）
+- 本体映射表单应支持快速导入与默认推荐值
+
+### 6.3 错误处理
+- CLI 失败时直接展示错误原因
+- `task_error` 存在时提示 spec 任务文件缺失或解析失败
+- 保留上一步产物可继续重试
+
+### 6.4 权限与治理
+- 若涉及写入本体或发布模板，建议通过 SCE auth lease 授权
+
+---
+
+## 7. 推荐路由
+
+- `/capability` Scene 首页  
+- `/capability/scene/:sceneId` 评估页  
+- `/capability/scene/:sceneId/template` 模板构建页  
+- `/capability/scene/:sceneId/release` 发布页  
+

package/docs/ontology/capability-mapping.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://scene-capability-engine.dev/contracts/capability-mapping.schema.json",
+  "title": "Capability Ontology Mapping",
+  "type": "object",
+  "required": [
+    "ontology_scope"
+  ],
+  "properties": {
+    "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
+    },
+    "notes": {
+      "type": "string"
+    },
+    "source": {
+      "type": "string"
+    },
+    "version": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": false
+}

package/lib/commands/capability.js

@@ -0,0 +1,634 @@
+/**
+ * Capability Iteration Commands
+ *
+ * Extracts capability candidates from scene/spec/task history,
+ * scores candidates, maps them to ontology scope, and exports
+ * registry-ready capability template packages.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const TaskClaimer = require('../task/task-claimer');
+const { runStudioSpecGovernance } = require('../studio/spec-intake-governor');
+const { SceStateStore } = require('../state/sce-state-store');
+const packageJson = require('../../package.json');
+
+const DEFAULT_ITERATION_DIR = '.sce/reports/capability-iteration';
+const DEFAULT_EXPORT_ROOT = '.sce/templates/exports';
+
+function normalizeText(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function normalizeStringArray(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map((item) => normalizeText(item)).filter(Boolean);
+}
+
+function normalizeBoolean(value, fallback = false) {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  const normalized = normalizeText(`${value || ''}`).toLowerCase();
+  if (!normalized) {
+    return fallback;
+  }
+  if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) {
+    return false;
+  }
+  return fallback;
+}
+
+function toPositiveInteger(value, fallback) {
+  const parsed = Number.parseInt(`${value}`, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
+function buildDefaultCandidatePath(sceneId) {
+  const safeScene = normalizeText(sceneId).replace(/[^\w.-]+/g, '_') || 'scene';
+  return path.join(DEFAULT_ITERATION_DIR, `${safeScene}.candidate.json`);
+}
+
+function buildDefaultScorePath(sceneId) {
+  const safeScene = normalizeText(sceneId).replace(/[^\w.-]+/g, '_') || 'scene';
+  return path.join(DEFAULT_ITERATION_DIR, `${safeScene}.score.json`);
+}
+
+function buildDefaultTemplatePath(sceneId) {
+  const safeScene = normalizeText(sceneId).replace(/[^\w.-]+/g, '_') || 'scene';
+  return path.join(DEFAULT_ITERATION_DIR, `${safeScene}.template.json`);
+}
+
+function buildDefaultExportDir(templateId) {
+  const safeId = normalizeText(templateId).replace(/[^\w.-]+/g, '_') || 'capability';
+  return path.join(DEFAULT_EXPORT_ROOT, `capability-${safeId}`);
+}
+
+function buildSceneIdFromCandidate(candidate) {
+  return normalizeText(candidate && candidate.scene_id) || 'scene.unknown';
+}
+
+async function loadSceneIndexFromFile(projectPath, fileSystem) {
+  const indexPath = path.join(projectPath, '.sce', 'spec-governance', 'scene-index.json');
+  if (!await fileSystem.pathExists(indexPath)) {
+    return null;
+  }
+  try {
+    const data = await fileSystem.readJson(indexPath);
+    return {
+      source: indexPath,
+      data
+    };
+  } catch (_error) {
+    return null;
+  }
+}
+
+async function loadSceneIndexFromState(projectPath, fileSystem, env) {
+  try {
+    const stateStore = new SceStateStore(projectPath, {
+      fileSystem,
+      env
+    });
+    const records = await stateStore.listGovernanceSceneIndexRecords({ limit: 500 });
+    if (!Array.isArray(records)) {
+      return null;
+    }
+    const scenes = {};
+    for (const record of records) {
+      if (!record || !record.scene_id) {
+        continue;
+      }
+      scenes[record.scene_id] = {
+        total_specs: record.total_specs,
+        active_specs: record.active_specs,
+        completed_specs: record.completed_specs,
+        stale_specs: record.stale_specs,
+        spec_ids: Array.isArray(record.spec_ids) ? record.spec_ids : [],
+        active_spec_ids: Array.isArray(record.active_spec_ids) ? record.active_spec_ids : [],
+        stale_spec_ids: Array.isArray(record.stale_spec_ids) ? record.stale_spec_ids : []
+      };
+    }
+    return {
+      source: 'sqlite:governance_scene_index_registry',
+      data: {
+        schema_version: '1.0',
+        generated_at: new Date().toISOString(),
+        scene_filter: null,
+        scenes
+      }
+    };
+  } catch (_error) {
+    return null;
+  }
+}
+
+async function resolveSceneSpecs(sceneId, options, dependencies) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const env = dependencies.env || process.env;
+
+  const explicitSpecs = normalizeStringArray(options && options.specs);
+  if (explicitSpecs.length > 0) {
+    return {
+      scene_id: sceneId,
+      spec_ids: explicitSpecs,
+      source: 'options.specs'
+    };
+  }
+
+  const indexFile = await loadSceneIndexFromFile(projectPath, fileSystem);
+  if (indexFile && indexFile.data && indexFile.data.scenes && indexFile.data.scenes[sceneId]) {
+    const record = indexFile.data.scenes[sceneId];
+    return {
+      scene_id: sceneId,
+      spec_ids: Array.isArray(record.spec_ids) ? record.spec_ids : [],
+      source: indexFile.source
+    };
+  }
+
+  const indexState = await loadSceneIndexFromState(projectPath, fileSystem, env);
+  if (indexState && indexState.data && indexState.data.scenes && indexState.data.scenes[sceneId]) {
+    const record = indexState.data.scenes[sceneId];
+    return {
+      scene_id: sceneId,
+      spec_ids: Array.isArray(record.spec_ids) ? record.spec_ids : [],
+      source: indexState.source
+    };
+  }
+
+  const governanceReport = await runStudioSpecGovernance({
+    apply: false,
+    scene: sceneId
+  }, {
+    projectPath,
+    fileSystem
+  });
+  if (governanceReport && Array.isArray(governanceReport.scenes)) {
+    const target = governanceReport.scenes.find((scene) => normalizeText(scene.scene_id) === sceneId);
+    if (target) {
+      return {
+        scene_id: sceneId,
+        spec_ids: Array.isArray(target.specs)
+          ? target.specs.map((item) => normalizeText(item.spec_id)).filter(Boolean)
+          : [],
+        source: 'studio-spec-governance'
+      };
+    }
+  }
+
+  return {
+    scene_id: sceneId,
+    spec_ids: [],
+    source: 'unknown'
+  };
+}
+
+function summarizeTasks(tasks) {
+  const summary = {
+    total: 0,
+    completed: 0,
+    in_progress: 0,
+    queued: 0,
+    not_started: 0,
+    unknown: 0
+  };
+
+  if (!Array.isArray(tasks)) {
+    return summary;
+  }
+
+  summary.total = tasks.length;
+  tasks.forEach((task) => {
+    const status = normalizeText(task && task.status);
+    if (status === 'completed') {
+      summary.completed += 1;
+    } else if (status === 'in-progress') {
+      summary.in_progress += 1;
+    } else if (status === 'queued') {
+      summary.queued += 1;
+    } else if (status === 'not-started') {
+      summary.not_started += 1;
+    } else {
+      summary.unknown += 1;
+    }
+  });
+
+  return summary;
+}
+
+function buildCandidateSummary(specs) {
+  const summary = {
+    spec_count: specs.length,
+    task_total: 0,
+    task_completed: 0,
+    task_pending: 0
+  };
+  specs.forEach((spec) => {
+    const taskSummary = spec.task_summary || {};
+    summary.task_total += Number(taskSummary.total || 0);
+    summary.task_completed += Number(taskSummary.completed || 0);
+  });
+  summary.task_pending = Math.max(0, summary.task_total - summary.task_completed);
+  return summary;
+}
+
+function buildScoreFromCandidate(candidate) {
+  const summary = candidate && candidate.summary ? candidate.summary : {};
+  const taskTotal = Number(summary.task_total || 0);
+  const taskCompleted = Number(summary.task_completed || 0);
+  const specCount = Number(summary.spec_count || 0);
+  const completionRate = taskTotal > 0 ? taskCompleted / taskTotal : 0;
+  const reuseScore = Math.min(100, Math.round((specCount / 3) * 100));
+  const stabilityScore = Math.round(completionRate * 100);
+  const riskScore = Math.min(100, Math.round((1 - completionRate) * 100));
+  const valueScore = Math.round((stabilityScore * 0.5) + (reuseScore * 0.3) + ((100 - riskScore) * 0.2));
+
+  return {
+    completion_rate: Number(completionRate.toFixed(3)),
+    reuse_score: reuseScore,
+    stability_score: stabilityScore,
+    risk_score: riskScore,
+    value_score: valueScore
+  };
+}
+
+function buildTemplateCandidate(candidate, mapping, options) {
+  const sceneId = buildSceneIdFromCandidate(candidate);
+  const templateId = normalizeText(options && options.template_id)
+    || normalizeText(options && options.id)
+    || sceneId.replace(/[^\w.-]+/g, '_');
+  const name = normalizeText(options && options.name)
+    || `Capability template: ${sceneId}`;
+  const description = normalizeText(options && options.description)
+    || `Capability template derived from ${sceneId}`;
+  const category = normalizeText(options && options.category) || 'capability';
+  const tags = normalizeStringArray(options && options.tags);
+  const ontologyScope = (mapping && mapping.ontology_scope && typeof mapping.ontology_scope === 'object')
+    ? mapping.ontology_scope
+    : {
+        domains: [],
+        entities: [],
+        relations: [],
+        business_rules: [],
+        decisions: []
+      };
+
+  return {
+    mode: 'capability-template',
+    template_id: templateId,
+    name,
+    description,
+    category,
+    template_type: 'capability-template',
+    scene_id: sceneId,
+    source_candidate: candidate,
+    ontology_scope: ontologyScope,
+    tags,
+    created_at: new Date().toISOString()
+  };
+}
+
+function buildRegistryEntry(templateCandidate, options) {
+  const riskLevel = normalizeText(options && options.risk_level) || 'medium';
+  const difficulty = normalizeText(options && options.difficulty) || 'intermediate';
+  const applicable = normalizeStringArray(options && options.applicable_scenarios);
+  const tags = normalizeStringArray(options && options.tags);
+  const sceneId = buildSceneIdFromCandidate(templateCandidate);
+  const safeTags = tags.length > 0 ? tags : ['capability', sceneId];
+  const safeApplicable = applicable.length > 0 ? applicable : [sceneId];
+
+  return {
+    id: templateCandidate.template_id,
+    name: templateCandidate.name,
+    category: templateCandidate.category,
+    description: templateCandidate.description,
+    difficulty,
+    tags: safeTags,
+    applicable_scenarios: safeApplicable,
+    files: ['capability-template.json'],
+    template_type: 'capability-template',
+    min_sce_version: packageJson.version,
+    max_sce_version: null,
+    risk_level: riskLevel,
+    rollback_contract: {
+      supported: false,
+      strategy: 'n/a'
+    },
+    ontology_scope: templateCandidate.ontology_scope
+  };
+}
+
+async function runCapabilityExtractCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const env = dependencies.env || process.env;
+  const sceneId = normalizeText(options.scene || options.sceneId || options.scene_id);
+  const writeOutput = normalizeBoolean(options.write, true);
+
+  if (!sceneId) {
+    throw new Error('scene is required for capability extract');
+  }
+
+  const specResolution = await resolveSceneSpecs(sceneId, {
+    specs: options.specs
+  }, { projectPath, fileSystem, env });
+  const specIds = Array.isArray(specResolution.spec_ids) ? specResolution.spec_ids : [];
+
+  const taskClaimer = new TaskClaimer();
+  const specs = [];
+
+  for (const specId of specIds) {
+    const tasksPath = path.join(projectPath, '.sce', 'specs', specId, 'tasks.md');
+    let tasks = [];
+    let taskError = null;
+    if (await fileSystem.pathExists(tasksPath)) {
+      try {
+        tasks = await taskClaimer.parseTasks(tasksPath, { preferStatusMarkers: true });
+      } catch (error) {
+        taskError = error.message;
+      }
+    } else {
+      taskError = 'tasks.md missing';
+    }
+    const taskSummary = summarizeTasks(tasks);
+    specs.push({
+      spec_id: specId,
+      tasks_path: path.relative(projectPath, tasksPath),
+      task_summary: taskSummary,
+      task_sample: tasks.slice(0, toPositiveInteger(options.sample_limit, 5)).map((task) => ({
+        id: task.taskId,
+        title: task.title,
+        status: task.status
+      })),
+      task_error: taskError
+    });
+  }
+
+  const payload = {
+    mode: 'capability-extract',
+    scene_id: sceneId,
+    generated_at: new Date().toISOString(),
+    source: {
+      scene_index_source: specResolution.source || 'unknown',
+      spec_count: specIds.length
+    },
+    specs,
+    summary: buildCandidateSummary(specs)
+  };
+
+  const outputPath = normalizeText(options.out) || buildDefaultCandidatePath(sceneId);
+  if (writeOutput) {
+    await fileSystem.ensureDir(path.dirname(path.join(projectPath, outputPath)));
+    await fileSystem.writeJson(path.join(projectPath, outputPath), payload, { spaces: 2 });
+    payload.output_file = outputPath;
+  }
+
+  if (!normalizeBoolean(options.json, false)) {
+    console.log(chalk.green('✅ Capability candidate extracted'));
+    console.log(chalk.gray(`  Scene: ${sceneId}`));
+    console.log(chalk.gray(`  Specs: ${payload.summary.spec_count}`));
+    console.log(chalk.gray(`  Tasks: ${payload.summary.task_total}`));
+    if (payload.output_file) {
+      console.log(chalk.gray(`  Output: ${payload.output_file}`));
+    }
+  }
+
+  return payload;
+}
+
+async function runCapabilityScoreCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const inputPath = normalizeText(options.input || options.file);
+  if (!inputPath) {
+    throw new Error('input candidate file is required for capability score');
+  }
+
+  const candidate = await fileSystem.readJson(path.join(projectPath, inputPath));
+  const sceneId = buildSceneIdFromCandidate(candidate);
+  const scores = buildScoreFromCandidate(candidate);
+  const payload = {
+    mode: 'capability-score',
+    scene_id: sceneId,
+    generated_at: new Date().toISOString(),
+    input: inputPath,
+    scores,
+    summary: candidate && candidate.summary ? candidate.summary : null
+  };
+
+  const outputPath = normalizeText(options.out) || buildDefaultScorePath(sceneId);
+  if (normalizeBoolean(options.write, true)) {
+    await fileSystem.ensureDir(path.dirname(path.join(projectPath, outputPath)));
+    await fileSystem.writeJson(path.join(projectPath, outputPath), payload, { spaces: 2 });
+    payload.output_file = outputPath;
+  }
+
+  if (!normalizeBoolean(options.json, false)) {
+    console.log(chalk.green('✅ Capability score generated'));
+    console.log(chalk.gray(`  Scene: ${sceneId}`));
+    console.log(chalk.gray(`  Value score: ${scores.value_score}`));
+    if (payload.output_file) {
+      console.log(chalk.gray(`  Output: ${payload.output_file}`));
+    }
+  }
+
+  return payload;
+}
+
+async function runCapabilityMapCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const inputPath = normalizeText(options.input || options.file);
+  if (!inputPath) {
+    throw new Error('input candidate file is required for capability map');
+  }
+
+  const mappingPath = normalizeText(options.mapping);
+  const candidate = await fileSystem.readJson(path.join(projectPath, inputPath));
+  const mapping = mappingPath
+    ? await fileSystem.readJson(path.join(projectPath, mappingPath))
+    : { ontology_scope: { domains: [], entities: [], relations: [], business_rules: [], decisions: [] } };
+
+  const templateCandidate = buildTemplateCandidate(candidate, mapping, options);
+  const sceneId = buildSceneIdFromCandidate(candidate);
+  const payload = {
+    mode: 'capability-map',
+    scene_id: sceneId,
+    generated_at: new Date().toISOString(),
+    input: inputPath,
+    mapping: mappingPath || null,
+    template: templateCandidate
+  };
+
+  const outputPath = normalizeText(options.out) || buildDefaultTemplatePath(sceneId);
+  if (normalizeBoolean(options.write, true)) {
+    await fileSystem.ensureDir(path.dirname(path.join(projectPath, outputPath)));
+    await fileSystem.writeJson(path.join(projectPath, outputPath), payload, { spaces: 2 });
+    payload.output_file = outputPath;
+  }
+
+  if (!normalizeBoolean(options.json, false)) {
+    console.log(chalk.green('✅ Capability ontology mapping prepared'));
+    console.log(chalk.gray(`  Scene: ${sceneId}`));
+    if (payload.output_file) {
+      console.log(chalk.gray(`  Output: ${payload.output_file}`));
+    }
+  }
+
+  return payload;
+}
+
+async function runCapabilityRegisterCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const inputPath = normalizeText(options.input || options.file);
+  if (!inputPath) {
+    throw new Error('input template file is required for capability register');
+  }
+
+  const payload = await fileSystem.readJson(path.join(projectPath, inputPath));
+  const templateCandidate = payload.template || payload;
+  if (!templateCandidate || !templateCandidate.template_id) {
+    throw new Error('template_id missing in capability template candidate');
+  }
+
+  const exportDir = normalizeText(options.out) || buildDefaultExportDir(templateCandidate.template_id);
+  const outputDirAbs = path.join(projectPath, exportDir);
+  await fileSystem.ensureDir(outputDirAbs);
+
+  const registryEntry = buildRegistryEntry(templateCandidate, options);
+  const registryPayload = {
+    version: '1.0',
+    templates: [registryEntry]
+  };
+
+  await fileSystem.writeJson(path.join(outputDirAbs, 'capability-template.json'), templateCandidate, { spaces: 2 });
+  await fileSystem.writeJson(path.join(outputDirAbs, 'template-registry.json'), registryPayload, { spaces: 2 });
+
+  const result = {
+    mode: 'capability-register',
+    template_id: templateCandidate.template_id,
+    output_dir: exportDir,
+    files: [
+      path.join(exportDir, 'capability-template.json'),
+      path.join(exportDir, 'template-registry.json')
+    ]
+  };
+
+  if (!normalizeBoolean(options.json, false)) {
+    console.log(chalk.green('✅ Capability template package exported'));
+    console.log(chalk.gray(`  Template: ${templateCandidate.template_id}`));
+    console.log(chalk.gray(`  Output: ${exportDir}`));
+  }
+
+  return result;
+}
+
+function registerCapabilityCommands(program) {
+  const capabilityCmd = program
+    .command('capability')
+    .description('Extract and manage capability templates from scene/spec/task history');
+
+  capabilityCmd
+    .command('extract')
+    .description('Extract capability candidate from a scene')
+    .requiredOption('--scene <scene-id>', 'Scene identifier')
+    .option('--specs <spec-ids>', 'Comma-separated spec identifiers')
+    .option('--out <path>', 'Output JSON path')
+    .option('--sample-limit <n>', 'Max tasks per spec in sample', '5')
+    .option('--no-write', 'Skip writing output file')
+    .option('--json', 'Output JSON to stdout')
+    .action(async (options) => {
+      const specs = normalizeText(options.specs)
+        ? normalizeText(options.specs).split(',').map((item) => normalizeText(item)).filter(Boolean)
+        : [];
+      await runCapabilityExtractCommand({
+        scene: options.scene,
+        specs,
+        out: options.out,
+        sample_limit: options.sampleLimit,
+        write: options.write,
+        json: options.json
+      });
+    });
+
+  capabilityCmd
+    .command('score')
+    .description('Score a capability candidate')
+    .requiredOption('--input <path>', 'Input candidate JSON')
+    .option('--out <path>', 'Output JSON path')
+    .option('--no-write', 'Skip writing output file')
+    .option('--json', 'Output JSON to stdout')
+    .action(async (options) => {
+      await runCapabilityScoreCommand(options);
+    });
+
+  capabilityCmd
+    .command('map')
+    .description('Attach ontology mapping to a capability candidate')
+    .requiredOption('--input <path>', 'Input candidate JSON')
+    .option('--mapping <path>', 'Ontology mapping JSON')
+    .option('--template-id <id>', 'Template identifier')
+    .option('--name <name>', 'Template name')
+    .option('--description <desc>', 'Template description')
+    .option('--category <category>', 'Template category')
+    .option('--tags <tags>', 'Comma-separated tags')
+    .option('--out <path>', 'Output JSON path')
+    .option('--no-write', 'Skip writing output file')
+    .option('--json', 'Output JSON to stdout')
+    .action(async (options) => {
+      const tags = normalizeText(options.tags)
+        ? normalizeText(options.tags).split(',').map((item) => normalizeText(item)).filter(Boolean)
+        : [];
+      await runCapabilityMapCommand({
+        ...options,
+        tags
+      });
+    });
+
+  capabilityCmd
+    .command('register')
+    .description('Export a registry-ready capability template package')
+    .requiredOption('--input <path>', 'Input template JSON (output of capability map)')
+    .option('--out <path>', 'Output directory')
+    .option('--difficulty <level>', 'Difficulty (beginner|intermediate|advanced)')
+    .option('--risk-level <level>', 'Risk level (low|medium|high|critical)')
+    .option('--tags <tags>', 'Comma-separated tags')
+    .option('--applicable-scenarios <scenes>', 'Comma-separated applicable scenarios')
+    .option('--json', 'Output JSON to stdout')
+    .action(async (options) => {
+      const tags = normalizeText(options.tags)
+        ? normalizeText(options.tags).split(',').map((item) => normalizeText(item)).filter(Boolean)
+        : [];
+      const applicable = normalizeText(options.applicableScenarios)
+        ? normalizeText(options.applicableScenarios).split(',').map((item) => normalizeText(item)).filter(Boolean)
+        : [];
+      await runCapabilityRegisterCommand({
+        ...options,
+        risk_level: options.riskLevel,
+        applicable_scenarios: applicable,
+        tags
+      });
+    });
+}
+
+module.exports = {
+  registerCapabilityCommands,
+  runCapabilityExtractCommand,
+  runCapabilityScoreCommand,
+  runCapabilityMapCommand,
+  runCapabilityRegisterCommand
+};

package/package.json

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