kld-sdd 2.5.0 → 2.5.2

package/templates/hooks/codebuddy/settings.json

@@ -0,0 +1,72 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-prompt.cjs\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-skill-apply-gate.cjs\""
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-pre-tool.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-apply-test-gate.cjs\""
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-apply-gate.cjs\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-post-tool.cjs\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-apply-test-gate.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-stop.cjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/openspec/design.md

@@ -1,3 +1,7 @@
+---
+capability-id: "CAP-<CAPABILITY>" # 必须与对应 spec.md 一致
+---
+
 # 局部技术实现方案 - [Capability 名称]
 
 > **定位**：单一 Capability 的业务维度技术实现方案
@@ -8,6 +12,20 @@
 
 ---
 
+## 0. 本体语义锚点
+
+<!-- 每个独立设计单元创建一个 DES；修改既有设计时复用原 ID -->
+
+### [DES-<CAPABILITY>-NNN] <!-- 设计单元名称 -->
+- **entity-id**: <UUID>
+- **version-id**: <UUID>
+- **delta-state**: added
+- **predecessor-version**: 无
+- **realizes**: STMT-<CAPABILITY>-NNN
+- **设计范围**: <!-- 本设计负责实现的局部范围 -->
+
+---
+
 ## 1. 字段完整性追溯表
 
 > **⛔ 核心红线**：用户在 Spec 中输入的所有字段必须在此表中体现，严禁无故丢弃！

package/templates/openspec/proposal.md

@@ -1,5 +1,11 @@
 ---
 # 【用户选择配置 - 由 /opsx:propose 引导填写】
+change-id: "CHG-<CHANGE-SLUG>" # 创建时生成，后续不得修改
+entity-id: "<UUID>" # Change 的全局逻辑实体 UUID，added 时生成
+version-id: "<UUID>" # 本次 Change 版本 UUID
+delta-state: "added"
+predecessor-version: "" # added 留空；modified/removed 指向直接前序版本
+mode: "" # full=分 Capability 产物，simple=根目录精简产物
 test-strategy: "" # tdd=测试先行, impl-first=实现优先, none=无测试
 ---
 
@@ -7,7 +13,7 @@ test-strategy: "" # tdd=测试先行, impl-first=实现优先, none=无测试
 
 > **定位**：变更的业务意图（Why）与上下文总览
 >
-> **可选性**：【可跳过，直入spec】若跳过，必须将"影响范围"在 specs 中补齐
+> **必需性**：ontology v2 新产物必须保留 proposal，用于承载 Change/Capability 身份和 profile；旧 proposal-less Simple 只能兼容扫描，不能直接归档为 confirmed
 
 ---
 
@@ -41,11 +47,19 @@ test-strategy: "" # tdd=测试先行, impl-first=实现优先, none=无测试
 
 ### 3.1 新增能力
 <!-- 每个能力会创建 specs/<name>/spec.md，使用 kebab-case 命名 -->
-- `<capability-name>`: <能力简要描述>
+- [CAP-<CAPABILITY>] `<capability-name>`: <能力简要描述>
+  - **entity-id**: <UUID>
+  - **version-id**: <UUID>
+  - **delta-state**: added
+  - **predecessor-version**: 无
 
 ### 3.2 修改能力
-<!-- 仅当已有能力的需求级别变更时填写，检查 openspec/specs/ 现有规格 -->
-- `<existing-name>`: <修改什么需求>
+<!-- 修改既有能力必须复用原 CAP ID，不得重新编号 -->
+- [CAP-<EXISTING>] `<existing-name>`: <修改什么需求>
+  - **entity-id**: <复用历史 UUID>
+  - **version-id**: <新 UUID>
+  - **delta-state**: modified
+  - **predecessor-version**: <直接前序 version UUID>
 
 ---
 
@@ -103,5 +117,4 @@ test-strategy: "" # tdd=测试先行, impl-first=实现优先, none=无测试
 > - [ ] 逻辑链路已闭环
 > - [ ] 受影响模块已明确
 > - [ ] 依赖关系已梳理
-> - [ ] 若跳过本文档，影响范围已在 specs 中补齐
-> - [ ] 能力分解章节已明确列出所有能力
+> - [ ] 能力分解章节已明确列出所有能力

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-apply/SKILL.md

@@ -29,7 +29,7 @@ allowed-tools:
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
-> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
 > - 阶段开始 / 阶段结束 / `task_update` / `ai_adoption_review` / `worktree_finish` 的**完整命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
@@ -115,7 +115,7 @@ openspec list --json
 ### 1.2 【Check 门禁检查】验证质量门禁状态
 
 > **⛔ 强制门禁**：apply 阶段开始前，必须确认 check 阶段已完成。这是 SDD 流程的关键质量保障。
-> 详细检查步骤、判定与门禁体系说明见 `./checklist.md`「§1.2 Check 门禁」。未完成强制拒绝，与 `sdd-apply-gate.cjs` Hook 形成双重保障。
+> 详细检查步骤、判定与门禁体系说明见 `./checklist.md`「§1.2 Check 门禁」。未完成强制拒绝。${HOOK_GATE_DESCRIPTION}
 
 ### 1.5 【本地并行】Worktree 与工作区（建议性策略）
 
@@ -230,7 +230,7 @@ g. **继续下一个层级** — 重新检查 DAG，找出依赖已满足的下
 
 ### 6.0 【条件必做】单元测试真实执行（`test-strategy` 非 `none`）
 
-当 `proposal.md` 的 `test-strategy` 为 **`tdd`** 或 **`impl-first`** 时，在结束 apply 或执行 §6.1 收尾之前，必须真实运行单元测试并留 telemetry 证据。**详细执行要求与证据形式见 `./reference.md`「§6.0」+ `./checklist.md`「§6.0 单元测试真实执行自检」**。Claude Code 的 `sdd-apply-test-gate.cjs` 会在 `log.cjs end`、`apply-worktree-finish`、会话 Stop 时自动校验；无证据则阻断。
+当 `proposal.md` 的 `test-strategy` 为 **`tdd`** 或 **`impl-first`** 时，在结束 apply 或执行 §6.1 收尾之前，必须真实运行单元测试并留 telemetry 证据。**详细执行要求与证据形式见 `./reference.md`「§6.0」+ `./checklist.md`「§6.0 单元测试真实执行自检」**。${HOOK_GATE_DESCRIPTION}
 
 ### 6.1 【条件必做】Worktree 收尾（仅当 §1.5 已创建 worktree）
 
@@ -247,11 +247,11 @@ g. **继续下一个层级** — 重新检查 DAG，找出依赖已满足的下
 
 > 完整 ⛔ 强制项勾选清单见 `./checklist.md`「Guardrails ⛔ 强制项」。核心红线：
 
-- **⛔ Check 门禁检查**：apply 前必须确认 check 已完成；未完成强制拒绝，与 `sdd-apply-gate.cjs` Hook 双重保障。
+- **⛔ Check 门禁检查**：apply 前必须确认 check 已完成；未完成强制拒绝。${HOOK_GATE_DESCRIPTION}
 - **⛔ 渐进式加载 + 隔离红线**：只加载当前 Capability 的四文档链，禁止加载同级其他 Capability 的文档。
 - **⛔ DAG 依赖拦截**：执行任务前必须检查依赖，前置未完成必须拦截。
 - **⛔ 编译检查门禁**：每完成一个任务后必须运行编译检查，编译失败禁止标记已完成。
-- **⛔ 测试执行门禁**：根据 `test-strategy` 决定（tdd=强制, impl-first=强制补跑, none=跳过）；须真实执行并留 telemetry，`sdd-apply-test-gate` 校验非占位数据。
+- **⛔ 测试执行门禁**：根据 `test-strategy` 决定（tdd=强制, impl-first=强制补跑, none=跳过）；须真实执行并留 telemetry。${HOOK_GATE_DESCRIPTION}
 - **⛔ 必须实时更新任务状态**：每完成一个任务立即改 tasks.md，两种格式同步。
 - **Git 只读策略**：禁止为了度量自动初始化 Git、创建分支或提交 commit；非 Git 项目用 `vcs_mode=no-git` 继续执行。
 - **⛔ Step 0.1 隔离校验必做**：建 worktree / 建议分支名前必须完成 proposal + 跨 cap spec 依赖校验并输出报告。

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

@@ -29,7 +29,7 @@ allowed-tools:
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
-> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
 > - 阶段开始：`node skywalk-sdd/log.cjs start --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
@@ -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

@@ -39,7 +39,7 @@ allowed-tools:
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
-> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）** — 阶段开始 / 阶段结束**命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
 
@@ -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-explore/SKILL.md

@@ -20,7 +20,7 @@ allowed-tools:
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
-> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
 > - 阶段开始：`node skywalk-sdd/log.cjs start --command=explore --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）

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

@@ -31,7 +31,7 @@ allowed-tools:
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
-> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）** — 阶段开始 / 阶段结束**命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
 
@@ -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-rules/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: opsx-rules
+description: "规则生成技能 - 扫描项目生成 5 主题 Agent 规则，或对比现有规则输出更新建议"
+argument-hint: "[generate|review] [--agent <id>]"
+license: MIT
+compatibility: 无外部依赖；opencode 接线需项目存在或可创建 opencode.json。
+metadata:
+  author: sdd-team
+  version: "1.0"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+---
+
+你是一个 SDD 项目规则生成与维护专家。激活本技能后，你将扫描项目事实，为已部署的 Agent 生成或审查规则文件。
+
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - ${SHELL_GUIDANCE}
+> - **本技能不写入 SkyWalk Telemetry**（与 `opsx-knowledge` 同属辅助技能，不走 `log.cjs start/end`）。
+
+---
+
+## 技能定位
+
+| 维度 | 内容 |
+|------|------|
+| 核心问题 | 各 Agent 的规则文件在哪里、格式如何、是否与项目事实一致 |
+| 关键输出 | generate：按 Agent 落位的 5 主题规则文件；review：更新建议表 |
+| 操作类型 | generate 写入新规则；review 默认只读，确认后才写入 |
+
+---
+
+## 启动流程
+
+### 1. 检测已部署 Agent 与运行模式
+
+扫描以下目录，记录存在的 Agent（`--agent <id>` 可过滤为单个）：
+
+| Agent id | 检测路径 |
+|----------|----------|
+| cursor | `.cursor/` |
+| claude | `.claude/` |
+| codebuddy | `.codebuddy/` |
+| qoder | `.qoder/` |
+| opencode | `.opencode/` |
+| kunlunzhima | `.kunlunzhima/` |
+| workbuddy | `.workbuddy/` |
+| codex | `.agents/` |
+
+**模式判定**（参数优先，否则自动）：
+- 显式 `generate` → 生成模式
+- 显式 `review` → 审查模式
+- 未指定：任一已选 Agent 的规则目录已有文件 → **review**；否则 → **generate**
+
+规则目录与格式详见 `reference.md` 落位矩阵。**KunlunZhima 注意**：目录是 `.kunlunzhima/.rules/`（点前缀），不是 `rules/`。
+
+### 2. 轻量项目扫描（generate 与 review 共用，不落盘）
+
+借鉴 codebase-map 三视角，只读扫描：
+
+| 视角 | 探测目标 |
+|------|----------|
+| STACK | `package.json` / `pom.xml` / `pyproject.toml` / `go.mod` / `Cargo.toml`；构建命令 |
+| STRUCTURE | 顶层目录职责、入口文件（`bin/`、`src/`、`lib/`、`app/`） |
+| CONVENTIONS | ESLint/Prettier/Ruff 配置；`test/` 目录与框架；`git log --oneline -20` 提交风格 |
+
+扫描结果作为 5 主题规则的正文依据，禁止编造与仓库不符的内容。
+
+### 3a. generate 模式
+
+对 Step 1 检测到的每个 Agent：
+
+1. 读取 `reference.md` 中该 Agent 的 `rulesDir` / `rulesFormat` / `rulesWiring`
+2. 按 5 主题（architecture / coding-style / testing / database-safety / git-commit）生成内容
+3. 按格式模板写入规则文件（见 `reference.md`）
+4. **已有同名文件 → 跳过**，提示用户改用 review 模式
+5. **接线**（仅 wiring ≠ none 的 Agent）：
+   - `opencode-config`：保守合并 `opencode.json` 的 `instructions` 数组（只增不删）；优先指向已有 `.claude/rules/*.md`
+   - `agents-md`：在 `AGENTS.md` 用 `<!-- kld-sdd-rules:start/end -->` marker 追加/替换规则章节
+   - `context-file`：在 WorkBuddy 上下文文件加一行规则目录索引（见 reference.md）
+
+### 3b. review 模式
+
+1. 读取各 Agent 现有规则文件
+2. 与 Step 2 扫描事实对比，输出建议表：
+
+| 文件 | 主题 | 建议类型 | 依据 |
+|------|------|----------|------|
+| （路径） | architecture 等 | 新增 / 修订 / 过期 | 具体扫描证据 |
+
+3. 使用 **AskUserQuestion** 让用户确认要应用的项
+4. **未经确认不写文件**
+
+### 4. 输出报告
+
+```markdown
+## opsx-rules 执行报告
+
+| Agent | 模式 | 写入/建议文件数 | 接线 |
+|-------|------|----------------|------|
+| ... | generate/review | N | 无/opencode.json/AGENTS.md |
+
+### 详情
+- （列出路径与操作摘要）
+
+### 后续
+- 规则内容可手工微调；再次变更后运行 `/opsx-rules review`
+- OpenCode 用户：确认 `opencode.json` instructions 已包含规则路径
+```
+
+---
+
+## Guardrails
+
+- **review 模式未经用户确认不写文件**
+- **generate 模式不覆盖已有同名规则文件**（存在即跳过 + 提示 review）
+- **opencode.json 合并只增不删**；写前提示用户备份已有配置
+- **AGENTS.md 追加用 managed marker**，存在 marker 则整块替换（幂等）
+- **规则内容来自扫描证据**，禁止编造项目不存在的框架或命令
+
+---
+
+## 渐进披露
+
+- **Read `reference.md`** — 落位矩阵、格式模板、5 主题骨架、接线示例
+- **Read `checklist.md`** — generate/review 前后检查项

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

@@ -0,0 +1,27 @@
+# opsx-rules 检查清单
+
+## generate 前
+
+- [ ] 工作目录为项目根
+- [ ] 已检测存在的 Agent 目录
+- [ ] 已完成 Step 2 轻量扫描（STACK / STRUCTURE / CONVENTIONS）
+- [ ] 目标 Agent 规则目录无同名文件（有则改 review）
+
+## generate 写后
+
+- [ ] 5 主题文件均已写入（或按 Agent 格式合并）
+- [ ] frontmatter 符合 reference.md 模板
+- [ ] KunlunZhima 路径为 `.kunlunzhima/.rules/` 而非 `rules/`
+- [ ] opencode.json / AGENTS.md 接线已完成（若 wiring 非 none）
+- [ ] 未覆盖用户已有非受管文件
+
+## review 前
+
+- [ ] 已读取现有规则文件
+- [ ] 已完成 Step 2 扫描
+- [ ] 建议表已输出（文件 / 主题 / 类型 / 依据）
+
+## review 写后
+
+- [ ] 用户已通过 AskUserQuestion 确认
+- [ ] 仅写入确认项