kld-sdd 2.7.8 → 2.8.0

package/templates/skills/kld-sdd/opsx-kb-ingest/SKILL.md

@@ -79,7 +79,8 @@ curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions/$JO
 
 上传的 zip 包必须满足以下条件（否则入库会失败）：
 
-- 包含三个必需 JSON 文件：`archive-manifest.json`、`canonical-facts.json`、`conversion-report.json`
+- 当前产物包含：`archive-manifest.json`、`canonical-facts.json`、`spec-ontology.json`、`conversion-report.json`
+- 历史兼容包可不带 `canonical-facts.json`，但必须带 `spec-ontology.json`，且 `compatibility_mode=LEGACY_MATERIALIZED`。重复锚点、非法 UUID、身份冲突、依赖成环、归档版本不一致由上传自动消解；无结构化事实时才是 `pending`。不要让用户处理这些历史诊断。
 - `canonical-facts.json` 支持 `kld-sdd-canonical-facts/v1` 与 **`v2`**（v2 可选实体级 `external_refs`）
 - 所有文件需通过 SHA-256 校验（manifest 中记录每个文件的 `content_hash`）
 - 允许的文件类型：`.md`、`.json`、`.jsonl`、`.yaml`、`.yml`
@@ -213,7 +214,7 @@ node skywalk-sdd/kb-sync-identity.cjs \
 |------|-----------|---------|
 | 输入 | 原始变更目录 | 已打包 zip |
 | 语义管线 | 自动执行（semantic-scan → reconcile → check） | 无需（zip 已含元数据） |
-| 元数据生成 | 自动生成（archive-manifest + canonical-facts + conversion-report） | 无需（zip 已含） |
+| 元数据生成 | 自动生成（manifest + canonical v2 + Spec ontology v1 + report） | 无需（zip 已含） |
 | 适用场景 | 任意 SDD 阶段入库 | 已有 zip 补传 / 归档后上传 |
 
 > 文件夹上传最终也会打包成 zip 走同一上传接口，KB 后端解析逻辑不变。

package/templates/skills/kld-sdd/opsx-kb-ingest/reference.md

@@ -233,8 +233,8 @@ node skywalk-sdd/kb-upload.cjs --package=<zip-path> [--space-id=<id>] [--kb-id=<
 | `--package=<zip>` | 与 `--folder` 二选一 | 已打包的 zip 路径 |
 | `--minimum-level` | 否 | 上传最低等级：`propose-spec`（默认）/ `design` / `task` / `full` |
 | `--validate-only` | 否 | 仅校验不上传 |
-| `--space-id=<id>` | 否 | 目标 Space ID（从 kb-state.json targets[0] 读取） |
-| `--kb-id=<id>` | 否 | 目标 KB ID（从 kb-state.json targets[0] 读取） |
+| `--space-id=<id>` | 否 | 目标 Space ID；单目标可读取配置，多目标时与 --kb-id 一起显式提供 |
+| `--kb-id=<id>` | 否 | 目标 KB ID；单目标可读取配置，多目标时与 --space-id 一起显式提供 |
 
 ### project_id 解析优先级
 

package/templates/skills/kld-sdd/opsx-ontology-ingest/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: opsx-ontology-ingest
+description: >-
+  Materializes current or historical SDD artifacts into the Spec ontology protocol,
+  reviews compatibility candidates, packages both canonical v2 and Spec ontology v1,
+  uploads them to the configured knowledge base, and verifies retrieval.
+argument-hint: "[change-key or archive folder]"
+license: MIT
+compatibility: Requires the kld-sdd ontology runtime; upload requires a configured Engineering KB.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+---
+
+> **执行方式**：先读 [交互与执行契约](../opsx-propose/interaction-policy.md)；同一会话已读则复用。
+
+# Spec 本体入库
+
+这是「产物兼容 → 本体物化 → 入库 → 召回验证」的统一入口。用户不需要手工补 UUID，也不需要判断历史产物版本。
+
+## 始终遵守
+
+- 不改写历史 Markdown。缺少、非法或互相冲突的身份由上传写进 `ontology/legacy-mapping.json`，并生成稳定 UUID。
+- 重复锚点、非法 UUID、身份冲突、任务依赖成环、归档版本对不上，都由上传自动消解并继续发布。不要停下来请用户处理，也不要改 Markdown 去“修”这些历史诊断。
+- `opsx-check` 仍会报告这些问题。入库和召回不依赖 Check 通过。
+- 正式发布仍校验证据、哈希、版本和租户边界。正文没有结构化事实时只入证据，不发布本体事实。
+- 当前 `canonical-facts/v2` 与 `spec-ontology/v1` 同包产出，支持新旧知识库过渡。
+
+## 执行流程
+
+1. 确定 Spec 仓根目录和 change。
+2. 执行兼容物化：
+
+```bash
+node skywalk-sdd/ontology/cli.cjs materialize-ontology --project=. --change=<change-key>
+```
+
+3. 读取结果中的 `compatibility_mode`：
+   - `NATIVE`：原生本体产物。
+   - `ADAPTED_V2`：当前 SDD v2 产物已无损适配。
+   - `LEGACY_MATERIALIZED`：历史产物已生成旁路身份，需审核候选合并。
+   - `EVIDENCE_ONLY`：结构不足，只入证据，不发布本体事实。
+4. 执行本地校验：
+
+```bash
+node skywalk-sdd/ontology/cli.cjs validate-spec-ontology \
+  --file=openspec/changes/<change-key>/ontology/spec-ontology.json
+```
+
+5. 上传本身会自动物化并确认。重复锚点按来源拆开，非法或冲突的 UUID 改成稳定派生身份，依赖成环和归档版本不一致只记入转换说明。不要向用户复述这些诊断，不要要求用户选择合并或补 UUID。完成后直接入库并用 spec-generation 召回验证。
+6. 仅当用户明确要求先审阅，或正文没有任何结构化事实时，才保留 candidate。此时再运行：
+
+```bash
+node skywalk-sdd/ontology/cli.cjs approve-spec-ontology \
+  --file=openspec/changes/<change-key>/ontology/spec-ontology.json
+```
+
+   用户没有要求审阅时不要执行这一步。上传已经自动确认，不要因为重复锚点或身份改写再停下来。
+7. 通过 `opsx-kb-ingest` 打包上传。正文变化时重新物化并自动确认。已确认本体与当前 Markdown 不一致时不沿用旧确认。
+8. 通过 `context-client.cjs --mode=spec-generation` 执行一次召回验证。向用户只报告是否入库、是否召回到 current 事实。自动改写过的身份、拆开的重复锚点、忽略的成环和归档差异写在命令输出里，不单独向用户确认。
+
+## 完成后的简报
+
+只向用户说明入库和召回结果。下面这些由工具自动处理，不列入需要用户决定的事项：
+
+```text
+兼容模式：LEGACY_MATERIALIZED
+已发布事实：12
+自动改写身份：3
+重复锚点已拆分：1
+归档/成环已忽略：2
+仅证据：0
+```
+
+若 KB 不可用，保留已物化产物并标记 `remoteContextVerified=false`；本地编写可继续，入库与发布状态明确为未完成。

package/templates/skills/kld-sdd/opsx-ontology-query/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: opsx-ontology-query
 description: >-
-  Queries the Engineering KB ontology via API Key (context search, match-requirement,
+  Queries the Engineering KB ontology via API Key (Spec-generation context, search, continuity,
   entity/impact/ontology-view). Prompts for API key and multi-selects spaces/KBs into
   local skill state. Use when looking up Spec/design facts, Spec reuse, impact, or
   citation-backed answers from the ontology KB.
@@ -64,7 +64,8 @@ Task Progress:
 |------|------|
 | 开放问题 / 相似事实 | `POST …/context/search` |
 | Continuity / 按外部需求号定位身份 | `POST …/entities/resolve` |
-| Spec 复用 / 转换 | `POST …/context/match-requirement` |
+| Spec 生成上下文 | `POST …/context/spec-generation` |
+| 旧服务端兼容 | `POST …/context/match-requirement` |
 | 对象详情 | `GET …/entities/{id}/current-version` |
 | 一跳结构 | `GET …/entities/{id}/ontology-view` |
 | 多跳影响 | `GET …/entities/{id}/impact` |
@@ -76,7 +77,7 @@ Task Progress:
 **机器意图（SDD 流程 Agent）**：
 
 - Continuity（只要身份）→ 优先 `entities/resolve`
-- Spec 复用 → `context/match-requirement`，带 external 与/或 `entityId`
+- Spec 复用 → `context/spec-generation`，带 external 与/或 `entityId`；只有端点 404 时退回 `match-requirement`
 - **KB 可用时禁止**扫描消费方本地 `archive/` 目录当跨迭代继承源；entity-id 必须来自 KB resolve by canonicalKey。KB degraded 时 archive 仅作背景参考，不自动继承身份；保留已有草稿基线，发布前再在线核对
 
 命中时关注：`resolution=LINK_EXISTING` 且 `inheritanceAllowed=true`（可继承 n）；`removedBindingCount`（已失效绑定 m）；`matchType=HISTORICAL_ONLY` 表示仅有失效绑定，不可继承。
@@ -91,7 +92,7 @@ scenario:    ^[A-Z0-9_-]+:SCN-[a-z0-9]+(-[a-z0-9]+)*-[0-9]{3}$
 
 归一化：trim；requirement/feature 段大写；SCN slug 小写。编号五律摘要：requirement/feature 由外部需求系统铸号（格式不限 REQ-/FEAT- 前缀，白名单 A-Z 0-9 - _）；SCN 由 kld-sdd/opsx-spec 铸号；编号≠身份；归属权威在需求系统；历史绑定 append-only。
 
-> 按功能号圈能力（FEAT query）、match-requirement / resolve 完整 curl 示例与响应字段解读 → [reference.md](reference.md)。
+> 按功能号圈能力（FEAT query）、spec-generation / match-requirement / resolve 完整示例与响应字段解读 → [reference.md](reference.md)。
 
 ## 输出模板
 

package/templates/skills/kld-sdd/opsx-ontology-query/reference.md

@@ -154,7 +154,20 @@ curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/entities/resol
 
 > 此查询只作范围参考，不改变 Continuity 判定优先级。
 
-## context/match-requirement
+## context/spec-generation（推荐）
+
+`POST {base}/context/spec-generation`
+
+返回面向 Spec 生成的结构化上下文：`matchedCapabilities` / `matchedScenarios` / `businessObjects` / `rules` / `specPatterns` / `answeredFacts` / `clarificationQuestions` / `evidence`。
+
+```bash
+node skywalk-sdd/context-client.cjs --mode=spec-generation \
+  --query="用户登录与会话" --target-stage=spec
+```
+
+若服务端返回 404，客户端自动调用旧 `match-requirement`，并返回 `compatibilityMode=LEGACY_V2`。鉴权失败、超时和服务错误不会伪装成兼容回退。
+
+## context/match-requirement（旧协议）
 
 `POST {base}/context/match-requirement`
 

package/templates/skills/kld-sdd/opsx-propose/SKILL.md

@@ -268,7 +268,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --mode=resolve \
 
 **以 `openspec-templates/proposal.md` 的结构为骨架**，填充内容到 `outputPath`。
 
-**【质量红线】生成文档必须严格遵循模板结构。**
+**【质量红线】保留模板中解析必需的字段、身份、锚点和关系，按实际变更保留相关章节，不机械复制无关空表和说明。**
 
 ### 10. 质量红线自检
 

package/templates/skills/kld-sdd/opsx-propose/interaction-policy.md

@@ -8,6 +8,7 @@
 - 用户已要求“完成这个需求”“实现并验证”或连续处理时，在授权范围内加载下一阶段技能并继续，Simple / Full 均适用，不反复索要阶段口令。要求“完善文档”不授权实现代码。
 - 连续推进仍按依赖完成文档、check、apply 和测试；check 未通过不得冒充通过。归档、入库、合并、推送、部署按用户授权分别判断，不能从“实现”推导为已授权发布。
 - 只在业务目标或验收口径存在实质歧义、多个身份无法判定、真实冲突或新增外部副作用需要授权时询问。先读取用户提供的材料与现有代码，集中提出缺失事实，不把 mode、UUID、内部枚举当作业务问题。
+- 同一轮发现多个冲突或待决策项时，合并成一份清单一次问完（含各自选项与建议），不逐个打断用户。
 - 自动选择文档形态和测试策略并简短说明理由；沿用已有变更的设置，不因这次默认规则重排存量目录。
 - 只展示业务差异、必要决策、验证结果和剩余问题。遥测、身份分配、结构化 JSON 由工具和 Agent 维护，不让用户手填，不把自动推断伪记为用户确认。
 
@@ -26,3 +27,11 @@
 - 当前 Markdown 身份块和归档格式继续兼容；本规则不声称已经把业务身份迁移到 sidecar。新 ID 由工具生成，旧 ID 不批量改写。
 - 任务按可验证的行为或交付单元组织，保留依赖和验收，避免按每五分钟、每个字段或每次命令机械拆分。规模以实际风险和依赖判断，不能用估计的工时冒充质量证明。
 - 默认聚焦当前 Capability；确有跨能力依赖时允许读取相关契约，注明依赖来源，避免全量加载或混写其他能力。多仓各自保留 Git 提交事实，共享 Spec 的关联由工具处理。
+
+## 文档只保留真实决策与契约
+
+- 模板用于提示需要考虑的内容，必须保留解析字段、身份、锚点和引用关系；不为填满模板复制教程、空表、重复背景或不适用章节。简单变更直接表达目的、行为、验收、设计决定和可验证任务。
+- 已有全局契约用引用复用；Spec 写行为，Design 只补实现决策，Task 只写交付单元、依赖和验收，不在四份文档重复同一解释。
+- ⛔ 修改已有 SDD 文档禁止整文件覆写（Write 全文重写会冲掉前次修复）；必须用 Edit 定向修改或章节末尾追加。仅用户明确要求重构文档结构时例外。
+- 参数边界可用表驱动验收和测试；只有行为、依赖或交付确实不同才拆任务。若项目明确采用 TDD，保留真实 RED→GREEN 证据与顺序，不机械按每个字段或输入值生成一整套任务。
+- Check 的结构合法性由程序负责，模型聚焦业务覆盖与矛盾；结果按实际检查项输出，由 check-record 计算记账字段。

package/templates/skills/kld-sdd/opsx-spec/SKILL.md

@@ -115,10 +115,11 @@ openspec list
 **【默认尝试】工程 Spec 知识库上下文（场景身份主战场）**：
 
 1. **先加载依赖技能**：确认 `${AGENT_SKILL_DIR}/opsx-ontology-query/SKILL.md` 存在并 Read；使用已有 API Key / target（`kb-state.json`）；未配置或未安装仅跳过远程查询，继续正文编写。
-2. 读取 proposal Continuity。对**当前 Capability** 各调一次（「全部」= 循环 N 次，不是一次大查询）——优先走 **`opsx-ontology-query`** 的 `match-requirement`；薄封装仅作参数拼装：
+2. 读取 proposal Continuity。对**当前 Capability** 各调一次（「全部」= 循环 N 次，不是一次大查询）——优先走 **`opsx-ontology-query`** 的 `spec-generation`；服务端暂未支持时薄封装才退回 `match-requirement` 并标记 `LEGACY_V2`：
 
 ```bash
 node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" \
+  --mode=spec-generation \
   --query="<当前 Capability 的自然语言需求>" \
   --target-stage=spec \
   --entity-id="<该 CAP 的 entity_id>" \
@@ -141,7 +142,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" \
   3. removed 号是墓碑：永不复用、永不重排；序号达 999 → 硬错误，回需求系统拆分需求，不扩位。
   4. 写完立即用 `cli.cjs external-key --validate … --type scenario` 校验；需求编号前缀必须 ∈ proposal `requirement-refs`。
 - 场景级「同 SCN key + 同锚点、不同 entity_id」当场问 A/B/C；未决不得进入下一 CAP / design。决议追加到 `ontology/continuity-resolution.json` 的 `scenarios[]`；决议中的 `externalKey` 必须是归一化形态。
-- 优先消费 `reuseBundles[].statements`；`designElements` 只作理解上下文，不能写成 Spec 的 How。
+- 优先消费 `matchedCapabilities` / `matchedScenarios` / `businessObjects` / `rules` / `specPatterns`；兼容返回时再读 `reuseBundles[].statements`。`designElements` 只作理解上下文，不能写成 Spec 的 How。
 - 所有知识库内容均为 advisory；与用户确认 / proposal 冲突时以当前确认与 proposal 为准。
 - **禁止**铸/改外部需求/功能编号；**禁止**自动重排/回收 SCN。
 
@@ -181,6 +182,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" \
 **输出路径**：`changes/<name>/specs/<capability>/spec.md`
 
 **【质量红线】需求项格式要求**：
+- 业务对象使用 `#### 业务对象：[OBJ-*]`，只描述影响规则或场景的稳定业务概念；没有明确对象时不强行创建
 - 需求项使用 `####`（4个#）
 - 场景使用 `#####`（5个#）
 
@@ -209,7 +211,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" \
 ## 本体语义生成契约
 
 - 写入 `capability-id: CAP-<CAPABILITY>`，且必须引用 proposal 中真实存在的 CAP ID。
-- 新需求、场景和约束分别使用 `STMT-*`、`AC-*`、`CON-*`；分配规则是同前缀同 Capability 当前最大序号 + 1。
+- 业务对象、需求、场景和约束分别使用 `OBJ-*`、`STMT-*`、`AC-*`、`CON-*`；分配规则是同前缀同 Capability 当前最大序号 + 1。
 - 修改已有实体必须复用原 ID；删除实体只写 removal 语义，不得把编号分配给新实体。
 - `added` 必须调用 `semantic-identity --delta-state=added` 生成新的实体 UUID 和版本 UUID；禁止通过复制另一需求的 UUID 创建新实体。
 - `modified/removed` 保留已明确的 `entity-id` 和真实 `predecessor-version`；在线解析当前版本后由工具分配版本。离线可以继续正文，未确认的远程身份登记为待核对，发布前解决；不能从相似归档复制 UUID 或把最新版本编号直接当作实际编辑基线。

package/templates/skills/kld-sdd/opsx-task/SKILL.md

@@ -147,7 +147,7 @@ Simple 模式或单文件能力域下，**不要拆成多个同文件任务**。
 
 ### 6. 【交互引导】确认任务拆解策略
 
-向用户确认拆解维度、任务粒度、预计 DAG 层级。**根据 test-strategy 调整 DAG 生成规则**，规则表（tdd / impl-first / none 对应的 DAG 生成规则）见 `./reference.md`「§6 DAG 生成规则表」。
+依据已授权需求和真实依赖选择拆解维度、任务粒度与 DAG；只就业务歧义询问。**根据 test-strategy 调整 DAG 生成规则**，规则表（tdd / impl-first / none 对应的 DAG 生成规则）见 `./reference.md`「§6 DAG 生成规则表」。
 
 **当 test-strategy=tdd 时，必须向用户说明：**
 > "🧪 TDD 模式将采用红绿重构循环：
@@ -171,7 +171,7 @@ Simple 模式或单文件能力域下，**不要拆成多个同文件任务**。
 **当 test-strategy=tdd 时，任务生成规则：**
 
 ⛔ 核心规则（inline）：
-1. 每个场景拆为一个行为点，每个行为点生成一对 RED+GREEN 任务
+1. 同一行为的输入边界合并为表驱动场景；按独立行为生成 RED+GREEN 任务，保留所有验收变体
 2. RED 验收标准必须包含"测试运行失败且失败原因正确"
 3. GREEN 验收标准必须包含"写最少代码让对应 RED 测试通过"，禁止捆绑
 4. GREEN 不得包含未测试的 Controller/Filter/Config

package/index.js

@@ -1,13 +0,0 @@
-/**
- * SDD OpenSpec Init - 项目初始化工具
- * 
- * 提供程序化 API 接口
- */
-
-const { main, detectTools, applyTeamConfig } = require('./lib/init');
-
-module.exports = {
-  main,
-  detectTools,
-  applyTeamConfig
-};