kld-sdd 2.5.1 → 2.6.0

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

@@ -107,6 +107,22 @@ openspec list
 
 > 上下文类型（需求文档 / 代码文件 / API 文档）与用途见 `./reference.md`「§3 上下文类型与用途」。
 
+**【默认尝试】工程 Spec 知识库上下文**：
+
+从用户输入、proposal.md 中当前 Capability 的名称、业务目标、边界和约束组成一段自然语言查询。不要要求用户提供 `entity_id`。执行：
+
+```bash
+node skywalk-sdd/context-client.cjs --query="<当前 Capability 的自然语言需求>" --target-stage=spec
+```
+
+- 配置项：`ENGINEERING_KB_API`、`ENGINEERING_KB_SPACE_ID`、可选 `ENGINEERING_KB_TOKEN`。
+- 若返回 `available=false` 或 `degraded=true`，记录降级原因并继续 Spec 流程，不得阻塞。
+- 优先消费 `reuseBundles[].statements` 中的历史 STMT、AC、Constraint；`designElements` 只能作为理解上下文，不能写成 Spec 的 How。
+- `answeredQuestions` 表示历史事实已经覆盖的内容，不要对用户重复提问。
+- 只向用户询问 `clarificationQuestions` 中仍与当前 Capability 有关的问题。
+- `reuseMode=REFERENCE` 只能参考复用，不得复制历史 UUID；只有 `reuseMode=INHERIT` 才允许按本体语义生成契约复用历史身份。
+- 所有知识库内容均为 advisory；若与用户输入、proposal.md 或用户确认冲突，以当前用户确认和 proposal.md 为准。
+
 **【可选】业务知识库检索**：
 术语含义不清且可能影响 spec 准确性时，可调用 **opsx-knowledge** skill。
 知识库结果仅供参考，spec 契约以用户确认和 proposal 为准；失败时不阻塞。
@@ -131,6 +147,9 @@ openspec list
 
 第 3 层：当前 Capability 上下文
   → 已有的 spec.md（若为增量修改）
+
+第 4 层：工程知识库 Spec Context Package
+  → reuseBundles / answeredQuestions / clarificationQuestions
 ```
 
 ### 6. 创建 spec.md
@@ -176,6 +195,21 @@ openspec list
 
 ---
 
+## 本体语义生成契约
+
+- 写入 `capability-id: CAP-<CAPABILITY>`，且必须引用 proposal 中真实存在的 CAP ID。
+- 新需求、场景和约束分别使用 `STMT-*`、`AC-*`、`CON-*`；分配规则是同前缀同 Capability 当前最大序号 + 1。
+- 修改已有实体必须复用原 ID；删除实体只写 removal 语义，不得把编号分配给新实体。
+- `added` 必须调用 `semantic-identity --delta-state=added` 生成新的实体 UUID 和版本 UUID；禁止通过复制另一需求的 UUID 创建新实体。
+- `modified/removed` 必须从 Archive 读取历史 `entity-id` 和直接前序 `version-id`，调用 `semantic-identity --delta-state=<modified|removed> --entity-id=<UUID> --predecessor-version=<UUID>`；实体 UUID 复用，版本 UUID 新建。
+- AC 必须嵌套在所属 STMT 下；CON 必须通过 `**constrains**` 显式引用 STMT。
+- 对 `reuseMode=REFERENCE` 的历史候选必须创建新的实体身份；禁止因为内容相似而复用历史 `entity-id`。
+- 对 `reuseMode=INHERIT` 的历史事实，必须使用返回的实体与版本来源完成 unchanged/modified 身份参数校验。
+- unchanged 内容只写人工锚点、历史实体 UUID、历史版本 UUID 和来源引用，不复制历史原文；调用 `semantic-identity --delta-state=unchanged --entity-id=<UUID> --version-id=<UUID>` 校验复用参数，引用断链时保持 unresolved 并交由 check 阻断。
+- 生成结束后必须运行 `node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<name>`，根据诊断修复缺号、重号和悬空引用。
+- reconcile 必须在 change 目录生成 `openspec/changes/<name>/artifacts/spec.ontology.json` 或 `openspec/changes/<name>/artifacts/specs/<capability>/spec.ontology.json`；该 JSON 是 draft 工作事实，不得等待 check/archive 才生成。
+- 阶段 `stage_end` 会在无 Hook 环境下幂等执行同步兜底，并返回 `semantic_state.artifact_json_paths`。
+
 ## Guardrails
 
 > 完整 ⛔ 强制项勾选清单见 `./checklist.md`「Guardrails ⛔ 强制项」。核心红线：

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

@@ -17,6 +17,7 @@ description: opsx-spec 的阶段强制检查点与自检清单。仅在执行 sp
 - [ ] 即使用户提供代码作为上下文，只用于分析现有实现，不执行任何代码操作
 - [ ] 代码实现将在 `/opsx-apply` 阶段进行
 - [ ] ⛔ 完成本阶段后绝对禁止自动继续执行 design/task 等后续阶段
+- [ ] 工程知识库未配置、超时或降级时继续 Spec 主流程，不阻塞本地创作
 
 ---
 
@@ -30,6 +31,9 @@ description: opsx-spec 的阶段强制检查点与自检清单。仅在执行 sp
 - [ ] 技术契约章节完整（数据模型、接口契约）
 - [ ] 文档末尾包含质量红线检查清单
 - [ ] 100% 覆盖 proposal.md 中该 Capability 的描述
+- [ ] 已消费工程知识库 `answeredQuestions`，没有重复询问历史事实已经回答的问题
+- [ ] 仅将 `reuseMode=INHERIT` 的事实作为身份继承；`REFERENCE` 候选使用新实体身份
+- [ ] 已处理与当前 Capability 有关的 `clarificationQuestions`
 
 **如有任意一项未满足，重新生成对应章节，直至全部通过。** 自检完成后必须输出结构化自检报告（模板见 `./reference.md`「§7 质量自检报告模板」），未通过项自动修复后重新输出。
 
@@ -42,5 +46,6 @@ description: opsx-spec 的阶段强制检查点与自检清单。仅在执行 sp
 - [ ] **需求项格式必须正确**：`####` 需求项、`#####` 场景
 - [ ] 每个需求项必须有清晰的验收标准
 - [ ] 技术契约必须可执行、无歧义
+- [ ] 工程知识库结果只作为 advisory 上下文，不覆盖用户输入或 proposal.md
 - [ ] ⛔ **阶段边界**：禁止执行任何代码创建/修改操作
 - [ ] ⛔ **单阶段原则**：完成 spec.md 后必须立即停止；仅提示用户下一步可运行 `/opsx-design`，绝对禁止自动执行 design/task 等后续阶段。每个阶段必须由用户主动触发。

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

@@ -193,6 +193,17 @@ Simple 模式或单文件能力域下，**不要拆成多个同文件任务**。
 
 ---
 
+## 本体语义生成契约
+
+- 写入与当前 spec/design 一致的 `capability-id`。
+- 每个任务必须使用 `TASK-<CAPABILITY>-NNN`；新增前按当前最大序号 + 1 分配，已有任务不得改 ID。
+- 每个 TASK 必须同时写 `entity-id`、`version-id` 和 `delta-state`；新增任务调用 `semantic-identity --delta-state=added`，不得复用其他任务 UUID。
+- 每个 TASK 必须写 `**implements**: DES-*` 或 `**covers**: STMT-*`，不得生成无上游来源任务。
+- 任务依赖必须写 `**dependsOn**: TASK-*`；无依赖显式写“无”，所有依赖必须构成 DAG。
+- 生成结束后必须运行 `node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<name>`。
+- reconcile 必须立即生成 `openspec/changes/<name>/artifacts/.../tasks.ontology.json`，包含 TASK、implements/covers/dependsOn 及原文 source；不得推迟到 check/archive。
+- 阶段 `stage_end` 会在无 Hook 环境下幂等执行同步兜底。
+
 ## Guardrails
 
 > 完整 ⛔ 强制项勾选清单见 `./checklist.md`「Guardrails ⛔ 强制项」。核心红线：