kld-sdd 2.5.1 → 2.5.2

package/templates/openspec/spec.md

@@ -1,3 +1,7 @@
+---
+capability-id: "CAP-<CAPABILITY>" # 必须与 proposal.md 中的 Capability ID 一致
+---
+
 # spec.md - 能力规格定义
 
 > **定位**：单个能力（capability）的技术规格定义，用于 `specs/<capability>/spec.md`
@@ -14,29 +18,49 @@
 
 ### 新增需求
 
-<!-- 新增的需求，使用「必须」强制要求 -->
+<!-- 新增实体按当前最大序号 + 1 分配 ID；已有实体修改时复用原 ID -->
 
-#### 需求项：<!-- 需求名称 -->
+#### 需求项：[STMT-<CAPABILITY>-NNN] <!-- 需求名称 -->
+- **entity-id**: <UUID>
+- **version-id**: <UUID>
+- **delta-state**: added
+- **predecessor-version**: 无
 
 <!-- 需求描述，使用「必须」而非「应该」「可以」 -->
 系统必须 ...
 
-##### 场景：<!-- 场景名称 -->
+##### 场景：[AC-<CAPABILITY>-NNN] <!-- 场景名称 -->
+- **entity-id**: <UUID>
+- **version-id**: <UUID>
+- **delta-state**: added
+- **predecessor-version**: 无
 - **当** <!-- 触发条件 -->
 - **预期** <!-- 预期结果 -->
 
-##### 场景：<!-- 另一个场景 -->
+##### 场景：[AC-<CAPABILITY>-NNN] <!-- 另一个场景 -->
+- **entity-id**: <UUID>
+- **version-id**: <UUID>
+- **delta-state**: added
+- **predecessor-version**: 无
 - **当** <!-- 触发条件 -->
 - **预期** <!-- 预期结果 -->
 
 ### 修改需求
 
-<!-- 仅当修改已有需求时使用，必须复制完整原需求内容再修改 -->
+<!-- 修改已有需求时复用原 STMT/AC/CON ID，只展开实际变化内容 -->
 
-#### 需求项：<!-- 已有需求名称 -->
+#### 需求项：[STMT-<CAPABILITY>-NNN] <!-- 已有需求名称，复用原 ID -->
+- **entity-id**: <复用历史 UUID>
+- **version-id**: <新 UUID>
+- **delta-state**: modified
+- **predecessor-version**: <直接前序 version UUID>
 系统必须 ...
 
-##### 场景：<!-- 场景名称 -->
+##### 场景：[AC-<CAPABILITY>-NNN] <!-- 场景名称，复用或新增 ID -->
+- **entity-id**: <复用历史 UUID；新增场景则生成新 UUID>
+- **version-id**: <新 UUID>
+- **delta-state**: <modified|added>
+- **predecessor-version**: <modified 时填写；added 为无>
 - **当** <!-- 触发条件 -->
 - **预期** <!-- 预期结果 -->
 
@@ -44,10 +68,40 @@
 
 <!-- 仅当移除已有需求时使用 -->
 
-#### 需求项：<!-- 被移除的需求名称 -->
+#### 需求项：[STMT-<CAPABILITY>-NNN] <!-- 被移除的需求名称，复用原 ID -->
+- **entity-id**: <复用历史 UUID>
+- **version-id**: <新墓碑版本 UUID>
+- **delta-state**: removed
+- **predecessor-version**: <直接前序 version UUID>
 **移除原因**：<!-- 移除原因 -->
 **迁移方案**：<!-- 迁移方案 -->
 
+### 约束
+
+#### 约束：[CON-<CAPABILITY>-NNN] <!-- 约束名称 -->
+- **entity-id**: <UUID>
+- **version-id**: <UUID>
+- **delta-state**: added
+- **predecessor-version**: 无
+- **constrains**: STMT-<CAPABILITY>-NNN
+- **约束内容**: <!-- 可量化、可验证的约束 -->
+
+### 继承引用
+
+<!-- unchanged 内容只记录既有实体/版本引用，不复制历史正文；断链时 opsx-check 必须阻断 -->
+- **anchor**: `STMT-<CAPABILITY>-NNN`
+- **entity-id**: `<复用历史 UUID>`
+- **version-id**: `<复用历史 version UUID>`
+- **delta-state**: `unchanged`
+- **source**: `<archive>/<artifact>#<anchor>`
+- **source-version-hash**: `<前序实体版本内容 SHA-256>`
+
+### 继承关系
+
+<!-- 历史关系不会自动全部继承；只有本节显式列出的 confirmed 关系进入 Effective Graph -->
+- **relation**: `STMT-<CAPABILITY>-NNN acceptedBy AC-<CAPABILITY>-NNN`
+- **source**: `<archive>/<artifact>#<from>-<relation>-<to>`
+
 ---
 
 ## 2. 技术契约（SDD 扩展）

package/templates/openspec/tasks.md

@@ -1,3 +1,7 @@
+---
+capability-id: "CAP-<CAPABILITY>" # 必须与对应 spec/design 一致
+---
+
 # 实施任务拆解 - [Capability 名称]
 
 > **定位**：单一 Capability 的 AI 编码引擎执行单元
@@ -116,10 +120,16 @@
 
 ---
 
-### [TASK-XXX-01] 任务名称
+### [TASK-<CAPABILITY>-NNN] 任务名称
 
+- **entity-id**: <UUID>
+- **version-id**: <UUID>
+- **delta-state**: added
+- **predecessor-version**: 无
 - **类型**: 数据层 / 接口层 / UI层 / 测试
-- **依赖**: 无
+- **implements**: DES-<CAPABILITY>-NNN
+- **covers**: STMT-<CAPABILITY>-NNN
+- **dependsOn**: 无
 - **状态**: [ ] 未完成
 
 #### 任务描述
@@ -146,10 +156,16 @@
 
 ---
 
-### [TASK-XXX-02] 任务名称
+### [TASK-<CAPABILITY>-NNN] 任务名称
 
+- **entity-id**: <UUID>
+- **version-id**: <UUID>
+- **delta-state**: added
+- **predecessor-version**: 无
 - **类型**: 数据层 / 接口层 / UI层 / 测试
-- **依赖**: 无
+- **implements**: DES-<CAPABILITY>-NNN
+- **covers**: STMT-<CAPABILITY>-NNN
+- **dependsOn**: 无
 - **状态**: [ ] 未完成
 
 #### 任务描述
@@ -173,10 +189,16 @@
 
 ---
 
-### [TASK-XXX-03] 任务名称
+### [TASK-<CAPABILITY>-NNN] 任务名称
 
+- **entity-id**: <UUID>
+- **version-id**: <UUID>
+- **delta-state**: added
+- **predecessor-version**: 无
 - **类型**: 数据层 / 接口层 / UI层 / 测试
-- **依赖**: TASK-XXX-01, TASK-XXX-02
+- **implements**: DES-<CAPABILITY>-NNN
+- **covers**: STMT-<CAPABILITY>-NNN
+- **dependsOn**: TASK-<CAPABILITY>-NNN, TASK-<CAPABILITY>-NNN
 - **状态**: [ ] 未完成
 
 #### 任务描述

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

@@ -155,6 +155,15 @@ node skywalk-sdd/log.cjs record --type=baseline_record --command=archive --proje
 
 ---
 
+## 本体语义归档门禁
+
+- 归档前必须运行 `node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<变更名称>`，不能只信任文件观察事件。
+- 随后必须运行 `node skywalk-sdd/log.cjs semantic-check --project=. --change=<变更名称>`；有阻断诊断时禁止移动活动 Change。
+- `archive-docs` 成功后必须在归档目录生成 `archive-ontology.json`，并将 `review_status` 标记为 `confirmed`。
+- Archive 快照必须固化人工锚点、逻辑实体 UUID、版本 UUID、前序版本 UUID、delta-state 和内容哈希；任一 UUID 冲突或谱系断裂都不得 confirmed。
+- 归档目录已经复制但语义快照失败时，不得删除活动 Change，不得标记 confirmed。
+- unchanged 正文保留在前序 Archive；当前归档只固化差量事实、继承引用和来源锚点。
+
 ## Guardrails
 
 - 归档操作执行前必须让用户确认归档原因。

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

@@ -200,6 +200,22 @@ node skywalk-sdd/log.cjs record --type=conformance_review --command=check --proj
 
 ---
 
+## 本体语义关系门禁
+
+在其他质量检查前必须运行：
+
+```bash
+node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<变更名称> --profile=<simple|full|strict>
+node skywalk-sdd/log.cjs semantic-check --project=. --change=<变更名称> --profile=<simple|full|strict>
+```
+
+- `simple` 必须阻断 STMT 无 AC；没有 design/tasks 时跳过对应链路，不得误报。
+- `full` 必须阻断 STMT→AC→Design→Task 任一断链。
+- `strict` 在 full 基础上要求完整来源字段并提升可选警告。
+- 所有 profile 都必须阻断重复人工锚点、UUID 缺失/非法、跨 Change 或 Archive 的实体 UUID 误复用、版本 UUID 重用、版本谱系断裂、悬空引用、非法 domain/range 和 Task 依赖成环。
+- `added` 必须使用全新实体/版本 UUID；`modified/removed` 必须复用实体 UUID并指向直接前序版本；`unchanged` 必须复用历史实体和版本 UUID且不得复制历史正文。
+- 文件观察结果只能作为快速上下文，check 必须重新全量 semantic-reconcile。
+
 ## Guardrails
 
 - Check 是**只读检查**操作，不修改任何文档内容

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

@@ -164,6 +164,15 @@ design.md 中若使用 version 正则约束（如格式校验 `^\d+\.\d+\.\d+$`
 
 ---
 
+## 本体语义生成契约
+
+- 写入与当前 spec 一致的 `capability-id`。
+- 每个独立设计单元必须使用 `DES-<CAPABILITY>-NNN`；新增前按当前最大序号 + 1 分配，修改时复用原 ID。
+- 每个 DES 必须同时写 `entity-id`、`version-id`、`delta-state` 和按需的 `predecessor-version`；新增用 `semantic-identity --delta-state=added`，修改时复用实体 UUID 并生成新版本 UUID。
+- 每个 DES 必须通过 `**realizes**: STMT-*` 显式引用一个或多个真实 STMT。
+- 不得仅凭文本相似创建 realizes；没有上游 STMT 时必须标记 unresolved。
+- 生成结束后必须运行 `node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<name>`。
+
 ## Guardrails
 
 > 完整 ⛔ 强制项勾选清单见 `./checklist.md`「Guardrails ⛔ 强制项」。核心红线：

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

@@ -202,6 +202,16 @@ openspec instructions proposal --change "<name>" --json
 
 ---
 
+## 本体语义生成契约
+
+- 创建 Change 时必须写入 `change-id: CHG-<CHANGE-SLUG>`；重新编辑时不得修改已有 Change ID。
+- 每个新增 Capability 必须写成 `[CAP-<CAPABILITY>] <slug>: <说明>`。
+- 修改既有 Capability 时必须复用已有 CAP ID，不得修改或重新分配已有实体 ID。
+- 分配新 CAP ID 前必须扫描当前 proposal 和归档中的显式编号；不得只凭标题认定跨 Change 同一性。
+- 每个 Change/Capability 同时写人工锚点、`entity-id`、`version-id` 和 `delta-state`。新增时必须调用 `node skywalk-sdd/log.cjs semantic-identity --delta-state=added`，不得手写或复制 UUID。
+- 修改既有 Capability 时调用 `semantic-identity --delta-state=modified --entity-id=<历史实体UUID> --predecessor-version=<直接前序版本UUID>`；复用实体 UUID，但必须生成新版本 UUID。
+- 本阶段只声明 Change 和 Capability，不得提前生成 STMT、AC、DES 或 TASK 事实。
+
 ## Guardrails
 
 > 完整 ⛔ 强制项勾选清单见 `./checklist.md`「Guardrails ⛔ 强制项」。核心红线：

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

@@ -176,6 +176,17 @@ 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。
+- 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>`，根据诊断修复缺号、重号和悬空引用。
+
 ## Guardrails
 
 > 完整 ⛔ 强制项勾选清单见 `./checklist.md`「Guardrails ⛔ 强制项」。核心红线：

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

@@ -193,6 +193,15 @@ 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>`。
+
 ## Guardrails
 
 > 完整 ⛔ 强制项勾选清单见 `./checklist.md`「Guardrails ⛔ 强制项」。核心红线：