kld-sdd 2.5.0 → 2.5.2

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

@@ -0,0 +1,124 @@
+# opsx-rules 参考 — 落位矩阵与格式模板
+
+> **权威源说明**：本文件是 skill **运行时**的落位矩阵真相源（部署到目标项目后无法 `require` kld-sdd 的 `lib/`）。`lib/tool-profiles.js` 中的 `rulesDir` / `rulesFormat` / `rulesWiring` 为 **init 契约与测试断言**；变更时须与本表同步，以本表为准写入规则文件。
+
+## 落位矩阵
+
+| Agent | rulesDir | 格式 | frontmatter | 原生加载 | 接线 |
+|-------|----------|------|-------------|----------|------|
+| cursor | `.cursor/rules/` | `.mdc` | description / globs / alwaysApply | ✅ | 无 |
+| claude | `.claude/rules/` | `.md` | 可选 paths（glob 列表） | ✅ | 无 |
+| codebuddy | `.codebuddy/rules/` | `.md` | 无 | ✅ | 无 |
+| qoder | `.qoder/rules/` | `.md` | 可选 trigger | ✅ | 无 |
+| kunlunzhima | **`.kunlunzhima/.rules/`** | `.mdc` | description / alwaysApply / enabled / updatedAt / provider | ✅ | 无 |
+| opencode | 无独立目录 | `.md` | 无 | ❌ | `opencode.json` instructions |
+| codex | 无独立目录 | — | — | ✅（读 AGENTS.md） | AGENTS.md managed marker |
+| workbuddy | `.workbuddy/rules/` | `.md` | 无 | ⚠️ 待验证 | 上下文文件索引行兜底 |
+
+> **KunlunZhima 证据**：样例目录 `.kunlunzhima/.rules/*.mdc`，frontmatter 含 IDE 管理字段 `enabled`、`updatedAt`、`provider`（无 `globs`）。
+
+## 格式模板
+
+### mdc（Cursor）
+
+```markdown
+---
+description: <一句话描述>
+globs:
+alwaysApply: true
+---
+
+<正文>
+```
+
+### mdc-kunlun（KunlunZhima）
+
+```markdown
+---
+description: <一句话描述>
+alwaysApply: true
+enabled: true
+updatedAt: <ISO8601 生成时间>
+provider:
+---
+
+<正文>
+```
+
+### md + paths（Claude Code，可选按路径触发）
+
+```markdown
+---
+paths:
+  - "src/**/*.ts"
+---
+
+<正文>
+```
+
+无 paths 时 Claude 会话启动即加载。
+
+### md + trigger（Qoder，可选）
+
+```markdown
+---
+trigger: always_on
+---
+
+<正文>
+```
+
+### 纯 md（CodeBuddy / WorkBuddy）
+
+```markdown
+<正文>
+```
+
+## 5 主题内容骨架
+
+| 主题 | 文件名 | 扫描依据 | 生成要点 |
+|------|--------|----------|----------|
+| 架构规范 | `architecture` | 目录分层、模块边界、入口 | 分层约定、禁止循环依赖、新代码落位 |
+| 编码规范 | `coding-style` | 语言、lint、缩进 | 命名、缩进、注释语言、CommonJS/ESM |
+| 测试约定 | `testing` | test 目录、框架 | 测试命令、命名、TDD 期望 |
+| 数据安全 | `database-safety` | ORM/迁移目录 | 无 DB 时降级为「禁止危险文件操作/敏感数据提交」 |
+| Git 提交 | `git-commit` | git log 风格、CI | 提交前确认、message 风格、禁止 force push |
+
+## OpenCode 接线
+
+优先复用已有 `.claude/rules/`：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [".claude/rules/*.md"]
+}
+```
+
+无 Claude 规则时，写入 `.opencode/rules/*.md` 并 instructions 指向该路径。合并：已有 `instructions` 数组去重追加，其他键不动。
+
+## Codex / AGENTS.md 接线
+
+```markdown
+<!-- kld-sdd-rules:start -->
+## 项目规则
+
+### 架构
+...
+
+### 编码
+...
+<!-- kld-sdd-rules:end -->
+```
+
+存在 marker 则整块替换，幂等。
+
+## WorkBuddy 兜底
+
+写入 `.workbuddy/rules/*.md`，并在项目上下文文件（若存在）追加：
+
+```markdown
+项目规则见 `.workbuddy/rules/` 目录。
+```
+
+验证：运行 CodeBuddy `/memory` 或查官方 docs。

package/templates/skills/kld-sdd/opsx-spec/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 命令模板」。
 
@@ -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

@@ -40,7 +40,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 命令模板」。
 
@@ -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 ⛔ 强制项」。核心红线：

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

@@ -26,7 +26,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=test --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）