scene-capability-engine 3.6.11 → 3.6.14

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.14] - 2026-03-06
+
+### Added
+- `sce capability use --apply` to append recommended tasks to spec tasks.md.
+
+## [3.6.13] - 2026-03-06
+
+### Added
+- Capability library reuse commands:
+  - `sce capability catalog list/search/show`
+  - `sce capability match`
+  - `sce capability use`
+- Magicball capability library integration guide:
+  - `docs/magicball-capability-library.md`
+
+## [3.6.12] - 2026-03-06
+
+### Added
+- Magicball task quality governance integration guide:
+  - `docs/magicball-task-quality-governance.md`
+
 ## [3.6.11] - 2026-03-05
 
 ### Added

package/README.md

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

package/README.zh.md

@@ -218,5 +218,5 @@ MIT，见 [LICENSE](LICENSE)。
 
 ---
 
-**版本**：3.6.11  
+**版本**：3.6.14  
 **最后更新**：2026-03-05

package/docs/command-reference.md

@@ -1888,6 +1888,29 @@ Schema references:
 - UI contract: `docs/agent-runtime/capability-iteration-ui.schema.json`
 - Ontology mapping: `docs/ontology/capability-mapping.schema.json`
 
+### Capability Library Reuse (query -> match -> use)
+
+```bash
+# List capability templates
+sce capability catalog list --json
+
+# Search capability templates
+sce capability catalog search "customer order" --json
+
+# Show capability template metadata + payload
+sce capability catalog show customer-order-core --json
+
+# Match capability templates to a spec (uses problem-domain-chain.json)
+sce capability match --spec 01-02-customer-order --json
+sce capability match --spec 01-02-customer-order --query "订单 库存" --limit 5 --json
+
+# Generate a usage plan for a spec
+sce capability use --template customer-order-core --spec 01-02-customer-order --json
+
+# Generate usage plan + append tasks to tasks.md
+sce capability use --template customer-order-core --spec 01-02-customer-order --apply --json
+```
+
 ### Scene Package Batch Publish
 
 ```bash

package/docs/magicball-capability-library.md

@@ -0,0 +1,123 @@
+# Magicball 能力库复用对接说明（SCE）
+
+> 目标：在 Magicball UI 中提供“能力库检索/匹配/使用”闭环，加速场景能力落地。
+
+## 1. 能力库复用流程
+
+1. **查询**能力库（列表/搜索）
+2. **匹配**当前 spec 的问题域（基于 problem-domain-chain 里的 ontology）
+3. **使用**能力模板（生成可执行的 usage plan）
+
+## 2. SCE CLI 支持（对 Magicball 的最小封装）
+
+### 2.1 查询与搜索
+
+```bash
+sce capability catalog list --json
+sce capability catalog search "customer order" --json
+sce capability catalog show <template-id> --json
+```
+
+### 2.2 匹配（基于 spec ontology）
+
+```bash
+sce capability match --spec <spec-id> --json
+sce capability match --spec <spec-id> --query "订单 库存" --limit 5 --json
+```
+
+匹配会读取：
+- `.sce/specs/<spec>/custom/problem-domain-chain.json`
+
+若该文件缺失，默认仍返回结果，但 `warnings` 中会标记缺失。
+
+### 2.3 使用（生成 usage plan）
+
+```bash
+sce capability use --template <template-id> --spec <spec-id> --json
+```
+
+输出：`capability-use-plan`（用于 UI 展示和后续手工应用）。
+
+如需直接写入 spec 任务：
+
+```bash
+sce capability use --template <template-id> --spec <spec-id> --apply --json
+```
+
+## 3. API 封装建议（CLI -> HTTP）
+
+建议 Magicball 后端封装为：
+
+- `POST /api/sce/capability/catalog/list`
+- `POST /api/sce/capability/catalog/search`
+- `POST /api/sce/capability/catalog/show`
+- `POST /api/sce/capability/match`
+- `POST /api/sce/capability/use`
+
+请求体示例：
+
+```json
+{
+  "specId": "01-02-customer-order",
+  "query": "订单 库存",
+  "limit": 5
+}
+```
+
+## 4. UI 行为建议（Magicball）
+
+### 4.1 能力库入口
+- 顶部图标入口
+- Tabs：`能力库` / `匹配结果` / `使用计划`
+
+### 4.2 能力库列表
+- 支持筛选：category / risk / source
+- 展示关键信息：`name` / `description` / `ontology_scope`
+
+### 4.3 匹配结果
+- 展示 `score` + `score_components`
+- 支持一键生成 usage plan
+
+### 4.4 使用计划
+- 展示 `recommended_tasks`
+- 可手工转为当前 spec 的任务
+
+## 5. 输出结构（关键字段）
+
+### capability-match
+```json
+{
+  "mode": "capability-match",
+  "spec_id": "01-02-customer-order",
+  "scene_id": "scene.customer-order",
+  "match_count": 12,
+  "matches": [
+    {
+      "template_id": "customer-order-core",
+      "score": 82,
+      "score_components": {
+        "ontology": 0.72,
+        "scenario": 1,
+        "keyword": 0.35
+      }
+    }
+  ]
+}
+```
+
+### capability-use-plan
+```json
+{
+  "mode": "capability-use-plan",
+  "template": {"id": "customer-order-core", "name": "Customer Order Core"},
+  "spec_id": "01-02-customer-order",
+  "recommended_tasks": [
+    {"title": "Define order entity"},
+    {"title": "Implement order lifecycle"}
+  ]
+}
+```
+
+---
+
+若需要“自动落地写入 spec 任务”的强制执行模式，可以在后续版本加 `--apply` 开关。

package/docs/magicball-task-quality-governance.md

@@ -0,0 +1,301 @@
+# Magicball 任务质量治理对接说明（SCE）
+
+> 适用于：Magicball AI 助手任务卡 UI 的质量治理增强与 SCE Task 质量闭环对接。
+
+## 1. 背景与目标
+
+任务由对话生成，容易出现「多事项混杂、目标不清晰、验收缺失」等问题，导致执行偏移或兜底编程。
+SCE 新增「任务质量治理」闭环能力，保证每个任务可执行、可验收、可追踪。
+
+目标：
+- 让 Magicball UI 在**同一任务卡**内完成“草案 -> 评分 -> 修正 -> Promote”的闭环
+- 通过质量门禁（Policy）强制任务可执行、可验收
+- 保留用户原始输入，避免信息丢失
+
+## 2. SCE 新增能力概览
+
+新增 CLI：
+- `sce task draft`
+- `sce task consolidate`
+- `sce task score`
+- `sce task promote`
+
+新增策略文件：
+- `.sce/config/task-quality-policy.json`
+- 支持 `--policy <path>` 覆盖
+
+默认门禁（可配置）：
+- acceptance_criteria 必须存在
+- needs_split 必须为 false
+- min_score >= 70
+
+## 3. 推荐交互流程（最短闭环）
+
+1. 用户输入 -> `sce task draft`
+2. 多轮输入合并 -> `sce task consolidate`
+3. 评分 -> `sce task score`
+4. 通过门禁 -> `sce task promote`
+5. 成功写入 `tasks.md`
+
+## 4. 字段契约（建议 Magicball 消费）
+
+核心字段：
+- `task_ref`（草案阶段可为空）
+- `title_norm`
+- `raw_request`
+- `goal`
+- `sub_goals`
+- `acceptance_criteria`
+- `needs_split`
+- `confidence`
+- `next_action`
+- `handoff`
+- `score`
+
+示例（草案阶段）：
+```json
+{
+  "task_ref": null,
+  "title_norm": "生成客户-订单-库存演示数据流程",
+  "raw_request": "帮我做一个客户订单库存的demo",
+  "goal": "生成可运行的客户-订单-库存演示流程",
+  "sub_goals": ["定义实体关系", "生成测试数据", "配置页面展示"],
+  "acceptance_criteria": [],
+  "needs_split": true,
+  "confidence": 0.68,
+  "next_action": "split",
+  "handoff": "needs_split=true, acceptance_criteria empty"
+}
+```
+
+评分示例：
+```json
+{
+  "score": 62,
+  "missing_items": ["acceptance_criteria", "split_required"]
+}
+```
+
+Promote 成功：
+```json
+{
+  "success": true,
+  "task_ref": "01.02.03",
+  "message": "promoted"
+}
+```
+
+Promote 失败：
+```json
+{
+  "success": false,
+  "message": "quality gate failed",
+  "reasons": ["acceptance_criteria missing", "needs_split=true"]
+}
+```
+
+## 5. UI 行为规范（强制）
+
+- 草案页：默认显示**评分卡 + 缺失项**
+- `needs_split=true`：必须拆分或补充，**禁止 promote**
+- `acceptance_criteria` 为空：**阻断 promote**
+- promote 失败时提示固定文案：**“质量门禁未通过”**
+
+## 6. 基于现有任务 UI 的最小改动建议
+
+当前 UI：单卡片 + 事件流 + 文件变更 + 错误信息。
+在不改整体布局的前提下，建议：
+
+1) 任务头部
+- 显示 `title_norm`
+- `raw_request` 置于标题下方（可折叠）
+- 状态徽标：Draft / Needs Split / Missing Acceptance / Ready / Failed Gate
+
+2) 评分卡（插入到事件流上方）
+- 展示 `score / missing_items / next_action`
+- 点击展开查看策略阈值与建议
+
+3) 强制阻断逻辑
+- needs_split 或 acceptance 缺失 => promote 按钮置灰
+- 展示原因与修复入口
+
+4) Promote 失败提示
+- 固定文案 “质量门禁未通过”
+- 展示失败原因列表
+
+5) 原有事件流保留，增强复制能力
+- 错误日志一键复制，便于诊断
+
+## 7. 参考命令（Magicball 封装为 API 即可）
+
+```bash
+sce task draft --spec <specPath> --input "<user text>"
+sce task consolidate --spec <specPath>
+sce task score --spec <specPath>
+sce task promote --spec <specPath>
+```
+
+## 8. 版本与发布说明
+
+该能力自 **SCE v3.6.11** 开始提供，若 Magicball 需要兼容老版本，请做版本检测与能力降级处理。
+
+---
+
+如需进一步输出 UI 页面原型或字段映射表，可直接在此文档上增补。
+## 9. 字段映射表（SCE -> Magicball UI）
+
+| SCE 字段 | UI 位置 | 展示方式 | 规则 |
+| --- | --- | --- | --- |
+| task_ref | 任务卡标题前 | 小号标签 | 无则隐藏 |
+| title_norm | 任务卡标题 | 主标题 | 必填 |
+| raw_request | 标题下方 | 灰色可折叠 | 保留原文 |
+| goal | 详情区 | 主目标段落 | 若空提示补齐 |
+| sub_goals | 详情区 | 列表 | needs_split=true 时高亮 |
+| acceptance_criteria | 详情区 | 验收列表 | 为空阻断 promote |
+| needs_split | 状态徽标 | Needs Split | true 则阻断 |
+| confidence | 评分卡 | 低/中/高 | <0.6 高亮 |
+| score | 评分卡 | 数值 + 色阶 | <阈值红色 |
+| missing_items | 评分卡 | 缺失列表 | 点击展开 |
+| next_action | 评分卡 | 下一步 | 生成操作建议 |
+| handoff | 详情区 | 灰色提示 | 展示门禁原因 |
+| errors | 事件流 | 错误块 | 一键复制 |
+| file_changes | 文件变更区 | 文件列表 | diff 快捷入口 |
+
+## 10. 前端组件建议
+
+### 10.1 TaskCard（现有卡片增强）
+- Header：`task_ref + title_norm`，`raw_request` 折叠显示。
+- StatusBadge：Draft / Needs Split / Missing Acceptance / Ready / Failed Gate。
+- QuickActions：Score / Promote / Split / Fix Acceptance。
+
+### 10.2 QualityScorePanel
+- 固定显示 `score / missing_items / next_action`。
+- 展开显示 policy 阈值与建议。
+- 禁止 promote 时显示红色提示条。
+
+### 10.3 AcceptanceEditor
+- 为空时自动提示“请补齐验收标准”。
+- 提供“自动补齐建议”按钮（由 SCE 生成）。
+
+### 10.4 PromoteGuard
+- 拦截条件：needs_split=true 或 acceptance_criteria 为空。
+- 拦截弹窗文案固定：“质量门禁未通过”。
+
+### 10.5 ErrorStream
+- 事件流右侧增加复制按钮。
+- 错误日志折叠/展开。
+
+## 11. 建议的调用顺序（前端按钮）
+
+- 点击“生成草案”：`sce task draft`
+- 点击“合并输入”：`sce task consolidate`
+- 点击“评分”：`sce task score`
+- 点击“Promote”：`sce task promote`
+
+---
+## 12. 示例 UI 结构（JSON/DSL）
+
+```json
+{
+  "type": "TaskCard",
+  "props": {
+    "taskRef": "01.02.03",
+    "titleNorm": "生成客户-订单-库存演示数据流程",
+    "rawRequest": "帮我做一个客户订单库存的demo",
+    "status": "NeedsSplit",
+    "score": 62,
+    "missingItems": ["acceptance_criteria", "split_required"],
+    "nextAction": "split"
+  },
+  "children": [
+    {
+      "type": "QualityScorePanel",
+      "props": {
+        "score": 62,
+        "minScore": 70,
+        "missingItems": ["acceptance_criteria", "split_required"],
+        "nextAction": "split"
+      }
+    },
+    {
+      "type": "TaskDetails",
+      "props": {
+        "goal": "生成可运行的客户-订单-库存演示流程",
+        "subGoals": ["定义实体关系", "生成测试数据", "配置页面展示"],
+        "acceptanceCriteria": [],
+        "handoff": "needs_split=true, acceptance_criteria empty"
+      }
+    },
+    {
+      "type": "EventStream",
+      "props": {
+        "events": [
+          {"ts": "23:59:01", "level": "error", "message": "auto-fix blocked", "copyable": true},
+          {"ts": "23:59:02", "level": "info", "message": "Task completed"}
+        ]
+      }
+    },
+    {
+      "type": "FileChanges",
+      "props": {
+        "files": [
+          {"path": "src/app.ts", "diffRef": "diff:123", "reason": "adjust task acceptance"}
+        ]
+      }
+    }
+  ]
+}
+```
+
+## 13. 前端 API 封装建议（CLI -> HTTP）
+
+建议 Magicball 在后端封装 SCE CLI，前端统一调用 HTTP。
+
+### 13.1 路由定义
+
+- `POST /api/sce/task/draft`
+- `POST /api/sce/task/consolidate`
+- `POST /api/sce/task/score`
+- `POST /api/sce/task/promote`
+
+### 13.2 请求体
+
+```json
+{
+  "specPath": "scenes/01/specs/02/spec.md",
+  "input": "帮我做一个客户订单库存的demo",
+  "policyPath": ".sce/config/task-quality-policy.json"
+}
+```
+
+### 13.3 响应体（统一包裹）
+
+```json
+{
+  "success": true,
+  "data": {
+    "task_ref": "01.02.03",
+    "title_norm": "生成客户-订单-库存演示数据流程",
+    "raw_request": "帮我做一个客户订单库存的demo",
+    "goal": "生成可运行的客户-订单-库存演示流程",
+    "sub_goals": ["定义实体关系", "生成测试数据", "配置页面展示"],
+    "acceptance_criteria": ["前端能展示客户列表"],
+    "needs_split": false,
+    "confidence": 0.81,
+    "score": 78,
+    "missing_items": [],
+    "next_action": "promote",
+    "handoff": "ready"
+  },
+  "errors": []
+}
+```
+
+### 13.4 前端调用顺序（建议）
+
+1. `draft` -> 渲染草案 + 评分卡
+2. `consolidate` -> 合并多轮输入（可选）
+3. `score` -> 质量评分
+4. `promote` -> 写入 tasks.md
+
+---

package/lib/commands/capability.js

@@ -11,7 +11,10 @@ const path = require('path');
 const chalk = require('chalk');
 const TaskClaimer = require('../task/task-claimer');
 const { runStudioSpecGovernance } = require('../studio/spec-intake-governor');
+const { DOMAIN_CHAIN_RELATIVE_PATH } = require('../spec/domain-modeling');
 const { SceStateStore } = require('../state/sce-state-store');
+const TemplateManager = require('../templates/template-manager');
+const { TemplateError } = require('../templates/template-error');
 const packageJson = require('../../package.json');
 
 const DEFAULT_ITERATION_DIR = '.sce/reports/capability-iteration';
@@ -31,6 +34,20 @@ function normalizeStringArray(value) {
   return value.map((item) => normalizeText(item)).filter(Boolean);
 }
 
+function normalizeTokenList(value) {
+  if (Array.isArray(value)) {
+    return normalizeStringArray(value).map((item) => item.toLowerCase());
+  }
+  const text = normalizeText(value);
+  if (!text) {
+    return [];
+  }
+  return text
+    .split(/[^a-zA-Z0-9._-]+/g)
+    .map((item) => item.trim().toLowerCase())
+    .filter(Boolean);
+}
+
 function normalizeBoolean(value, fallback = false) {
   if (typeof value === 'boolean') {
     return value;
@@ -71,6 +88,12 @@ function buildDefaultTemplatePath(sceneId) {
   return path.join(DEFAULT_ITERATION_DIR, `${safeScene}.template.json`);
 }
 
+function buildDefaultUsePlanPath(specId, templateId) {
+  const safeSpec = normalizeText(specId).replace(/[^\w.-]+/g, '_') || 'spec';
+  const safeTemplate = normalizeText(templateId).replace(/[^\w.-]+/g, '_') || 'template';
+  return path.join(DEFAULT_ITERATION_DIR, 'usage', `${safeSpec}.${safeTemplate}.plan.json`);
+}
+
 function buildDefaultExportDir(templateId) {
   const safeId = normalizeText(templateId).replace(/[^\w.-]+/g, '_') || 'capability';
   return path.join(DEFAULT_EXPORT_ROOT, `capability-${safeId}`);
@@ -80,6 +103,225 @@ function buildSceneIdFromCandidate(candidate) {
   return normalizeText(candidate && candidate.scene_id) || 'scene.unknown';
 }
 
+function parseTemplatePath(templatePath) {
+  const normalized = normalizeText(templatePath);
+  if (!normalized) {
+    return { sourceName: 'official', templateId: '' };
+  }
+  if (normalized.includes(':')) {
+    const [sourceName, templateId] = normalized.split(':', 2);
+    return { sourceName: normalizeText(sourceName) || 'official', templateId: normalizeText(templateId) };
+  }
+  return { sourceName: 'official', templateId: normalized };
+}
+
+function buildOntologyScopeFromChain(domainChain) {
+  const ontology = domainChain && domainChain.ontology ? domainChain.ontology : {};
+  return {
+    domains: normalizeStringArray(domainChain && domainChain.scene_id ? [domainChain.scene_id] : []),
+    entities: normalizeStringArray(ontology.entity),
+    relations: normalizeStringArray(ontology.relation),
+    business_rules: normalizeStringArray(ontology.business_rule),
+    decisions: normalizeStringArray(ontology.decision_policy)
+  };
+}
+
+function buildOntologyOverlap(specScope, templateScope) {
+  const fields = ['domains', 'entities', 'relations', 'business_rules', 'decisions'];
+  const details = {};
+  let weightedTotal = 0;
+  let weightedMatched = 0;
+  let bucketCount = 0;
+
+  fields.forEach((field) => {
+    const expected = normalizeTokenList(specScope && specScope[field]);
+    const provided = normalizeTokenList(templateScope && templateScope[field]);
+    const providedSet = new Set(provided);
+    const matched = expected.filter((item) => providedSet.has(item));
+    const expectedCount = expected.length;
+    const matchedCount = matched.length;
+    const coverage = expectedCount > 0 ? matchedCount / expectedCount : 0;
+    if (expectedCount > 0) {
+      weightedTotal += 1;
+      weightedMatched += coverage;
+      bucketCount += 1;
+    }
+    details[field] = {
+      expected,
+      provided,
+      matched,
+      expected_count: expectedCount,
+      matched_count: matchedCount,
+      coverage_ratio: Number(coverage.toFixed(3))
+    };
+  });
+
+  const score = bucketCount > 0 ? weightedMatched / weightedTotal : 0;
+  return {
+    score,
+    details
+  };
+}
+
+function buildKeywordScore(template, queryTokens) {
+  if (!queryTokens || queryTokens.length === 0) {
+    return 0;
+  }
+  const haystack = [
+    template.id,
+    template.name,
+    template.description,
+    ...(template.tags || []),
+    ...(template.applicable_scenarios || [])
+  ].map((item) => `${item || ''}`.toLowerCase());
+  const hits = queryTokens.filter((token) => haystack.some((value) => value.includes(token))).length;
+  return hits / queryTokens.length;
+}
+
+function collectExistingTaskRegistry(tasksContent) {
+  const taskPattern = /^-\s*\[[ x~-]\]\*?\s+(\d+(?:\.\d+)*)\s+(.+)$/;
+  const lines = String(tasksContent || '').split('\n');
+  const existingTitles = new Set();
+  let maxTaskId = 0;
+
+  for (const line of lines) {
+    const match = line.match(taskPattern);
+    if (!match) {
+      continue;
+    }
+
+    const rawId = match[1];
+    const rawTitle = match[2];
+    const taskId = Number.parseInt(String(rawId).split('.')[0], 10);
+
+    if (Number.isFinite(taskId)) {
+      maxTaskId = Math.max(maxTaskId, taskId);
+    }
+
+    const normalizedTitle = String(rawTitle || '')
+      .replace(/\s+\[[^\]]+\]$/, '')
+      .trim()
+      .toLowerCase();
+
+    if (normalizedTitle) {
+      existingTitles.add(normalizedTitle);
+    }
+  }
+
+  return {
+    maxTaskId,
+    existingTitles
+  };
+}
+
+function createCapabilityTaskLine(taskId, title, metadata = {}) {
+  const suffixParts = [];
+  if (metadata.templateId) {
+    suffixParts.push(`capability_ref=${metadata.templateId}`);
+  }
+  if (metadata.templateSource) {
+    suffixParts.push(`template_source=${metadata.templateSource}`);
+  }
+  const suffix = suffixParts.length > 0 ? ` [${suffixParts.join(' ')}]` : '';
+  return `- [ ] ${taskId} ${title}${suffix}`;
+}
+
+async function appendCapabilityPlanToSpecTasks(options, plan, fileSystem = fs) {
+  const projectPath = options.projectPath || process.cwd();
+  const specId = normalizeText(options.spec || options.specId);
+  if (!specId) {
+    throw new Error('spec is required to apply capability plan');
+  }
+  const tasksPath = path.join(projectPath, '.sce', 'specs', specId, 'tasks.md');
+  const tasksExists = await fileSystem.pathExists(tasksPath);
+  if (!tasksExists) {
+    throw new Error(`target spec tasks.md not found: ${tasksPath}`);
+  }
+  const currentContent = await fileSystem.readFile(tasksPath, 'utf8');
+  const registry = collectExistingTaskRegistry(currentContent);
+  const recommended = Array.isArray(plan.recommended_tasks) ? plan.recommended_tasks : [];
+  const sectionTitle = normalizeText(options.sectionTitle)
+    || `## Capability Template Tasks (${plan.template.id} - ${new Date().toISOString()})`;
+
+  const lines = [];
+  const addedTasks = [];
+  let nextTaskId = registry.maxTaskId + 1;
+  let duplicateCount = 0;
+
+  for (const entry of recommended) {
+    const title = normalizeText(entry && entry.title);
+    if (!title) {
+      continue;
+    }
+    const titleKey = title.toLowerCase();
+    if (registry.existingTitles.has(titleKey)) {
+      duplicateCount += 1;
+      continue;
+    }
+    registry.existingTitles.add(titleKey);
+
+    lines.push(createCapabilityTaskLine(nextTaskId, title, {
+      templateId: plan.template.id,
+      templateSource: plan.template.source
+    }));
+
+    addedTasks.push({
+      task_id: nextTaskId,
+      title
+    });
+
+    nextTaskId += 1;
+  }
+
+  if (addedTasks.length === 0) {
+    return {
+      tasks_path: tasksPath,
+      added_count: 0,
+      skipped_duplicates: duplicateCount,
+      skipped_reason: recommended.length === 0
+        ? 'no recommended tasks'
+        : 'all recommended tasks already exist in tasks.md',
+      added_tasks: []
+    };
+  }
+
+  const prefix = currentContent.trimEnd();
+  const chunks = [
+    prefix,
+    '',
+    sectionTitle,
+    '',
+    ...lines,
+    ''
+  ];
+
+  const nextContent = chunks.join('\n');
+  await fileSystem.writeFile(tasksPath, nextContent, 'utf8');
+
+  return {
+    tasks_path: tasksPath,
+    added_count: addedTasks.length,
+    skipped_duplicates: duplicateCount,
+    first_task_id: addedTasks[0].task_id,
+    last_task_id: addedTasks[addedTasks.length - 1].task_id,
+    added_tasks: addedTasks
+  };
+}
+
+async function loadSpecDomainChain(projectPath, specId, fileSystem) {
+  const specPath = path.join(projectPath, '.sce', 'specs', specId);
+  const domainChainPath = path.join(specPath, DOMAIN_CHAIN_RELATIVE_PATH);
+  if (!await fileSystem.pathExists(domainChainPath)) {
+    return { exists: false, path: domainChainPath, payload: null };
+  }
+  try {
+    const payload = await fileSystem.readJson(domainChainPath);
+    return { exists: true, path: domainChainPath, payload };
+  } catch (error) {
+    return { exists: true, path: domainChainPath, payload: null, error: error.message };
+  }
+}
+
 async function loadSceneIndexFromFile(projectPath, fileSystem) {
   const indexPath = path.join(projectPath, '.sce', 'spec-governance', 'scene-index.json');
   if (!await fileSystem.pathExists(indexPath)) {
@@ -537,6 +779,263 @@ async function runCapabilityRegisterCommand(options = {}, dependencies = {}) {
   return result;
 }
 
+function displayCapabilityCatalog(templates, options = {}) {
+  const total = Array.isArray(templates) ? templates.length : 0;
+  console.log(chalk.red('🔥') + ' Capability Library');
+  if (total === 0) {
+    console.log(chalk.yellow('No capability templates found.'));
+    if (options.source) {
+      console.log(chalk.gray(`Try removing filters or run ${chalk.cyan('sce templates update')}.`));
+    }
+    return;
+  }
+  templates.forEach((template) => {
+    const sourcePrefix = template.source && template.source !== 'official'
+      ? chalk.gray(`[${template.source}] `)
+      : '';
+    console.log(`${sourcePrefix}${chalk.cyan(template.id)} ${chalk.gray(`(${template.category})`)}`);
+    console.log(`  ${template.name}`);
+    console.log(`  ${chalk.gray(template.description)}`);
+    console.log();
+  });
+  console.log(chalk.gray(`Total: ${total} capability template(s)`));
+}
+
+async function listCapabilityCatalog(options = {}) {
+  const manager = new TemplateManager();
+  const templates = await manager.listTemplates({
+    category: options.category,
+    source: options.source,
+    templateType: 'capability-template',
+    compatibleWith: options.compatibleWith,
+    riskLevel: options.risk
+  });
+  if (normalizeBoolean(options.json, false)) {
+    return {
+      mode: 'capability-catalog-list',
+      templates
+    };
+  }
+  displayCapabilityCatalog(templates, options);
+  return { templates };
+}
+
+async function searchCapabilityCatalog(keyword, options = {}) {
+  const manager = new TemplateManager();
+  const templates = await manager.searchTemplates(keyword, {
+    category: options.category,
+    source: options.source,
+    templateType: 'capability-template',
+    compatibleWith: options.compatibleWith,
+    riskLevel: options.risk
+  });
+  if (normalizeBoolean(options.json, false)) {
+    return {
+      mode: 'capability-catalog-search',
+      keyword,
+      templates
+    };
+  }
+  displayCapabilityCatalog(templates, options);
+  return { templates };
+}
+
+async function showCapabilityTemplate(templatePath, options = {}) {
+  const manager = new TemplateManager();
+  const template = await manager.showTemplate(templatePath);
+  const { sourceName, templateId } = parseTemplatePath(templatePath);
+  await manager.ensureCached(sourceName);
+  const sourcePath = manager.cacheManager.getSourceCachePath(sourceName);
+  const templateDir = path.join(sourcePath, templateId);
+  const capabilityFile = path.join(templateDir, 'capability-template.json');
+  let templatePayload = null;
+  if (await fs.pathExists(capabilityFile)) {
+    try {
+      templatePayload = await fs.readJson(capabilityFile);
+    } catch (_error) {
+      templatePayload = null;
+    }
+  }
+  const result = {
+    mode: 'capability-catalog-show',
+    template,
+    template_file: await fs.pathExists(capabilityFile) ? capabilityFile : null,
+    payload: templatePayload
+  };
+  if (normalizeBoolean(options.json, false)) {
+    return result;
+  }
+  console.log(chalk.green('✅ Capability template loaded'));
+  console.log(chalk.gray(`  ID: ${template.id}`));
+  console.log(chalk.gray(`  Name: ${template.name}`));
+  if (templatePayload) {
+    console.log(chalk.gray('  Payload: capability-template.json loaded'));
+  }
+  return result;
+}
+
+async function matchCapabilityTemplates(options = {}) {
+  const projectPath = options.projectPath || process.cwd();
+  const fileSystem = options.fileSystem || fs;
+  const specId = normalizeText(options.spec || options.specId);
+  if (!specId) {
+    throw new Error('spec is required for capability match');
+  }
+  const chain = await loadSpecDomainChain(projectPath, specId, fileSystem);
+  if (!chain.exists && normalizeBoolean(options.strict, false)) {
+    throw new Error(`problem-domain-chain missing for spec ${specId}`);
+  }
+  if (chain.error && normalizeBoolean(options.strict, false)) {
+    throw new Error(`problem-domain-chain invalid: ${chain.error}`);
+  }
+  const domainChain = chain.payload || {};
+  const specScope = buildOntologyScopeFromChain(domainChain);
+  const queryTokens = normalizeTokenList(options.query)
+    .concat(normalizeTokenList(domainChain.problem && domainChain.problem.statement))
+    .concat(normalizeTokenList(domainChain.scene_id));
+  const manager = new TemplateManager();
+  const templates = await manager.listTemplates({
+    source: options.source,
+    templateType: 'capability-template',
+    compatibleWith: options.compatibleWith,
+    riskLevel: options.risk
+  });
+  const matches = templates.map((template) => {
+    const overlap = buildOntologyOverlap(specScope, template.ontology_scope || {});
+    const scenarioScore = template.applicable_scenarios && domainChain.scene_id
+      ? (template.applicable_scenarios.includes(domainChain.scene_id) ? 1 : 0)
+      : 0;
+    const keywordScore = buildKeywordScore(template, queryTokens);
+    const totalScore = (overlap.score * 0.6) + (scenarioScore * 0.2) + (keywordScore * 0.2);
+    return {
+      template_id: template.id,
+      source: template.source,
+      name: template.name,
+      description: template.description,
+      category: template.category,
+      risk_level: template.risk_level,
+      score: Math.round(totalScore * 100),
+      score_components: {
+        ontology: Number(overlap.score.toFixed(3)),
+        scenario: scenarioScore,
+        keyword: Number(keywordScore.toFixed(3))
+      },
+      overlap
+    };
+  }).sort((a, b) => b.score - a.score);
+
+  const limit = toPositiveInteger(options.limit, 10);
+  const payload = {
+    mode: 'capability-match',
+    spec_id: specId,
+    scene_id: domainChain.scene_id || null,
+    query: normalizeText(options.query) || null,
+    ontology_source: chain.exists ? chain.path : null,
+    match_count: matches.length,
+    matches: matches.slice(0, limit),
+    warnings: chain.exists ? [] : ['problem-domain-chain missing; ontology-based match unavailable']
+  };
+  if (normalizeBoolean(options.json, false)) {
+    return payload;
+  }
+  console.log(chalk.green('✅ Capability match completed'));
+  console.log(chalk.gray(`  Spec: ${specId}`));
+  console.log(chalk.gray(`  Matches: ${payload.matches.length}`));
+  return payload;
+}
+
+async function useCapabilityTemplate(options = {}) {
+  const projectPath = options.projectPath || process.cwd();
+  const fileSystem = options.fileSystem || fs;
+  const templateId = normalizeText(options.template || options.id);
+  if (!templateId) {
+    throw new Error('template is required for capability use');
+  }
+  if (normalizeBoolean(options.apply, false) && normalizeBoolean(options.write, true) === false) {
+    throw new Error('cannot use --apply with --no-write');
+  }
+  const specId = normalizeText(options.spec || options.specId) || null;
+  const manager = new TemplateManager();
+  const template = await manager.showTemplate(templateId);
+  const { sourceName, templateId: parsedTemplateId } = parseTemplatePath(templateId);
+  await manager.ensureCached(sourceName);
+  const sourcePath = manager.cacheManager.getSourceCachePath(sourceName);
+  const templateDir = path.join(sourcePath, parsedTemplateId);
+  const capabilityFile = path.join(templateDir, 'capability-template.json');
+  let templatePayload = null;
+  if (await fileSystem.pathExists(capabilityFile)) {
+    try {
+      templatePayload = await fileSystem.readJson(capabilityFile);
+    } catch (_error) {
+      templatePayload = null;
+    }
+  }
+
+  const recommendedTasks = [];
+  if (templatePayload && templatePayload.source_candidate && Array.isArray(templatePayload.source_candidate.specs)) {
+    templatePayload.source_candidate.specs.forEach((spec) => {
+      const sample = Array.isArray(spec.task_sample) ? spec.task_sample : [];
+      sample.forEach((task) => {
+        if (task && task.title) {
+          recommendedTasks.push({
+            title: task.title,
+            source_spec_id: spec.spec_id || null,
+            source_task_id: task.id || null
+          });
+        }
+      });
+    });
+  }
+  if (recommendedTasks.length === 0) {
+    recommendedTasks.push({ title: `Implement capability scope: ${template.name || parsedTemplateId}` });
+  }
+
+  const plan = {
+    mode: 'capability-use-plan',
+    generated_at: new Date().toISOString(),
+    template: {
+      id: template.id,
+      name: template.name,
+      source: template.source,
+      description: template.description,
+      ontology_scope: template.ontology_scope || {}
+    },
+    spec_id: specId,
+    recommended_tasks: recommendedTasks
+  };
+
+  const outputPath = normalizeText(options.out) || buildDefaultUsePlanPath(specId || 'spec', template.id);
+  if (normalizeBoolean(options.write, true)) {
+    await fileSystem.ensureDir(path.dirname(path.join(projectPath, outputPath)));
+    await fileSystem.writeJson(path.join(projectPath, outputPath), plan, { spaces: 2 });
+    plan.output_file = outputPath;
+  }
+
+  if (normalizeBoolean(options.apply, false)) {
+    if (!specId) {
+      throw new Error('spec is required for --apply');
+    }
+    plan.apply = await appendCapabilityPlanToSpecTasks({
+      projectPath,
+      spec: specId,
+      sectionTitle: options.sectionTitle
+    }, plan, fileSystem);
+  }
+
+  if (!normalizeBoolean(options.json, false)) {
+    console.log(chalk.green('✅ Capability use plan generated'));
+    console.log(chalk.gray(`  Template: ${template.id}`));
+    if (specId) {
+      console.log(chalk.gray(`  Spec: ${specId}`));
+    }
+    if (plan.output_file) {
+      console.log(chalk.gray(`  Output: ${plan.output_file}`));
+    }
+  }
+
+  return plan;
+}
+
 function registerCapabilityCommands(program) {
   const capabilityCmd = program
     .command('capability')
@@ -623,6 +1122,143 @@ function registerCapabilityCommands(program) {
         tags
       });
     });
+
+  const catalogCmd = capabilityCmd
+    .command('catalog')
+    .description('Browse and reuse capability templates');
+
+  catalogCmd
+    .command('list')
+    .description('List capability templates')
+    .option('--source <name>', 'Template source name')
+    .option('--category <name>', 'Template category filter')
+    .option('--compatible-with <semver>', 'SCE version compatibility')
+    .option('--risk <level>', 'Risk level filter')
+    .option('--json', 'Output JSON to stdout')
+    .action(async (options) => {
+      try {
+        const payload = await listCapabilityCatalog({
+          source: options.source,
+          category: options.category,
+          compatibleWith: options.compatibleWith,
+          risk: options.risk,
+          json: options.json
+        });
+        if (options.json) {
+          console.log(JSON.stringify(payload, null, 2));
+        }
+      } catch (error) {
+        console.log();
+        console.log(chalk.red('❌ Error:'), error.message);
+        if (error instanceof TemplateError && error.suggestions) {
+          console.log();
+          console.log(chalk.yellow('💡 Suggestions:'));
+          error.suggestions.forEach((suggestion) => console.log(`  • ${suggestion}`));
+        }
+        process.exit(1);
+      }
+    });
+
+  catalogCmd
+    .command('search <keyword>')
+    .description('Search capability templates')
+    .option('--source <name>', 'Template source name')
+    .option('--category <name>', 'Template category filter')
+    .option('--compatible-with <semver>', 'SCE version compatibility')
+    .option('--risk <level>', 'Risk level filter')
+    .option('--json', 'Output JSON to stdout')
+    .action(async (keyword, options) => {
+      try {
+        const payload = await searchCapabilityCatalog(keyword, {
+          source: options.source,
+          category: options.category,
+          compatibleWith: options.compatibleWith,
+          risk: options.risk,
+          json: options.json
+        });
+        if (options.json) {
+          console.log(JSON.stringify(payload, null, 2));
+        }
+      } catch (error) {
+        console.log();
+        console.log(chalk.red('❌ Error:'), error.message);
+        if (error instanceof TemplateError && error.suggestions) {
+          console.log();
+          console.log(chalk.yellow('💡 Suggestions:'));
+          error.suggestions.forEach((suggestion) => console.log(`  • ${suggestion}`));
+        }
+        process.exit(1);
+      }
+    });
+
+  catalogCmd
+    .command('show <template-id>')
+    .description('Show capability template details')
+    .option('--json', 'Output JSON to stdout')
+    .action(async (templateId, options) => {
+      try {
+        const payload = await showCapabilityTemplate(templateId, { json: options.json });
+        if (options.json) {
+          console.log(JSON.stringify(payload, null, 2));
+        }
+      } catch (error) {
+        console.log();
+        console.log(chalk.red('❌ Error:'), error.message);
+        if (error instanceof TemplateError && error.suggestions) {
+          console.log();
+          console.log(chalk.yellow('💡 Suggestions:'));
+          error.suggestions.forEach((suggestion) => console.log(`  • ${suggestion}`));
+        }
+        process.exit(1);
+      }
+    });
+
+  capabilityCmd
+    .command('match')
+    .description('Match capability templates to a spec using ontology scope')
+    .requiredOption('--spec <spec-id>', 'Spec identifier')
+    .option('--query <text>', 'Additional keyword query')
+    .option('--source <name>', 'Template source name')
+    .option('--compatible-with <semver>', 'SCE version compatibility')
+    .option('--risk <level>', 'Risk level filter')
+    .option('--limit <n>', 'Max match results', '10')
+    .option('--strict', 'Fail if domain-chain missing or invalid')
+    .option('--json', 'Output JSON to stdout')
+    .action(async (options) => {
+      try {
+        const payload = await matchCapabilityTemplates(options);
+        if (options.json) {
+          console.log(JSON.stringify(payload, null, 2));
+        }
+      } catch (error) {
+        console.log();
+        console.log(chalk.red('❌ Error:'), error.message);
+        process.exit(1);
+      }
+    });
+
+  capabilityCmd
+    .command('use')
+    .description('Generate a capability usage plan for a spec')
+    .requiredOption('--template <template-id>', 'Capability template identifier')
+    .option('--spec <spec-id>', 'Spec identifier')
+    .option('--out <path>', 'Output JSON path')
+    .option('--apply', 'Append recommended tasks to spec tasks.md')
+    .option('--section-title <title>', 'Custom section title for tasks.md')
+    .option('--no-write', 'Skip writing output file')
+    .option('--json', 'Output JSON to stdout')
+    .action(async (options) => {
+      try {
+        const payload = await useCapabilityTemplate(options);
+        if (options.json) {
+          console.log(JSON.stringify(payload, null, 2));
+        }
+      } catch (error) {
+        console.log();
+        console.log(chalk.red('❌ Error:'), error.message);
+        process.exit(1);
+      }
+    });
 }
 
 module.exports = {

package/package.json

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